Hacker News Reader

Comment by zdw | Hacker News Reader

Manpages used to be the defacto best source of information, but sometime in the last 15 years they went from great to a hit and miss shambles.

I write this up to GNU's "info" being preferred by some programs, but then that not being installed properly or at all on many system, and people hating manpage syntax, often with good reason.

That said, some systems pay a lot of attention to this. OpenBSD's mandoc is a great example of a modernization of the manpage system, and their manpages are second to none: http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

View on HN

I think people now like documentation in lots of different forms - manpages, HTML, pdf, or introspectable docs like Python docstrings. IPython, for example, has all four of those.

There are systems like Sphinx that let you share content between different formats, but they're not magic bullets. For instance, if I write docs relying on inline links because I'm used to viewing them in HTML, the result won't be great for manpage readers.

The info nav system can be avoided with:

    info () { command info "$@" 2>&1 | less; }

to get the content with a more (or less) familiar nav tool.

Another useful approach is to 'project the document' rather than to 'document the project'. Write the draft documents as part of the specification and development process. Code the project. Finally, edit the docs to match the code.

You get to capture the state of early energy and an over- or top-down view before diving into the code, and will remember to mention details of the design while they are fresh and new, rather than at the end of the coding process, when everything has become so familiar that it all seems trivially obvious.

Wait, there's programs that use info? o.O

Oh yeah. 'man cp' from my Arch Linux machine:

---

SEE ALSO

The full documentation for cp is maintained as a Texinfo manual. If the info and cp programs are properly installed at your site, the command

              info coreutils 'cp invocation'

should give you access to the complete manual.

---

I ran that 'info' command and promptly ran the one emacs command I have memorized: C-x C-c

I recently switched to Emacs and started learning it by going through the tutorial (C-h t). Near the end of the tutorial, it refers you to the Emacs manual which uses info (C-h r). After going to the manual I had no idea how to navigate, so I ran the info tutorial (h). I don't really have a point, but I think it's funny that I had to run the a tutorial to get help.

Coreutils come from the GNU project so I wouldn't really count it. :p

the best part is when a man page has an entry like this, and then the info page is a copy of the man page...

Reply on news.ycombinator.com