Re: [bug #24052] man page info.1 is nearly useless

[Karl Berry]

Hi Dan,

Sorry for the delayed reply.  And, just to warn you, I doubt you'll be
happy with my views here, either.  Sorry about that too ...

    Given that "info" is the lowest common denominator for documentation
    viewing, 

I think that honor belongs to "more" (or "less") or "cat" :).
I know people who have used just those with Info files ...

Personally, I believe far fewer people use standalone Info to read Info
than use Emacs (let alone browse Texinfo-generated HTML).  Based on
emacs info-related traffic vs. standalone info-related traffic here ...
And the Emacs reader is better, too.  It seems to me the main reason for
the Info reader to exist is for the sake of those who don't want Emacs
on their system, for whatever reason.

    it seems useful to put some extra effort into maintaining
    the external documentation for it.

help2man has plenty of possibilities for adding information.  I can
imagine that we could automatically extract the first part of the h(elp)
message from Info, dump it to a file, then include it in info.1.  If you
or anyone wants to work out the details for the Makefiles and send me a
patch, great.

    As a crusty unix type, 

Me too.  But remember, GNU's not Unix :).  rms has always considered man
pages to be second-class citizens ...

    I think this should be the man page but maybe i'm wrong.

I have no objection to making the man page better.  I object to spending
additional maintenance time, ongoing, to document things a second or
third time that are already documented elsewhere.  That is just a
guarantee of things getting out of sync.  (The current situation is
already suboptimal.)

    The --help/man page includes the URL for the texinfo package, but
    maybe it should also include the top-level URL for the documentation
    at http://www.gnu.org/doc/

That page seems awfully generic to be in info --help; it's not going to
help anyone learn how to use Info, that I can see.  But it couldn't hurt
to include it on the Texinfo web page, and maybe in the Info and/or
Texinfo manual.  Thanks.

    how about a URL for how to use the info program?  i.e., the HTML
    dump of the info document for the info program?  (I can't easily
    find it online right now)

The second link under "Basics" on the Texinfo home page says
"Info manual":  http://www.gnu.org/software/texinfo/manual/info/

I guess we could include a link to that, but I confess I kind of think
it's better just to link to the Texinfo home page.  Too much information
can obscure the point too ...

Either or both of those url's could be added to the man page via the
help2man supplements I mention above.  That'd be fine, since they're not
going to change and so no maintenance is involved.  Patches welcome, or
maybe I'll get to it one day.

    So how about installing a copy of that HTML by default when you
    install the software?

You mean, so it would end up in something like /usr/share/doc/info in
the distros?  Do you really think anyone would look for it there?  (Who
can't already figure out how to get to the documentation on the web or
wherever.)

    How about another man page, referenced by the first, that has the
    ascii dump of that info page?

It's not feasible to convert info.texi or info-stnd.texi to man.
They aren't written as man pages.

They are available in plain text (see above link).  I could install
those files, I suppose, but I'm not sure it's worth the bytes, for the
same reason as HTML, and plus, Info format is already very nearly plain
text.

    Yikes.  I didn't know about "pinfo".  I am not sure it is part of
    texinfo per se, 

It isn't.

    but it is listed on your web page.  

I try to list everything Texinfo-ish (and free) that I come across.

    It seems worthy of a "see also" in the manual/help text.

I'm not sure.  It's not GNU.  I have no idea if it is still maintained
or up to date, or if it will be in the future.  I don't especially want
to recommend such unknown quantities in long-lived places like man
pages.

(And besides, if/since pinfo is useful, the best approach would be to
integrate its functionality into Info, rather than have competing
programs ...)

Thanks for all the ideas, despite being such a nay-sayer ...

Best,
k