Re: Man vs. Info: documenting the software

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

"S" == Seebs <usenet-nospam@xxxxxxxxx> writes:
"IS" == Ivan Shmakov <ivan@xxxxxxxxxxxxxx> 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-----
.

Relevant Pages

  • Re: Man vs. Info: documenting the software
    ... S> search with a single search command is more useful to me. ... And again, I already addressed this: Manuals like that, sure, make them ... And this is why the GNU attitude is harmful; ... for which the documentation is in an awful state. ...
    (comp.unix.shell)
  • Man vs. Info: documenting the software
    ... How do I make a hard copy of the documentation for the GNU Libc ... The Info manuals are much closer to a “single document” ideal ... S> As long as a large number of packages have man pages, ...
    (comp.unix.shell)
  • Re: reference for beginner on configure/make/compile/linking/etc.
    ... reference for beginner on configure/make/compile/linking/etc. ... when using the `GNU build system' is the one at Wikipedia: ... Note that the online copies of the manuals refers to particular versions ... and it usually takes multiple attempts at writing a new ...
    (freebsd-questions)
  • Re: Hyperref queries
    ... TeX documentation really does need to be re-written for people who are ... Indeed - I can work with car maintenance manuals, ... Another difference with TeX is that it's not just a toolbox - it's more ...
    (comp.text.tex)
  • Re: reference for beginner on configure/make/compile/linking/etc.
    ... when using the `GNU build system' is the one at Wikipedia: ... The GNU automake homepage ... Note that the online copies of the manuals refers to particular versions ... and it usually takes multiple attempts at writing a new ...
    (freebsd-questions)