3 ms·

That's a bit like complaining that when I use the BSDs they don't have documentation in Microsoft CHM format, or that they put stuff in /usr/local. Different s

by avar 16y ago

That's a bit like complaining that when I use the BSDs they don't have documentation in Microsoft CHM format, or that they put stuff in /usr/local. Different systems simply have different conventions, and GNU picked GNU Info over man pages. That bastard GNU tar(1) man page was created because Debian has a policy that everything must have a manpage. I like Unix, but the GNU Info format solved some real issues with man. It has built-in index and cross-reference metadata, scales to the size of entire books (the FreeBSD manual would be a single info page), and is much easier to write. I much prefer reading info pages to man pages for that reason. A lot of people seem to dislike GNU info because they confuse the GNU TexInfo / info format with the info(1) program. I'm not a big fan of the default reader (I use the Emacs one instead). But the TexInfo format can be exported to multiple formats and read by multiple programs. Here's the exported GNU Tar documentation for instance: http://www.gnu.org/software/tar/manual/index.html http://www.gnu.org/software/tar/manual/index.html

tzs 16y ago
> Different systems simply have different conventions, and GNU picked GNU Info over man pages. Sure, but that's no reason to be hostile to man pages. Ideally you have a man page, which provides a standard quick reference for those how know the command, and then other documents (such is Info) for people who need more detailed information, complete manuals, etc.. In fact, that's how it was way back in the Seventh Edition days of Unix, with the UPM providing the in-depth documentation and the man pages providing the quick reference. If the GNU people don't want to actually write the man pages, they could at least not stand in the way of those who would like to provide them. Here's another variant of the note from the GNU tar man page on some Linux systems: The GNU folks, in general, abhor man pages, and create info documents instead. Unfortunately, the info document describing tar is licensed under the GFDL with invariant cover texts, which makes it impossible to include any text from that document in this man page. Most of the text in this document was automatically extracted from the usage text in the source. It may not completely describe all features of the program.
- avar 16y ago
  > Sure, but that's no reason to be hostile to man pages. They're not being hostile to man pages. They just don't maintain them. They're no more hostile to man pages than FreeBSD is to info pages. > Ideally you have a man page [...] That doesn't sound very ideal. man pages and info pages are formatted differently and take a different approach to explaining things. Having both would mean that the maintainer of each package would need to expend effort on maintaining both. As an example. Here's the FreeBSD strlen() manpage: http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=strlen http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=strle... And the equivalent section in the GNU libc manual: http://www.gnu.org/software/libc/manual/html_node/String-Length.html#String-Length http://www.gnu.org/software/libc/manual/html_node/String-Len... On FreeBSD I'd do `man 3 strlen' at the nearest terminal. On GNU I'd do `info libc' followed by `m string<TAB>' to find that node. You can't easily turn that documentation into a man page. E.g. on FreeBSD you'd have one manual page for malloc(3), but in the libc manual the documentation for malloc and other allocation functions is part of an entire chapter on "Virtual Memory Allocation And Paging". You can't easily tear that out into a man page. > They could at least not stand in the way of those who would like to provide them. Well, would the FreeBSD project stand in my way if I started sending them patches to duplicate their documentation in some new format like GNU info or perldoc? Probably yes. Documentation isn't a one-off thing. It incurs a long-term maintenance cost. So it's best to pick one system and stick to it. And really, it's not too much to ask that you just familiarize yourself with the conventions of the OS or system you're using. To stick to just ways of reading documentation I use man, info, perldoc, rdoc, phpdoc, javadoc, online tutorials etc. regularly.
  - tzs 16y ago
    But FreeBSD would not stand in your way if you wanted to take their documentation and incorporate it into whatever format documentation you wanted on your system. The GNU folks, on the other hand, will not allow people to take text from Info pages and incorporate it into BSD or Linux man pages.
    - avar 16y ago
      Relly? When have they ever stood in someone's way if they wanted to do that? And was that GNU policy or just some lone grumpy maintainer?
nailer 16y ago
> Different systems simply have different conventions Yes, but one OS should not have two different conventions. (I'm actually a GNU user, but they fucked up here - if they wanted to promote info, the man binary should just direct you to the info page, and fall back to man - avoiding horrible situations like this).

by avar 16y ago

tzs 16y ago

> Different systems simply have different conventions, and GNU picked GNU Info over man pages. Sure, but that's no reason to be hostile to man pages. Ideally you have a man page, which provides a standard quick reference for those how know the command, and then other documents (such is Info) for people who need more detailed information, complete manuals, etc.. In fact, that's how it was way back in the Seventh Edition days of Unix, with the UPM providing the in-depth documentation and the man pages providing the quick reference. If the GNU people don't want to actually write the man pages, they could at least not stand in the way of those who would like to provide them. Here's another variant of the note from the GNU tar man page on some Linux systems: The GNU folks, in general, abhor man pages, and create info documents instead. Unfortunately, the info document describing tar is licensed under the GFDL with invariant cover texts, which makes it impossible to include any text from that document in this man page. Most of the text in this document was automatically extracted from the usage text in the source. It may not completely describe all features of the program.

avar 16y ago
> Sure, but that's no reason to be hostile to man pages. They're not being hostile to man pages. They just don't maintain them. They're no more hostile to man pages than FreeBSD is to info pages. > Ideally you have a man page [...] That doesn't sound very ideal. man pages and info pages are formatted differently and take a different approach to explaining things. Having both would mean that the maintainer of each package would need to expend effort on maintaining both. As an example. Here's the FreeBSD strlen() manpage: http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=strlen http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=strle... And the equivalent section in the GNU libc manual: http://www.gnu.org/software/libc/manual/html_node/String-Length.html#String-Length http://www.gnu.org/software/libc/manual/html_node/String-Len... On FreeBSD I'd do `man 3 strlen' at the nearest terminal. On GNU I'd do `info libc' followed by `m string<TAB>' to find that node. You can't easily turn that documentation into a man page. E.g. on FreeBSD you'd have one manual page for malloc(3), but in the libc manual the documentation for malloc and other allocation functions is part of an entire chapter on "Virtual Memory Allocation And Paging". You can't easily tear that out into a man page. > They could at least not stand in the way of those who would like to provide them. Well, would the FreeBSD project stand in my way if I started sending them patches to duplicate their documentation in some new format like GNU info or perldoc? Probably yes. Documentation isn't a one-off thing. It incurs a long-term maintenance cost. So it's best to pick one system and stick to it. And really, it's not too much to ask that you just familiarize yourself with the conventions of the OS or system you're using. To stick to just ways of reading documentation I use man, info, perldoc, rdoc, phpdoc, javadoc, online tutorials etc. regularly.
- tzs 16y ago
  But FreeBSD would not stand in your way if you wanted to take their documentation and incorporate it into whatever format documentation you wanted on your system. The GNU folks, on the other hand, will not allow people to take text from Info pages and incorporate it into BSD or Linux man pages.
  - avar 16y ago
    Relly? When have they ever stood in someone's way if they wanted to do that? And was that GNU policy or just some lone grumpy maintainer?

nailer 16y ago

> Different systems simply have different conventions Yes, but one OS should not have two different conventions. (I'm actually a GNU user, but they fucked up here - if they wanted to promote info, the man binary should just direct you to the info page, and fall back to man - avoiding horrible situations like this).