[HN Gopher] TLDR pages: Simplified, community-driven man pages
___________________________________________________________________
TLDR pages: Simplified, community-driven man pages
Author : lordgrenville
Score : 381 points
Date : 2020-01-22 13:15 UTC (9 hours ago)
(HTM) web link (tldr.sh)
(TXT) w3m dump (tldr.sh)
| FabHK wrote:
| FWIW, can be installed on macOS with brew: brew
| install tldr
|
| EDIT to add: and so can the faster (caching) Rust version (note:
| install one or the other, not both, since they use the same
| `tldr` command) brew install tealdeer
| sammorrowdrums wrote:
| Yeah cargo install tealdeer was worthwhile. Really good.
| ashton314 wrote:
| Woah. That's way faster. Thanks for mentioning this! I'll
| switch all my machines over to tealdeer now.
| [deleted]
| gyoza wrote:
| Am I the only one who thinks... This is based on npm and this is
| the sole reason to not even consider using it??
| ausjke wrote:
| tldr is the tool I recommend to linux beginners, so they're not
| afraid of CLI
| [deleted]
| BrianB wrote:
| I would still reference man pages to see what the flags do in the
| tldr examples.
| justinhensley wrote:
| tldr has been my daily driver for 1-2 years now, almost replacing
| man entirely. The community has contributed very useful examples.
|
| I go to man once or twice for tools that are entirely new to me.
| Then, I use tldr until I have muscle memory or using a feature
| that is new to me.
| 1MachineElf wrote:
| Very useful. Thank you for supporting multiple platforms, and the
| MIT license.
| overcast wrote:
| http://bropages.org/ is usually my goto. I learn by example, so
| naturally I despise man pages, and this makes it tolerable.
| upofadown wrote:
| This 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.
| Brave-Steak wrote:
| 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.
| b5n wrote:
| It's just text - so all the text
| formatting/search/manipulation commands are available to you.
| Manpages are really easy to use and navigate, given you use
| them how they're meant to be used.
|
| man man | grep -A 10 EXAMPLES
|
| man tar | awk -F , '/-v,/ {print $2}'
| Brave-Steak wrote:
| Or I type 'tldr' and don't waste my time? I swear to god,
| engineers are so focused on efficiency and yet are so eager
| to waste so much time and effort on repeating crap like
| this unnecessarily. Just think about the context switches
| alone necessary to type all that.
| b5n wrote:
| It was easy for me, no context switching. I assume basic
| use of grep and awk shouldn't be too much of a stretch
| for most Linux savvy engineers.
|
| I'm happy TLDR fits your needs. I was just demonstrating
| how I use manpages effectively in hopes it might assist
| you.
| Brave-Steak wrote:
| 1) Bullshit. 2) And the waste of time typing all of that?
| I'd rather just not.
| b5n wrote:
| Is it insane to think that some engineers might have a
| basic grasp of incredibly powerful and useful tools
| developed over 40 years ago?
|
| Maybe you're of the opinion we should equip all race cars
| with fully automatic transmissions, ABS, and rev limiters
| because it's easier for inexperienced drivers to learn
| on?
|
| awk is > 40 years old, grep was released almost 45 years
| ago.
|
| These tools have endured because they work, just like
| manpages.
|
| TL;DR: It's okay if you have decided to allocate your
| mental bandwidth elsewhere, but your comments are wholly
| ignorant.
| Brave-Steak wrote:
| And your comments are infuriatingly dismissive. Typical
| of a software engineer to not give a shit about
| accessibility, ease of use, _actual_ efficiency, tools
| getting out of the way of people who want to do their
| actual jobs, etc.
|
| tl;dr You're arrogant and elitist and think everybody
| should work like you do.
| avsteele wrote:
| Examples are great because they give the curious user an idea of
| how to use the command in new ways.
| b3kart wrote:
| Shout out to http://cht.sh, which could be used without
| installing anything: curl cht.sh/tr
| zackmorris wrote:
| Wow that's pretty great. There are so many powerful console
| utilities with overly opaque manuals that make them hard to
| jump into when you just want to do a simple thing. Compare
| these for example:
|
| http://cht.sh/jq
|
| https://www.systutorials.com/docs/linux/man/1-jq/
| streb-lo wrote:
| For .bash/.zshrc:
|
| function cht() { curl cht.sh/$1 }
| ausjke wrote:
| amazing, just tested it out, i hope it can add devdocs.io
| support, and update vim plugin to newer ones. this will likely
| replace my tldr soon
| ausjke wrote:
| I have yet to see node.js API support from any REPL or shell
| or vim or tldr, the only option is access it from browser,
| which is not enough.
|
| https://zealdocs.org is another great source, similar to
| https://devdocs.io
| toomim wrote:
| Grandparent just showed how to use it on the command-line,
| with curl.
| [deleted]
| GordonS wrote:
| Been using this for years, it's great!
|
| Note that https://cheat.sh works too (I find that easier to
| remember than cht.sh)
| SamBam wrote:
| Awesome. It looks like for the shell commands it uses content
| straight from TLDR, right?
|
| e.g. http://cht.sh/tar
| ivanfon wrote:
| Thank you, this is amazing! Simple ZSH/Bash function if anyone
| wants it: cheat () { curl "cheat.sh/$1"
| }
| [deleted]
| hyperpallium wrote:
| How can I remove the colors from the output? It's hard to read
| on mobile (termux).
| stared wrote:
| I would be happy to see such a thing taking off.
|
| Typical man pages are well, like learning a language by studying
| a dictionary, alphabetically. It may contain all information, but
| a clear F on UX. Some packages get slightly better with starting
| from the most common use cases, with examples (and digestible
| errors).
|
| However, I would be even more interested to see what is the
| actual usage pattern (e.g. from .bash_history / .zsh_history). Do
| you know any datasets with longer such?
| reaperducer wrote:
| _It may contain all information, but a clear F on UX._
|
| What I find annoying is the number of command line programs
| that don't even have man pages anymore. Or maybe that's just an
| artifact of installing them with brew?
|
| What I find interesting is that for the most part (there are
| exceptions), the older the man page, the more useful it is.
| Realistic examples. Succinct descriptions. User-friendly
| terminology. Too many of the newer man pages seem inflated and
| full of jargon to make themselves seem important or worthy.
| wongarsu wrote:
| I don't think I've encountered anything on Ubuntu that
| doesn't have a man page, but it also seems like many of the
| man pages are created or improved by Debian or
| Ubuntu/Canonical. Homebrew probably wouldn't have those.
| Athas wrote:
| I have added packages to Homebrew, and they install man pages
| when available. Homebrew provides a pretty simple mechanism
| for doing so. The problem is that many projects just prefer
| web documents to man pages, likely because the man page
| tooling is not great.
| dickeytk wrote:
| and because it doesn't work on windows
| bauerd wrote:
| Some ecosystems even eschew manpages. For example, I wouldn't
| know how to ship manpages as part of a Ruby gem, it's
| discouraged iirc
| SnowflakeOnIce wrote:
| > What I find annoying is the number of command line programs
| that don't even have man pages anymore. Or maybe that's just
| an artifact of installing them with brew?
|
| A messed-up MANPATH environment variable can also cause man
| pages to not be found. In 'man' used on many flavors of
| Linux, MANPATH behaves differently from, say, PATH: an empty
| colon-delimited section means something like "use the
| system's regular 'man' configuration for finding man pages".
| Without that, it seems like a bad MANPATH setting will cause
| default mannpages not to be found.
| stared wrote:
| Also, I see that there are other similar projects:
| https://www.ostechnix.com/3-good-alternatives-man-pages-ever...
| downerending wrote:
| It's true that the man pages aren't meant to be the primary
| method of learning Unix. But they are indeed a spectacular and
| irreplaceable resource.
|
| One of the best things that ever happened in my career was
| having a desk across from the entire SunOS manual set. I'd pull
| them down one at a time and read them, cover to cover. It paid
| off, big time, and I strongly recommend it.
| lynndotpy wrote:
| I'm also interested in a `.bash_history` kind of dataset. If
| you become aware of this, I'd love to see such a thing.
| CaptArmchair wrote:
| Man pages are intended to be an exhaustive description of the
| individual options, switches and command arguments and what
| they do; but they won't tell you how to combine those to be
| useful in your particular case. It's up to you to figure that
| out.
|
| tldr caters to an entirely different heuristic: I have this use
| case, give me a list of use cases and the corresponding
| combination of switches, options and arguments for each
| respective use case. tldr won't explain to you what each
| individual switch, option or argument does, turning the
| provided commands into black boxes.
|
| Here's the trade off:
|
| The former has a steep learning curve and figuring out how a
| tool works doesn't solve your immediate problem. But if you
| commit the meaning of switches, options and arguments for
| common tools such as awk, sed, tar, ls,... to memory, you will
| become proficient at solving any problem with a few tools over
| time.
|
| The latter has a low learning curve and you just have to
| copy/paste a command to solve your problem. But tldr won't tell
| you how those switches and options work. And you will just use
| them as incantations that magically help you to solve a limited
| number of cases. If you end up with a use case that isn't
| listed, you are left in the dark as far as tldr is concerned.
|
| So, is tldr a bad tool then? No! If you are confronted with the
| command line sparingly, then tldr helps to lower the bar and
| solve your immediate problem. But if you hope to grow into a
| proficient shell user, then you're still going to have to grok
| the man pages one switch, option and argument at a time.
|
| I'm a polyglot. Studying a language by opening a dictionary and
| starting alphabetically, is arguably, the worst way to get
| there. You would start with learning a set of common words and
| basic grammatical rules, and then expand over time through
| practice and instruction: speaking, reading and writing.
|
| The same applies to command line tools and man pages: they are
| reference materials first and foremost.
| zantana wrote:
| That doesn't preclude them from including examples of the
| most commonly used flags and scenarios.
|
| Man pages for newer tools, like all of the lvm utilities,
| include examples at the end.
|
| I would like to see it similar to what powershell has with
| their examples built into the documentation.
| lordgrenville wrote:
| I frequently use TLDR, and I wouldn't describe it as an
| incantation. It's for the case where, say, I know there's a
| grep flag for inverse match or case-insensitive, but don't
| use it often enough to remember it. It surfaces the
| (community-driven) top use cases, and it's pretty clear from
| the context what the flags are doing. (As seen here:
| https://github.com/tldr-
| pages/tldr/blob/master/pages/common/... ) If I don't see my
| use-case in tldr I'll move on to the man page.
|
| OTOH, sometimes I'll copy-paste some perl or awk dark magic
| from Stack Overflow, and then try modify it piecemeal to fit
| my case. _That 's_ an incantation :)
| CaptArmchair wrote:
| > it's pretty clear from the context
|
| I think that largely depends on who's using the tools and
| how acquainted they are with command line tools. An
| absolute beginner likely will not know what tar's 'f' flag
| does, or assume something else.
|
| > OTOH, sometimes I'll copy-paste some perl or awk dark
| magic from Stack Overflow, and then try modify it piecemeal
| to fit my case. That's an incantation :)
|
| And I absolutely have no qualms doing the same when push
| comes to shove. Ain't nobody always got the time. ;-)
| thrwaway69 wrote:
| I will bite - I have been using linux for 4 years. I have
| used tar a lot and I don't know what v means. I switch
| between -xvf, -xvz, etc.
|
| x - extract | f - file | z - operating on tar.gz or
| similar.
|
| Edit: v - verbose
| b5n wrote:
| man tar | awk -F , '/-v,/ {print $2}'
| [deleted]
| kfrzcode wrote:
| Laziness is surely not always the answer. I advise learning how
| to read man pages. Eating your Wheaties, so to speak.
| stageleft wrote:
| This is very useful. It's essentially command-line cheat sheets,
| which are very handy for cmds you don't use every day.
| codesections wrote:
| I like the _idea_ of tldr pages. Unfortunately, by default, they
| are a bit too slow to display--I know it 's under a second, but
| it's just enough to break my flow.
|
| Fortunately, there are other clients, some of which are __much
| __faster. My current favorite is
| tealdeer:https://github.com/dbrgn/tealdeer
| dbrgn wrote:
| Thanks for the shoutout :) It's funny that my weekend project
| that I wrote to learn Rust suddenly has almost 500 stars on
| GitHub...
| brudgers wrote:
| a lively previous discussion,
| https://news.ycombinator.com/item?id=15779382
| dang wrote:
| Also 2015: https://news.ycombinator.com/item?id=10797303
|
| Related from 2014: https://news.ycombinator.com/item?id=7166257
| ddevault wrote:
| A 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.
| mongol wrote:
| It would be interesting to take a step back and consider what
| man pages actually are. Are they documentation structured in a
| specific way, dating back to Unix origins, or are they what the
| user sees if they type "man command" on the command line?
| Because if we consider the latter, I think it will be much
| easier to see radical improvement of the "man experience"
|
| If I type "man ps" I see Man: find all
| matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
| * ps (1) ps (1p) Man: What manual page do
| you want?
|
| What if I instead saw Man: find all matching
| manual pages (set MAN_POSIXLY_CORRECT to avoid this) *
| ps (1) ps (1.tldr) ps (1p) Man:
| What manual page do you want?
|
| where the man command retrieved that information from the TLDR-
| pages site?
|
| In the last years we have seen many innovative Rust re-
| implementations of classical commands such as cat, find, grep.
| Maybe the man command is next up?
| teddyh wrote:
| man apropos
| topspin wrote:
| > 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...
| JdeBP wrote:
| > _If one checks the tar man page there are no examples._
|
| * https://www.freebsd.org/cgi/man.cgi?query=tar#EXAMPLES
|
| * https://man.openbsd.org/tar#EXAMPLES
|
| * https://illumos.org/man/1/tar#examples
|
| * https://www.ibm.com/support/knowledgecenter/ssw_aix_72/t_co
| m...
|
| * http://osr507doc.sco.com/cgi-
| bin/man?mansearchword=/usr/man2...
|
| You are clearly very limited in your user manuals. (-:
| smhenderson wrote:
| I'm aware of GBU's preference for info but systems vary. Just
| to use your example, I'm typing this on Slackware and when I
| pull up man tar there are three examples, right after
| Synopsis and Description. Examples for extracting, both
| gzipped and regular archives, and creating a tar file are
| given.
|
| And when I shell into an OpenBSD server their man page for
| tar has several examples at the bottom of the page.
|
| Man, IMO, is a lot like Linux distros in that they are not
| all created equal, pull from a lot of different sources and
| can be inconsistent if you're not looking at the correct ones
| for whatever system you are on.
|
| I too think TLDR is a good idea but that's no reason not to
| encourage that some of their work be ported back to man pages
| in their examples' sections.
| topspin wrote:
| A quick survey of GNU tar man pages, by program version and
| the date that appears in the page itself:
| 1.23 March, 2012: no examples (RHEL 6) 1.26
| March, 2015: no examples (OpenSUSE 13.1) 1.26
| February, 2016: no examples (CentOS 7) 1.29 March,
| 2016: limited examples (Ubuntu 1804)
|
| The last has no actual "EXAMPLES" section in the man page;
| only some incidental examples appearing among a discussion
| of "Option styles." I suspect this is also what you see;
| it's in the same position in the page. So there is some
| evidence that examples aren't entirely prohibited in GNU
| man pages, at least in recent years. Progress, I guess. The
| latest work on this man page (release 1.32) shows no
| further progress.
|
| TLDR goes well beyond those incidental examples and is far
| closer to what I'd hope to see; first class, worked example
| forms eagerly supplied. _Without_ suffering info.
| smhenderson wrote:
| Fair enough and as mentioned this was Slackware and the
| maintainer, Patrick, is known to have a fondness for BSD
| so maybe his influence can be seen here.
|
| For what it's worth the Slackware page does have an
| Examples section so it's not exactly what your seeing on
| Ubuntu but the examples themselves may be the same. As
| mentioned there are only three but they are probably the
| three examples needed most by 95% of users.
|
| And, since I wasn't clear in my previous post, I
| absolutely agree about info. It may have been a nice
| thought when hypertext based systems were young and new
| things needed to be tried but it should have quietly died
| by now IMHO.
| dylanz wrote:
| +1 ... we should be working on improving "the actual" man
| pages. There is an "Examples" section in OpenBSD man pages that
| help out quite a bit. I'd rather have one definitive place for
| man pages (rather than many), and I'd rather have them be
| accessible from the OS (and not require an internet
| connection).
| diebeforei485 wrote:
| 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.
| joshklein wrote:
| > they serve two different purposes
|
| I agree, but I'm also painfully aware of man page
| incompleteness every time I'm on a non-OpenBSD system. I'd be
| grateful to anyone who chipped away at proper tagging for any
| GNU software. One should be able to :t to jump to the
| reference for any flag.
| beefhash wrote:
| That's impossible by means of how they're written. GNU
| still cares about operating systems that don't bundle the
| mdoc macros with their troff processor and don't use mandoc
| (which is... exactly only AIX and HP-UX at this point), so
| they write all their text in man so that they render
| correctly everywhere.
|
| For tagging, the formatting would need to be redone to be
| mdoc, which breaks both the OSes mentioned above and would
| be an immensely arduous task at this point. Probably not
| going to happen.
|
| Note GNU and and the Linux man-pages project are mostly
| outliers; everyone else that lives in BSD/illumos land has
| long since moved on to mdoc since like the 80s. See also ht
| tps://www.usenix.org/system/files/login/articles/141-dzons.
| ..
| avodonosov wrote:
| I often have this difficulty with man pages. But man page
| format allows examples, contributing many examples to
| original man pages would make them more accessible.
|
| Also, a gentle, human oriented intro can be a part of man
| page I think.
| Scarblac wrote:
| It would be quite nice to have that quick tutorial in a new
| section at the top of man pages, in addition to what's
| already there.
| Kalq wrote:
| I disagree. Plenty of man pages have very excellent examples
| that serve as a beginner tutorial. Ones that are just as good
| (and easy to understand) if not better than what I've seen
| from TLDR. There's no reason manpages can't be both.
| SaulOfTheJungle wrote:
| > No, they serve two different purposes.
|
| I don't see why they could not serve both purposes.
|
| Man pages should start with a tldr section followed by the
| full reference/spec.
| fhennig wrote:
| Yes, put both things in the man page!
|
| Looking at some examples of tldrs, it mostly boils down to
| the most common use cases as examples. So well written man
| pages already have an "examples" section, and that really
| helps!
| xorcist wrote:
| There's no reason man pages can't be both.
|
| Many man pages contain examples and common usages. See for
| example the rsync man page, with complete examples of how to
| backup common file systems.
| [deleted]
| Brave-Steak wrote:
| Yeah, no. The use cases for man and tldr are completely
| different, and trying to convince every single project to make
| their man pages more friendly to people who just want to get
| their work done is just ... well, an impossible amount of
| effort. tldr coalesces a community around a common goal, and
| they can work towards that goal without fighting hundreds of
| different maintainers on making man pages more accessible.
| bananamerica wrote:
| manpages would be awesome if more pages had examples.
|
| Since they don't, we use bropages, tldr, etc.
| overcast wrote:
| 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.
| spenczar5 wrote:
| Do you have examples of that refusal? I'm unfamiliar.
| edw wrote:
| Based on my experience, the problem may be that man pages
| are often not where one learns how to use a tool. I still
| remember from long, long ago when I told a greybeard that I
| was trying to learn sed by reading the man page. He
| replied, "God help you," and guffawed.
|
| While some man pages have examples, I don't know if man
| page writers see their job as teaching readers how to use a
| utility. The goal of man pages more often seems to be
| _reminding_ a person already familiar with the tool how to
| use a tool.
|
| I'm, umm, _reminded_ of project READMEs. I've come to
| assume that when I go to a project on GitHub, I'm going to
| get everything I need (or pointers to everything I need) to
| get started with a project, but often there's a project web
| site that is intended to serve that purpose. I just ran
| into this yesterday with Falcor.
|
| Not all man pages are like this obviously. Specifically,
| the section three man pages on C functions do a good job
| fully documenting functions.
| kbenson wrote:
| The more complex a tool, the less likely a man page is
| going to be a good way to distill and impart the
| information of how to use it. Bash's mane page is so
| large I can almost never find what I'm looking for.
|
| At the same time, that means a TL;DR type page is also
| likely to be useless. For the vast majority of software
| run from a shell, a man page is sufficient, and examples
| can be (and often are) added to good effect.
|
| I will note that some projects split very large man pages
| into sub-pages, and that can work well. For example, ip,
| and much of the man pages on BSDs that explain how
| different technologies are implemented (for example,
| follow the references in the man page for ifconfig on
| OpenBSD).
| overcast wrote:
| By virtue of the fact that TLDR and bropages exist? People
| are creating 3rd party solutions, because no one does
| anything with man pages.
| vmchale wrote:
| On Linux that has been my experience. man pages on Mac are a
| little better, I've heard the BSDs do better as well.
| jeltz wrote:
| Doesn't each project maintain its own man pages? There is a
| huge variation in quality between them with some being
| excellent while others are lacking.
|
| Have you tried talking to any of the projects?
| fluidcruft wrote:
| Doesn't GNU still scoff at man pages and foist texinfo?
| Honestly who wants to waste their time with roff etc?
|
| The focus has been making it easier for the _developers_ to
| write literally anything. One thing uses sphynx another uses
| man another uses doxygen or what the hell ever. Users aren 't
| developers. This is why everyone ends up on google and ends
| up on stackoverflow or random blog or watching youtube.
|
| The barrier to entry is much lower with some simple markdown
| thing. Hell, I was thinking about how to abuse this thing to
| make my own notes about commands.
| aktau wrote:
| I maintain my man pages in markdown format, and convert
| them to roff at build time. There are plenty of tools that
| can do that: pandoc(1), ronn(1), ...
| munk-a wrote:
| I dunno, the TLDR page highlighted tar which seems a bit odd
| since tar has always gone out of its way to have a very
| strong and useful manpage - specifically having several
| examples[1] at the top of the page before diving into all the
| intricacies of the arguments.
|
| 1. Including tar -cf and tar -xf probably the two you want to
| run in most cases. See: https://linux.die.net/man/1/tar
| JoshTriplett wrote:
| 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.
| overcast wrote:
| 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.
| JoshTriplett wrote:
| > 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.
| usrusr wrote:
| > They know best how it works
|
| But they don't necessarily know best what usage patterns
| work well for people who are not maintainer-level
| experts.
|
| I see a strong case for having separate texts for
| documenting the interface (striving for completeness and
| low redundancy) and introductory teaching. I don't think
| that I'd like seeing each man page prepended with a wordy
| ELIF and two pages of trivial examples. And I'm not
| saying this because I'd not need the ELIF, quite the
| opposite, I just don't think that it would be wise to mix
| them.
|
| Having them maintained in one place, passed through the
| same distribution channels and available on the command
| line, now that would great of course. The minimum almost-
| requirement for a crowdsourcing effort for that content
| could be a contribution licence that is 100% compatible
| with the real thing, not 99%, not 99.99. Just in case.
| tylerchilds wrote:
| 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.
| overcast wrote:
| 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.
| Darkphibre wrote:
| 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.
| [deleted]
| overcast wrote:
| That's EXACTLY what I do. I imagine there are some that
| are great at reading white papers, but I am not one of
| them, and I'm not alone. Experience > Education.
| b5n wrote:
| 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.
| nebulous1 wrote:
| Ideally this information would be controlled by the individual
| package maintainers, I agree.
|
| However, realistically at the moment I don't see man pages
| competing with the spirit of tldr/bro/whatever, and I suspect
| that PRs geared towards making them compete would in fact be
| rejected by most projects.
| nathias wrote:
| it's not the same use-case, manpages are detailed instructions,
| tldr is just the 7 most used commands
| hellcow wrote:
| manpages often have an examples section on OpenBSD showcasing
| different ways to use programs. It can be done...
| Semiapies wrote:
| How is this "rapidly decaying third-party documentation" in any
| way that man isn't?
| glckr wrote:
| 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.
| skybrian wrote:
| 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.
| tyrust wrote:
| man pages are first-party, are they not?
| jlg23 wrote:
| Yes. The given example shows exactly what I would expect in the
| EXAMPLES section of a man page anyways. If not, it's worth a
| patch.
| josephernest wrote:
| 1) Great project!
|
| Is there a simple way to install it without having to install
| Node.js or Haskell or Ruby? (I don't want to install Node.js just
| for it)
|
| Is there a apt-get install tldr
|
| solution on recent Debian / Ubuntu distros _without installing
| another additional package manager_?
|
| I mean even the bash solution: bpkg ...
|
| does not work out of the box.
|
| (bpkg or brew or npm aren't installed by default)
|
| 2) Is TLDR linked with the project cht.sh? e.g curl cht.sh/tar?
| Does it share a common source of documentation are they two
| totally different projects?
|
| 3) Few people won't remember tldr.ostera.io (I won't)... Ok we
| have bookmarks, but still, it would be more convenient if we
| could just do: tldr.sh/tar
| tldr.sh/git_push
|
| instead of having to remember ostera.tldr.io oh no ostera.tldr.sh
| oh no tldr.ostera.sh no...
| dbrgn wrote:
| Regarding 1: Tealdeer provides static binaries for Linux.
| https://github.com/dbrgn/tealdeer/
| presiozo wrote:
| Nice idea. Also, I think that an ELI5 command would be really
| useful, too
| FabHK wrote:
| There was a previous HN discussion of "bro", can anyone comment
| on the differences?
|
| "Bro pages: like man pages, but with examples only"
|
| https://news.ycombinator.com/item?id=7121268
| fredley wrote:
| tldr has a better name.
| stared wrote:
| Was BroPages name the only reason it hasn't gone mainstream?
| capableweb wrote:
| Yes, just like the only reason Facebook went mainstream was
| because of the incredible name.
| FabHK wrote:
| Having skimmed the endless discussion about the "bro" name, I
| have to agree.
| nannal wrote:
| I can think of about four other projects called bro so
| without context the name is fairly useless and it appears
| this is a competitive space, I wouldn't hold much hope for
| the tdlr esc bro
| drdebug wrote:
| man pages sometimes have an EXAMPLES section, may be at some
| point these could be merged (both ways?)
| noodlesUK wrote:
| I think this is an indictment of how awful the man pages are on
| GNU/Linux systems. The man pages within the various *BSDs are a
| fantastic resource, as are their other documentation (e.g., the
| freebsd handbook).
| kccqzy wrote:
| Well, man pages cover more than just command-line utilities.
| These typically go in section 1 only. What about section 2
| (system calls) or section 3 (library functions)? I guess the
| audience of this tool doesn't really need these?
| read_if_gay_ wrote:
| Of course some information will be omitted, that is the entire
| purpose of this tool. What's your point?
| ajsharp wrote:
| This is such a great idea. Praise fucking be.
| nathias wrote:
| I've been using them for a while, they replace/improve man for
| most cases/
| rkangel wrote:
| Neither 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. Rust also has the 'examples' directory (I'm
| talking about a library project) which usually has a few
| executables that use the library.
| Brave-Steak wrote:
| 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.
| omaranto wrote:
| I don't understand why this needs a client. Why not just install
| these as man pages in their own section and read them with man?
|
| EDIT: My idea is of course not new, see
| https://github.com/joelekstrom/tldr-man for a way to convert
| these docs to man pages.
| rgoulter wrote:
| I've not used man enough to know the how to look up a
| particular section.
|
| This is a good opportunity for me to compare the out-of-the-box
| results from tldr vs man:
|
| https://tldr.ostera.io/man
|
| https://linux.die.net/man/1/man
|
| "Why not just install these as man pages in their own section
| and read them with man?" Because downloading the default
| program is much easier, most users aren't that concerned about
| adding a small CLI program on their computer, and most aren't
| that purist about right way to read documentation is through
| manpages.
| omaranto wrote:
| I don't think tldr is a _small_ CLI program unless you
| already have Node.js installed. :)
|
| And I also don't see why installing that is easier than
| installing man pages, if appropriately packaged. (I'm not
| claiming they are currently appropriately packaged, I'm just
| saying that's what they could have done instead of writing a
| client.)
| beart wrote:
| I don't think you need Nodejs.
|
| There are a large number of clients listed here
|
| https://github.com/tldr-pages/tldr#clients
| therealjumbo wrote:
| Debian has a package "tldr" implemented in haskell, that's
| under 1 MB.
| https://packages.debian.org/search?keywords=tldr
|
| I just found that and installed it after reading this
| thread. It looks like on first run, like "tldr tar", it
| calls "git clone" on some repo. Thereafter, other
| incantations like "tldr grep" use the already local repo.
| And the repo can be updated with tldr --update. Seems very
| fast.
___________________________________________________________________
(page generated 2020-01-22 23:00 UTC)