Shout out to http://cht.sh , which could be used without installing anything: curl cht.sh/tr
Been using this for years, it's great!
Note that https://cheat.sh works too (I find that easier to remember than cht.sh)
TLDR pages: Simplified, community-driven man pages
71–80 of 179 posts
Re: TLDR pages: Simplified, community-driven man pages
#72Shout out to http://cht.sh , which could be used without installing anything: curl cht.sh/tr
Thank you, this is amazing! Simple ZSH/Bash function if anyone wants it:
cheat () {
curl "cheat.sh/$1"
}Re: TLDR pages: Simplified, community-driven man pages
#73A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
I use manpages frequently, seems easier to learn how to read manpages than create a new project dedicated to adding examples to manpages. I find them incredibly user friendly, but I cared enough to learn how to use them.
Re: TLDR pages: Simplified, community-driven man pages
#74Earlier quoted context omitted.
The maintainer of the manpages project, Michael Kerrisk, is quite responsive and interested in improvements. I've generally found the maintainers of other software to be receptive to documentation patches, as well.
I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.
> I'm not sure what this has to do with Kerrisk
Because the man-pages project that he maintains provides the largest set of third-party manpages (outside the project trees themselves). The majority of manpages live either in the project they document or in the man-pages project.
> I don't know why this has to be met with so much friction.
The point of this thread is that it will often not be met with friction. Examples should be in a combination of the summary and examples sections of the manpages. (Distinct modes of operation belong in the summary, more fine-grained examples go in the examples section.
Re: TLDR pages: Simplified, community-driven man pages
#75Earlier quoted context omitted.
I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.
Just start with the assumption that no one understands how to read a man page and how to translate that into a full command line operation. A simple example goes A LONG WAY.
Back in 2000-2005 I worked on the SQL Server documentation.
If I remember correctly, when we instrumented the docs we found that the VAST majority of users skipped over all the descriptions and parameter definitions, and jumped straight to the examples of usage. Turns out observation is the fastest way to learn/remember. We redoubled our efforts to include examples of more obscure usage patterns, rather than relying on wordy explanations.
Re: TLDR pages: Simplified, community-driven man pages
#76A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
> The maintainers would be thrilled to have them.
Would they?
The tldr.sh site prominently offers a sample of usage examples for a command; tar specifically. If one checks the tar man page there are no examples. This is policy, apparently promulgated by GNU et al. in favor of "info". I haven't the time right now to hunt down the official position, but here[1] is a SO discussion.
Should this TLDR thing correct that long standing mistake I'm all for it. Also, info is one of the most hostile TUI programs I've ever encountered and I resent using it.
[1] https://unix.stackexchange.com/questions/306189/why-dont-man...
Re: TLDR pages: Simplified, community-driven man pages
#77Earlier quoted context omitted.
How is this "rapidly decaying third-party documentation" in any way that man isn't?
man is universally known in the industry, and supported (to some extent, at least) by project authors/maintainers; this project will be forgotten by almost everyone (and start decaying) as soon as this post is off the front page here.
They're often used, but I suspect most people who read them don't know how to write or even modify a man page. (What format is it?) Also, Stack Overflow probably gets more traffic.
Whether documentation gets read or not probably depends on its Google ranking more than anything.
Re: TLDR pages: Simplified, community-driven man pages
#78This tends to be more of an issue with GNU programs that have info pages. You are not really supposed to use the man pages in that case. The info pages for GNU tar have lots of examples scattered throughout: * http://www.gnu.org/software/tar/manual/ BSD systems, for example, have much better man pages that have an actual "EXAMPLES" section near the bottom.
The thing is - I don't want to go to some website or pour through pages and pages of documentation when I want to do one specific thing. I want to do something and move on with my life. My job isn't learning every command line switch under the job.
Re: TLDR pages: Simplified, community-driven man pages
#79Neither this, nor the traditional man page list of options is useful on its own. You need a detailed reference of the things you can do, and then you need examples for how to pull those things together in common usages. For a code equivalent, Rust encourages function level documentation. This gives you detailed information on the full API surface and is vital, but if you only had that you wouldn't know where to start…
tldr doesn't remove man pages. You're free to check the man page for what whatever flags used in a command in tldr mean.
Re: TLDR pages: Simplified, community-driven man pages
#80A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
No, they serve two different purposes.
Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept.
This is something different. It's a tutorial of how to do the most common things using that tool.
It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples?
Unless you've read formal specs for other languages with a similar paradigm before, it's way easier to learn from examples first, which gets you to the level of understanding where the formal specs start to make sense.
Improvements to man pages should be made, but not at the cost of beginner-friendly projects.