Re: General complaint about GNU's preference for "info" versus "man"

[Eli Zaretskii]

> From: Torsten Bronger <address@hidden>
> Date: Sun, 23 Apr 2006 10:56:09 +0200
> 
> >> Some Info documents don't have an Invocation node
> >
> > Which ones?  The GNU coding standards _require_ each manual to
> > have such a node, [...]
> 
> Probably the GNU coding standards are not as well-known as the
> structure of manpages.

Maybe so, but they are nonetheless standards, and at least the GNU
package maintainers are required to abide by them.  In other words, if
some package doesn't, it's a reason good enough to submit a bug
report.

> In my opinion this should be said in the documentation of the
> Texinfo file format.

I'm not sure I understand what you wanted to say here.

> Okay, here's my unfair pseudo-analysis of "info --usage".

Thanks.

> "info --usage info" is equivalent to "man 5 info" rather than "man
> info".  This is not what most users will be looking for.

I'm guessing that you thought "info --usage info" will tell you about
the stand-alone Info reader.  But it doesn't: info.info is a manual
that described the Info system in general and the features of an Info
reader once you are _inside_ the reader.  This manual was written to
be the first one that one reads when one's exposed to the Info system
for the first time.  That is why it is (or should be) the first item
in the DIR file's menu.

The manual that describes the stand-alone Info reader is called
info-stnd.info, so "info --usage info-stnd" will do what you want.

> Additionally, I didn't find the path to info's command line options,
> at least not without going via the "dir" file.

Again, that's because it's not a manual that describes a certain
program.

> GCC and CVS simply show the manpage.

??? Unless there's a bug, this should happen only if these manuals
aren't installed, or the stand-alone Info reader couldn't find them.

I just tried "info --usage gcc", and landed in the node "Option
Summary", which is a good place, I think.  And "info --usage cvs" gets
me to Appendix B "Quick reference to CVS commands", which is again a
reasonable place.  This is on a Debian box.

> "info --usage gnuplot" got me to Gnuplot's command options which is
> neither the command list itself nor the command line options list.

That manual doesn't have anything close to what the GNU standards
request, and the description of command-line args, when one does find
it, only mentions X11 options.  In other words, the stuff you are
looking is simply not there.  OTOH, "man gnuplot" says "No manual
entry for gnuplot" on that machine.

> Apparently it is just a node that contains "option" in its name.

The Info reader tries several reasonable names, but in this case it
simply couldn't succeed.

> "info --usage makeinfo" takes me to "Running `makeinfo' from a
> Shell".  However, the following node would be much more useful.

I think these two nodes should simply be united.  Karl?

> however, I don't think that this is a real substitute for "man".

Why not?

> Additionially, as I already said in a follow-up to Stepan, it's not
> only about command-line options.  I like the "description", "files",
> and "environment" sections in manpages as well.  For example, where
> is the configuration file?  In $HOME, /usr/etc, or somewhere below
> /var?  A manpage tells you under "FILES".

If this is important, we could have references to the relevant
sections after the options' description; some packages already do
that.  (OTOH, many packages simply don't have anything to say on these
issues.)