5 ms·

One thing that annoys me is excess verbosity (that doesn't make the manual any more readable or easier to skim through). Man page for find(1) is a typical exam

by clarry 7y ago

One thing that annoys me is excess verbosity (that doesn't make the manual any more readable or easier to skim through). Man page for find(1) is a typical example. http://man.openbsd.org/find http://man.openbsd.org/find https://linux.die.net/man/1/find https://linux.die.net/man/1/find I usually read man pages on OpenBSD, even when I'm working on Linux. I also often link people on IRC OpenBSD man pages when they're struggling with their tools (or their manuals) on Linux. The reception is generally positive.

teddyh 7y ago
For GNU tools such as find (part of GNU Findutils), the official documentation is almost always not the man pages (which are therefore not as good as they could be), but the Info documentation. In this case: https://www.gnu.org/software/findutils/manual/html_mono/find.html#Finding-Files https://www.gnu.org/software/findutils/manual/html_mono/find...
thom 7y ago
Yeah, the difference here is very stark. I do sometimes wish that info had won as I always found it more accessible (compared to Linux man pages at least), but I suppose the vast majority of people just google now and almost all of these things are redundant.
- clarry 7y ago
  Info is even worse IMHO. Navigating a hierarchy makes it harder to skim and search through, as well as easier to get lost. And when you have such hierarchy, manual writers can use that as an excuse to write even longer (sigh) manuals. To me, much like code and math, the art of writing good documentation is all about finding a way to make it short and simple (but still correct and complete).
  - fanf2 7y ago
    `info x | less` gives you a better info browser than info
    - alyandon 7y ago
      If only I could somehow coax info to render all subnodes into a single page and then pipe it through less it'd be useful to me.
  - thom 7y ago
    You can search a whole info file just as quickly as a man page, and using the index you can jump to the canonical docs for any argument or command in one go (ever spent time trying to find the hyphen-character section of a man page but struggled because it's referenced in 10 places?). I'll admit that whenever in man or info, I will generally go straight to the examples section because that's just how my brain works, but at that point I appreciate that info files aren't stingy with detail.
    - clarry 7y ago
      > You can search a whole info file just as quickly as a man page It's possible that I just don't know how to use info. I always end up in the wrong place. That does not happen with man. > and using the index you can jump to the canonical docs for any argument or command in one go How? > (ever spent time trying to find the hyphen-character section of a man page but struggled because it's referenced in 10 places?) No, because the options are indented and inserting a few spaces before the hyphen in search string eliminates virtually all in-text references. Conventionally, the options are alpha-sorted too. In info pages, I end up wondering which section the option I want might be covered in.
      - sedachv 7y ago
        > How? I in Emacs info-mode. The prompt also has autocompletion.
- alexhutcheson 7y ago
  Info is great for people who live and breathe Emacs, and terrible for non-Emacs users who are just trying to figure out how to get something done. If it's been a while since you last used it, you probably have to refresh yourself on the navigation commands, and the really useful features (the index[1] and incremental search[2]) are buried in different sub-nodes of the Info info manual. As sibling commenters have mentioned, the Info tooling and format encourages people to split up their content into a bunch of nodes. In my experience, ~80% of Info manuals would be better if they were just concatenated into a single node, which the user could quickly Ctrl-F through with the tool of their choice. [1] https://www.gnu.org/software/texinfo/manual/info-stnd/info-stnd.html#Index-Commands https://www.gnu.org/software/texinfo/manual/info-stnd/info-s... [2] https://www.gnu.org/software/texinfo/manual/info-stnd/info-stnd.html#Searching-Commands https://www.gnu.org/software/texinfo/manual/info-stnd/info-s...
  - thom 7y ago
    You can use arrow keys and enter to navigate if you want, or tab like in every other hypertext system in the world. The search key is exactly the same as man, as well as supporting the same ones as readline, and they work across the whole file. I mean, it's 2019, it's a lost argument, but it'd be a shame to think it was lost on this basis.
  - clarry 7y ago
    Fwiw I used Emacs as my go-to editor & IRC client for a few years but I just could not bring myself to like info much at all. The format feels more suitable for something that wants to be a book. I don't want manuals to read like books.
  - jmclnx 7y ago
    Yes, info is horrendous, I hate to say this about a free documentation system, but they could not come up with a worse environment if they tried. But the good news is I read GNU is moving away from INFO for something else, forgot what it was.
- technofiend 7y ago
  Info is kind of cool but as others have stated requires learning yet another command line user interface. It's nice to hear that in recent years it's been made more user friendly by respecting arrow keys, etc but IMHO nothing can touch man foo | col -b > /tmp/foo.1 && vi /tmp/foo.1 for simplicity. It's not a vi vs emacs thing as much as I just want to get to the data and get the tool out of my way kind of thing. Particularly when taking a certain vendor's certification tests, it was the work of seconds to write a man page example to disk and turn that into a script.
willtim 7y ago
Wow, that's a huge difference. I'm tempted to try OpenBSD just for those man pages.

by clarry 7y ago

teddyh 7y ago

For GNU tools such as find (part of GNU Findutils), the official documentation is almost always not the man pages (which are therefore not as good as they could be), but the Info documentation. In this case: https://www.gnu.org/software/findutils/manual/html_mono/find.html#Finding-Files https://www.gnu.org/software/findutils/manual/html_mono/find...

thom 7y ago

Yeah, the difference here is very stark. I do sometimes wish that info had won as I always found it more accessible (compared to Linux man pages at least), but I suppose the vast majority of people just google now and almost all of these things are redundant.

clarry 7y ago
Info is even worse IMHO. Navigating a hierarchy makes it harder to skim and search through, as well as easier to get lost. And when you have such hierarchy, manual writers can use that as an excuse to write even longer (sigh) manuals. To me, much like code and math, the art of writing good documentation is all about finding a way to make it short and simple (but still correct and complete).
- fanf2 7y ago
  `info x | less` gives you a better info browser than info
  - alyandon 7y ago
    If only I could somehow coax info to render all subnodes into a single page and then pipe it through less it'd be useful to me.
- thom 7y ago
  You can search a whole info file just as quickly as a man page, and using the index you can jump to the canonical docs for any argument or command in one go (ever spent time trying to find the hyphen-character section of a man page but struggled because it's referenced in 10 places?). I'll admit that whenever in man or info, I will generally go straight to the examples section because that's just how my brain works, but at that point I appreciate that info files aren't stingy with detail.
  - clarry 7y ago
    > You can search a whole info file just as quickly as a man page It's possible that I just don't know how to use info. I always end up in the wrong place. That does not happen with man. > and using the index you can jump to the canonical docs for any argument or command in one go How? > (ever spent time trying to find the hyphen-character section of a man page but struggled because it's referenced in 10 places?) No, because the options are indented and inserting a few spaces before the hyphen in search string eliminates virtually all in-text references. Conventionally, the options are alpha-sorted too. In info pages, I end up wondering which section the option I want might be covered in.
    - sedachv 7y ago
      > How? I in Emacs info-mode. The prompt also has autocompletion.
alexhutcheson 7y ago
Info is great for people who live and breathe Emacs, and terrible for non-Emacs users who are just trying to figure out how to get something done. If it's been a while since you last used it, you probably have to refresh yourself on the navigation commands, and the really useful features (the index[1] and incremental search[2]) are buried in different sub-nodes of the Info info manual. As sibling commenters have mentioned, the Info tooling and format encourages people to split up their content into a bunch of nodes. In my experience, ~80% of Info manuals would be better if they were just concatenated into a single node, which the user could quickly Ctrl-F through with the tool of their choice. [1] https://www.gnu.org/software/texinfo/manual/info-stnd/info-stnd.html#Index-Commands https://www.gnu.org/software/texinfo/manual/info-stnd/info-s... [2] https://www.gnu.org/software/texinfo/manual/info-stnd/info-stnd.html#Searching-Commands https://www.gnu.org/software/texinfo/manual/info-stnd/info-s...
- thom 7y ago
  You can use arrow keys and enter to navigate if you want, or tab like in every other hypertext system in the world. The search key is exactly the same as man, as well as supporting the same ones as readline, and they work across the whole file. I mean, it's 2019, it's a lost argument, but it'd be a shame to think it was lost on this basis.
- clarry 7y ago
  Fwiw I used Emacs as my go-to editor & IRC client for a few years but I just could not bring myself to like info much at all. The format feels more suitable for something that wants to be a book. I don't want manuals to read like books.
- jmclnx 7y ago
  Yes, info is horrendous, I hate to say this about a free documentation system, but they could not come up with a worse environment if they tried. But the good news is I read GNU is moving away from INFO for something else, forgot what it was.
technofiend 7y ago
Info is kind of cool but as others have stated requires learning yet another command line user interface. It's nice to hear that in recent years it's been made more user friendly by respecting arrow keys, etc but IMHO nothing can touch man foo | col -b > /tmp/foo.1 && vi /tmp/foo.1 for simplicity. It's not a vi vs emacs thing as much as I just want to get to the data and get the tool out of my way kind of thing. Particularly when taking a certain vendor's certification tests, it was the work of seconds to write a man page example to disk and turn that into a script.

willtim 7y ago

Wow, that's a huge difference. I'm tempted to try OpenBSD just for those man pages.