Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Simplified and community-driven man pages

tldr.sh

Post reply on HN
Print view View original

151–160 of 169 posts

Re: Simplified and community-driven man pages

#151

Post by Annatar »

pletnes wrote: post #41
dfabulich wrote: post #36

Earlier quoted context omitted.

The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…

I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addi…

Good projects should have tutorials and complete references online in addition to man pages.

A well written manual page requires no additional tutorials, for they will be included in the text’s corpus.

Writing good documentation for one’s software is almost more important than writing the software itself; don’t force the user to have to run around the internet; be comprehensive in the manual.

Re: Simplified and community-driven man pages

#152

Post by Annatar »

jmfayard wrote: post #77
dfabulich wrote: post #36

Earlier quoted context omitted.

The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool t…

  man test | grep -- ‘ -e’
UNIX already has that as you can see. You just need to learn the target substrate you’re using.

Re: Simplified and community-driven man pages

#154

Post by Annatar »

wang_li wrote: post #127
jmfayard wrote: post #77

Earlier quoted context omitted.

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool t…

If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.

Indeed!

Re: Simplified and community-driven man pages

#155

Post by explainplease »

jmfayard wrote: post #77
dfabulich wrote: post #36

Earlier quoted context omitted.

The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool t…

> If I'm looking for option "-e" of the test command, why can't I do...

https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-...

    $ man test -e

           STRING1 != STRING2
                  the strings are not equal

           INTEGER1 -eq INTEGER2
                  INTEGER1 is equal to INTEGER2

           INTEGER1 -ge INTEGER2
                  INTEGER1 is greater than or equal to INTEGER2
    --

           INTEGER1 -ne INTEGER2
                  INTEGER1 is not equal to INTEGER2

           FILE1 -ef FILE2
                  FILE1 and FILE2 have the same device and inode numbers

           FILE1 -nt FILE2
                  FILE1 is newer (modification date) than FILE2
    --

           -d FILE
                  FILE exists and is a directory

           -e FILE
                  FILE exists

           -f FILE
                  FILE exists and is a regular file

Re: Simplified and community-driven man pages

#156

Post by explainplease »

dmitriid wrote: post #110
onetruepretzel wrote: post #56

Earlier quoted context omitted.

I must admit I'm not a fan of this. I feel like the work could go towards submitting patches to the man pages. The MAN page layout [0] allows for an EXAMPLES section which serves this purpose. Great effort in creating this tool but I think it's replicating functionality already provided by the man pages. I've submitted patches for MAN pages for GNU tools in the past and the creators are very receptive to updates. [0]…

Yup, and the examples section is usually last, with no possibility to jump directly to it

    $ cat ~/.bin/eg
    #!/bin/bash
    man $@ | awk '/^EXAMPLE/ { getline; while ($0 !~ /^[A-Z]+/) { print $0; getline; } }'

Re: Simplified and community-driven man pages

#157

Post by xtiansimon »

justin66 wrote: post #126
dfabulich wrote: post #36

Earlier quoted context omitted.

The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…

> The examples should have come first, in the synopsis. That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an e…

I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant.

That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.

Re: Simplified and community-driven man pages

#158

Post by explainplease »

_blz2 wrote: post #114

Sweet. Added this to my bashrc file. tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | less ; }

If you have Pandoc and w3m:

    curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | pandoc --from=markdown --to=html | w3m -T text/html

Re: Simplified and community-driven man pages

#159

Post by detaro »

JdeBP wrote: post #123
detaro wrote: post #66

Earlier quoted context omitted.

please don't point out empty discussions without upvotes as duplicates, unless there are tons of those recently. Reposts are explicitly allowed on HN under these circumstances.

At the time that I wrote that this was an empty discussion too. You should bear in mind when things are written.

I don't see how that makes the reference more useful. (I see two purposes for linking to other submissions: point out duplicates that mean the current discussion should be marked dupe (post the link and flag = [dupe] if it's the first comment, otherwise mods add it later), or point other commenters to old but maybe still interesting discussions. Neither case applies when pointing to empty discussions)

Re: Simplified and community-driven man pages

#160

Post by bmn__ »

JdeBP wrote: post #65
dfabulich wrote: post #37

Earlier quoted context omitted.

I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result. Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping... In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific ques…

... or Wikipedia. Interestingly, Stack Exchange answers are sometimes constructed by people using search engines to find phrase matches, sometimes with ridiculous results. (-: * https://photo.stackexchange.com/questions/94238/who-or-what-... That Stack Overflow web log entry is poorly researched, by the way. As I can attest from my own WWW site's statistics, there are reasons that a WWW site can have Ukraine at the t…

Off-topic:

What do you hope to achieve by expressing domain names with a dot at the end? That's only required in zonefiles. No one else does that in hyperlinks and I wish you would stop doing it. It's annoying because your alternative notation is so rare that browsers don't normalise the equivalency, and now I have multiple divergent entries in the browser history.

Post reply on HN