Re: [Bug-wget] wget manpage question/suggestion

[Micah Cowan]

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

Noèl Köthe wrote:
> Hello,
> 
> the source of the info and manpage is wget.texi. From this file wget.pod
> is generated and then pod2man creates the manpage.
> The result has the problem that sentences are truncated sometimes and
> subnodes are skipped.

Any examples? Thought we cleared away the truncated sentences in 1.11...

<snip patch swapping texi2pod for info2man>

> The problem with this is that the manpage structure is different as
> users expect.

I'm more concerned with my impression that the resulting manpage has
made it much harder to actually find the information one's looking for,
particularly with regard to command-line options. The info manual gets
some compensation for this due to the hierarchical and hyperlinked
navigational features (although I feel that, again particularly for
command-line options, navigability as a reference could be improved).

<snip>

> Another option to fix the manpage could be to just point from the
> manpage to the infopages but I don't know if this is acceptable for
> anybody.

We already do this, don't we? ...though I suppose it appears at the
bottom, whereas maybe it should go at the top.

> My favorite solution would be to remove the info pages and work on
> create a good and complete manpage (maybe with going to docbook or
> anyting else).

Wget being a GNU project, I think you already suspect the chances of
that are about zero, so long as GNU's leadership continues with its
current policies on documentation. The decision to ditch info is
literally not mine to make.

texi2pod sucks, but perhaps not as much as help2man, which is what many
other GNU projects seem to be using. GNU Screen has good, complete
manpage documentation, which is a PITA to maintain since it comes in the
form of a wholly separate document, rather than something generated in
some fashion from existing sources.

I'm not really sure what can be done about this admittedly
less-than-desirable situation. You mentioned DocBook, and the GNU
maintainer guidelines do permit using that (or other formats) as the
source format (though they encourage Texinfo), so long as info
documentation can be generated from it, but really I think man docs and
info docs are sufficiently different as to make it quite a challenge to
generate both from a single source, regardless of what format the source
is in.

Perhaps your info2man solution is the best practical method to have a
manpage for wget that documents everything fully; but using it instead
of the existing manpage is IMO a step backwards in terms of quickly
finding the information one is likely to want. When man-based
documentation gets as large as screen's Texinfo documentation is, it
tends to be most natural if it is split apart into various separate
documents. Perl's succession of manpages, including both reference
material, tutorials, and detailed mechanical explanations, is a great
example.

Of course, producing that amounts to a lot of work... perhaps for the
present we can produce one manpage that contains the basic invocation
information (i.e., the current one), and another that fills in the rest
(your info2man-generated one). I believe the existing one should be
maintained as the front-facing page ("wget.1"); not sure what the
alternative could be called (i.e., I'm open to suggestions).


As far as I'm concerned, the single biggest shortcoming of the current
manpage, is its lack of coverage for the wgetrc commands, particularly
those that lack command-line option counterparts.


I think for the present this discussion will be with an eye to 1.13; I
don't want to make such changes for the approaching 1.12 release.

- --
Micah J. Cowan
Programmer, musician, typesetting enthusiast, gamer.
Maintainer of GNU Wget and GNU Teseq
http://micah.cowan.name/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkprqGIACgkQ7M8hyUobTrFjCwCePjBL1LGtwNREDgj88x3/usM5
mGAAn11StDejk9/ikKM4aDFgWI9hfPIW
=dsKK
-----END PGP SIGNATURE-----