Man vs. Info: documenting the software
in [Shell]
|
Prev: Remove certain characters in a filename
Next: x12a403
From: Ivan Shmakov on 2 Feb 2010 01:45 -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 >>>>> "S" == Seebs <usenet-nospam(a)seebs.net> writes: >>>>> "IS" == Ivan Shmakov <ivan(a)main.uusia.org> wrote: [...] S> An index on a whole bunch of separate documents is often less useful S> than a single all-in-one searchable text document. The people doing S> the indexes may not have categorized something the way I would have; S> a plain search is often faster. IS> The index, as included into almost every Info document, allows for IS> a quick access to the documentation for the particular system or IS> language functions, commands, etc. Instead of having a Man section IS> to specify a ?namespace?, one specifies the namespace to search in IS> by choosing a particular Info document. S> And if I know what section I want, then that's useful, otherwise, S> it's anti-useful, because a single document all of which I can S> search with a single search command is more useful to me. And, to state it once again, Info is such a document. Just strike âsâ to run a search. [...] - -- FSF associate member #7257 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAktnyfAACgkQMBO2oCMOM0q8lwCfZ6BawKsJv2aa4QbaxVx9Hqrb nL4AoMKKs4iQyMQ5CaZgnRHUSLl6K4Oo =HMe4 -----END PGP SIGNATURE-----
From: Seebs on 2 Feb 2010 02:20 On 2010-02-02, Ivan Shmakov <ivan(a)main.uusia.org> wrote: > S> Except in the degenerate case where the man page sucks, I have never > S> seen a case where the info page was as useful for "I forgot the > S> command line usage" as the man page was. > And what about $ foo --help? Usually just a bare usage message, not very helpful for reminding you of complicated options. > How do I make a hard copy of the documentation for the GNU Libc > (would there be one in the Man format)? Usually, one would print out all the section 3 man pages in alphabetical order, with an index. > And now I want it to be in some sort of order, like being split > into sections in some sensible way. Is Man of any help there? Sort of. > And Texinfo does this with ease. Yes. Exactly my point -- it solves a problem of extremely marginal value, in a way that breaks things of significant value. It's classic "we made this up without really thinking it through". > S> And if I know what section I want, then that's useful, otherwise, > S> it's anti-useful, because a single document all of which I can > S> search with a single search command is more useful to me. > Huh? So, how can I have a single document with the contents of > each and every manual page installed in my system? "info gcc" gives me a huge nest of menus I have to pick from to find a given option. "man gcc" gives me something where "/msoft-float" gets me to the right option without me having to figure out what category that information was put in. > The Info manuals are much closer to a ?single document? ideal > (if one has one), actually, since there're usually one or two > perfectly searchable Info files per package. With Man, there > may easily be a hundred of Man pages (say, for a programming > language), which are to be concatenated into a single document > somehow before starting the search. I rarely have to look in more than one, though, because I know what I want the documentation for. > S> They wouldn't all be in the third section. If I want to know about > S> the printf in awk, it's in man awk. Otherwise, "man 3 printf" and > S> "man 1 printf" seem to work pretty well. > As its Web page says, Octave manual is some 575 pages long. > Isn't it a bit too much for a manual page? Yes. And again, I already addressed this: Manuals like that, sure, make them an info page. But FIRST, make a man page that covers the basics of how to invoke the program, what the options are, and so on. > The same stands for SLIB, and for Tcl as well, which uses a Man > page per command, not a Man page per language, too. (Thus, I'm > not sure what you'll get with $ man 3 puts ? would it be a Man > for a C function, or a Tcl command?) Tcl gets its own section. > BTW, did you notice that info Gawk is some order of magnitude > larger than its Man counterpart? Yes. And that's fine; they did that one right. The man page covers what you expect to get when you do "man <command>", there's a much larger manual if you need it. > S> Yes. So did the GNU indentation standard. > So, why it was Info to ?astonish? you, and not Man? Because I learned on UNIX systems. Also, because info does not act like a UNIX command. "man foo" prints to standard output. "info foo" pops into a weird program with its own key bindings. Also: Standards. POSIX specifies man. "man" has been there since I was a small child playing rogue. (Note that I was using UNIX systems for a good decade before I started programming seriously.) It's there on every system, not just GNU systems. > S> As long as a large number of packages have man pages, and man pages > S> are somewhat standardized and apply across multiple enviroments, > Are they? Yes. > To set-up a serial terminal in GNU/Linux, one has to > read inittab(5) and getty(8) first. In BSD-like, it probably > will be ttys(5), and in OpenSolaris (as I've found recently) > neither helps. I didn't say the specific things for which there would be man pages were standardized, but the underlying "man" program is. > I have no chance to either object or to support this because I > simply lack the experience with other, non-GNU, environments. > IOW, for me, it doesn't matter. And this is why the GNU attitude is harmful; it's embrace-and-extend, and screw the people who aren't using EXACTLY the system I am. It's indistinguishable from Windows people saying "well, IE works on everything I use, so for me, it doesn't matter." > As for the large number packages ? there're too many packages > for which the documentation is in an awful state. I wonder, > whether this state of disorder should be made a standard on the > mere basis that it's what is seen all to often? I would argue that, no, it shouldn't. Which is why I dislike the "oh, we don't maintain the man page, just the info page" thing. > Texinfo documents aren't mere references, they generally serve > as tutorials as well. So write the tutorial AFTER you have written the basic manual. > Would I have the resources to develop a > manual that's also a decent tutorial, I wouldn't put it into a > Man page. Of course not. But a good reference is NOT a decent tutorial! Which is more useful to a practicing chemical engineer: 1. A chart of the elements of the periodic table. 2. A large colorful book which explains what "electrons" are, has a five page section introducing the notion of covalence, and otherwise serves as an effective tutorial. If you want a tutorial and a reference manual, THEY ARE SEPARATE THINGS. Make them separate, and make each of them good at the thing it does; don't try to make a single all-singing all-dancing thing which is both. > S> It's well-documented, and FANTASTICALLY, UTTERLY, STUPID. > I don't understand how --help and --version could ever be > stupid. I said "GNU coding standards". Not "every last possible thing which GNU has ever specified". (That said: Consider "true --help" or "echo --version".) > S> They're bad at every level; the technical advice has historically > S> been awful, the stylistic advice is awful, > Could you be more specific, please? Their indentation style is ridiculous. The "don't worry about other systems, and everything is 32-bits" advice they used to give was classically awful, and if they haven't gotten around to changing it, it's still awful. > Man pages could be nice if they're small, but it's a sign of > sure evil to document a whole programming language in just one. And you shouldn't do that. That's not what they're *for*. They're not complete documentation; they're a particular subset of documentation. Specifically, the quick reference you need to look up for a given command, function, or file. > If making a hard copy of the documentation isn't a problem for > you, try to compare the printed Man page to the printed Texinfo > manual for GNU Awk (please consider downloading a PostScript or > PDF version, if anything else fails.) Why? I don't *use* printed documentation if I can possibly avoid it. It's wasteful and I can't search it. > Would you please name the specific examples? There are too many. I gave you a couple as a starting point. But it's not like this is hard. Just imagine that you care whether your work is of use to people who don't use the exact same operating system you do, and read the GNU coding standards with an eye to portability. It should be pretty obvious. Similarly, if you can't see what's wrong with their style guidelines, I'm really not sure what I can do, except suggest that you get some practice programming under a variety of style guidelines. > S> It's great that they've made some useful stuff available, but it > S> doesn't make the bad things somehow not-bad. > It just that their stuff is not only useful, but, generally, is > the only useful. "Generally"? gawk is not the only free and usable awk; mawk is probably superior. GNU make is not the only free and usable make, and Berkeley pmake has a large number of features which are probably better. Nothing in the coreutils type stuff is the "only" of its kind; most of them have two or three or five other implementations already available, at least one of which is open source. Emacs is not the only good or powerful editor. The toolchain's really good, and has little competition. That's about what I can come up with. Everything else is not by any stretch of the imagination the "only" useful. BSD's had a complete Unix environment available as open source for something near twenty years now. -s -- Copyright 2010, all wrongs reversed. Peter Seebach / usenet-nospam(a)seebs.net http://www.seebs.net/log/ <-- lawsuits, religion, and funny pictures http://en.wikipedia.org/wiki/Fair_Game_(Scientology) <-- get educated!
From: Ivan Shmakov on 2 Feb 2010 03:38 -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 >>>>> "S" == Seebs <usenet-nospam(a)seebs.net> writes: >>>>> "IS" == Ivan Shmakov <ivan(a)main.uusia.org> wrote: S> Except in the degenerate case where the man page sucks, I have never S> seen a case where the info page was as useful for "I forgot the S> command line usage" as the man page was. IS> And what about $ foo --help? S> Usually just a bare usage message, not very helpful for reminding S> you of complicated options. Any specific GNU package or program to suffer from that? IS> How do I make a hard copy of the documentation for the GNU Libc IS> (would there be one in the Man format)? S> Usually, one would print out all the section 3 man pages in S> alphabetical order, with an index. ... Including the ones that belong to particular âthird-partyâ libraries? [...] S> And if I know what section I want, then that's useful, otherwise, S> it's anti-useful, because a single document all of which I can S> search with a single search command is more useful to me. IS> Huh? So, how can I have a single document with the contents of IS> each and every manual page installed in my system? S> "info gcc" gives me a huge nest of menus I have to pick from to find S> a given option. "man gcc" gives me something where "/msoft-float" S> gets me to the right option without me having to figure out what S> category that information was put in. Doesn't M-x info RET d m gcc RET give you something where âs msoft-float RET n s RETâ gets you to the very same option? Note that with Info it's easy to skip a section (n), which is not the case with a typical (Less, More)-paged Man page. [...] IS> As its Web page says, Octave manual is some 575 pages long. Isn't IS> it a bit too much for a manual page? S> Yes. S> And again, I already addressed this: Manuals like that, sure, make S> them an info page. But FIRST, make a man page that covers the S> basics of how to invoke the program, what the options are, and so S> on. Agreed. But what'd be the purpose of keeping the separate Man reference when there's already one in the Info manual? IS> The same stands for SLIB, and for Tcl as well, which uses a Man IS> page per command, not a Man page per language, too. (Thus, I'm not IS> sure what you'll get with $ man 3 puts ? would it be a Man for a C IS> function, or a Tcl command?) S> Tcl gets its own section. So, a Man section per programming language is the way to go? [...] IS> So, why it was Info to ?astonish? you, and not Man? S> Because I learned on UNIX systems. Also, because info does not act S> like a UNIX command. "man foo" prints to standard output. "info S> foo" pops into a weird program with its own key bindings. So does Vim, and Less, at least when most of the today âcomputer usersâ are concerned. In particular, GRASS GIS has (or at least had) âmoreâ to override âlessâ as the default pager, for the newcomers not to be confused by the weird behaviour of the latter. [...] IS> To set-up a serial terminal in GNU/Linux, one has to read IS> inittab(5) and getty(8) first. In BSD-like, it probably will be IS> ttys(5), and in OpenSolaris (as I've found recently) neither helps. S> I didn't say the specific things for which there would be man pages S> were standardized, but the underlying "man" program is. IIRC, there was no single cross-platform Man implementation? Even GNU/Linux has, IIRC, two distinct Man implementations (one typically associated with Debian, while the other with, I guess, RedHat-like systems.) The pager used may also differ â there're Less, Most, and also different More implementations. IS> I have no chance to either object or to support this because I IS> simply lack the experience with other, non-GNU, environments. IOW, IS> for me, it doesn't matter. S> And this is why the GNU attitude is harmful; it's S> embrace-and-extend, and screw the people who aren't using EXACTLY S> the system I am. It's indistinguishable from Windows people saying S> "well, IE works on everything I use, so for me, it doesn't matter." Well, yes. [...] IS> Texinfo documents aren't mere references, they generally serve as IS> tutorials as well. S> So write the tutorial AFTER you have written the basic manual. Once again, I agree with that. But after the latter is fully embedded into the former, I see no reason to maintain the latter separately. That being said, Docbook has the facilities to support producing both the printable document, and the specially marked excerpts from it as the Man pages. But I surely do not want to propose it for the GNU standard documentation platform. IS> Would I have the resources to develop a manual that's also a decent IS> tutorial, I wouldn't put it into a Man page. S> Of course not. But a good reference is NOT a decent tutorial! S> Which is more useful to a practicing chemical engineer: 1. A chart S> of the elements of the periodic table. 2. A large colorful book S> which explains what "electrons" are, has a five page section S> introducing the notion of covalence, and otherwise serves as an S> effective tutorial. I've seen some of these large colorful books. Indeed, most were with a chart of the elements. Fortunately, computer documents are unlike the paper ones. S> If you want a tutorial and a reference manual, THEY ARE SEPARATE S> THINGS. Make them separate, and make each of them good at the thing S> it does; don't try to make a single all-singing all-dancing thing S> which is both. Once one's given infinite time to implement it, this advice seems reasonable. S> It's well-documented, and FANTASTICALLY, UTTERLY, STUPID. IS> I don't understand how --help and --version could ever be stupid. S> I said "GNU coding standards". Not "every last possible thing which S> GNU has ever specified". (That said: Consider "true --help" or S> "echo --version".) There's an obvious clash between the widely established and standardised behaviour and the GNU standards. That being said, I'd use â:â (in Bash) and âprintfâ instead anyway. S> They're bad at every level; the technical advice has historically S> been awful, the stylistic advice is awful, IS> Could you be more specific, please? S> Their indentation style is ridiculous. S> The "don't worry about other systems, I've seen GNU Coreutils running on FreeBSD and OpenSolaris. Have you seen, e. g., their FreeBSD counterparts running on GNU/Linux and OpenSolaris? S> and everything is 32-bits" It was âeverything is at least 32-bitsâ, at least as I've remembered it, which still holds true. Unless, of course, you're developing for an embedded platform. S> advice they used to give was classically awful, and if they haven't S> gotten around to changing it, it's still awful. And once again, I don't see why it is. IS> Man pages could be nice if they're small, but it's a sign of sure IS> evil to document a whole programming language in just one. S> And you shouldn't do that. That's not what they're *for*. Good to hear that. [...] IS> If making a hard copy of the documentation isn't a problem for you, IS> try to compare the printed Man page to the printed Texinfo manual IS> for GNU Awk (please consider downloading a PostScript or PDF IS> version, if anything else fails.) S> Why? I don't *use* printed documentation if I can possibly avoid S> it. It's wasteful and I can't search it. This particular example was only to show the differences between the purposes of Man and Info. [...] - -- FSF associate member #7257 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAktn5IsACgkQMBO2oCMOM0r0MgCgzQeoqLArkmIioCNyOtT9k5Iz iO8AoJTS5hNPcgRdm1hiaueb4978odNI =9AOz -----END PGP SIGNATURE-----
From: Chris F.A. Johnson on 2 Feb 2010 03:46 On 2010-02-02, Ivan Shmakov wrote: .... > Agreed. But what'd be the purpose of keeping the separate Man > reference when there's already one in the Info manual? What's the purpose of a separate Info manual when there's a perfectly good man page? -- Chris F.A. Johnson, author <http://shell.cfajohnson.com/> =================================================================== Shell Scripting Recipes: A Problem-Solution Approach (2005, Apress) Pro Bash Programming: Scripting the GNU/Linux Shell (2009, Apress) ===== My code in this post, if any, assumes the POSIX locale ===== ===== and is released under the GNU General Public Licence =====
From: Ivan Shmakov on 2 Feb 2010 05:56
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 >>>>> "CFAJ" == Chris F A Johnson <cfajohnson(a)gmail.com> writes: >>>>> "IS" == Ivan Shmakov wrote: IS> Agreed. But what'd be the purpose of keeping the separate Man IS> reference when there's already one in the Info manual? CFAJ> What's the purpose of a separate Info manual when there's a CFAJ> perfectly good man page? It seems that we've agreed with the OP (the Other Poster) earlier in this thread, that having a 575-page long Man page isn't quite the solution to the documentation problem. - -- FSF associate member #7257 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAktoBMMACgkQMBO2oCMOM0qLMwCg3TYFFKRdgk0OGmGFZAVOnB+8 x0AAn1iL9a02+s0mdhTRuOFMyzM+4sIf =Yzmp -----END PGP SIGNATURE----- |