[screen-devel] Man-writing volunteers?

[Micah Cowan]

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

So, what would _really_ help me out in getting the documentation ready
for a 4.1.0 release, is if someone would step up to volunteer to
maintain the man page.

The first step would be to ensure that the man page is in-step with the
Texinfo manual; currently I believe the man page is a couple steps
behind. the content is essentially the same between them, so for the
most part you should actually be able to compare them side-by-side for
differences. Tedious work, obviously.

The next step would be to watch changes made to the Texinfo document
(which I'll be updating to reflect the current state of things), and
transfer them to the man-page.

Basically, I'm willing to maintain one big, hulking, autonomous manual;
but I will not maintain two. I need someone else to step up for that. If
no one does, then this release will be issued with a woefully
out-of-date man page (lacking information on all the nifty new stuff),
and future releases might include one of those shell-of-a-manpages that
simply refer the reader to the Texinfo documentation. Surely that's
enough to scare a few of you into volunteering? ;)

To my mind, unifying on a single source format would be the best
long-term approach, rather than having two manuals maintained. So far,
the approach that makes the most sense to me is to use the Texinfo as
the source document, generating the manpage with texi2pod.pl (see Wget's
Texinfo documentation for an understanding of this; note that, even with
texi2pod.pl, however, Wget's man page is still very much inferior to
their Texinfo counterparts: only a small portion is translated into the
man page). However, for Screen this would require texi2pod.pl to be
modified to allow arbitrary sections to be transmitted (it only allows
the standard ones, currently).

Actually, though, as it stands, a big-hulking man page strikes me as
remarkably untraditional. It seems to me that, if we're going to do man
pages right for Screen, we should split it apart into separate man pages
by concept. For instance, one dedicated to the invocation options,
another dedicated to commands (screen(5) or screenrc(5)), another
dedicated to screen's mechanisms for hardstatus/caption/autoaka, another
for screen's terminal emulation details... of course, doing such a thing
would also mean that it would be a lot more challenging to generate from
the Texinfo documentation, so would really require a separate maintainer
(or more heavy modifications to texi2pod, or something).

- --
Micah J. Cowan
Programmer, musician, typesetting enthusiast, gamer.
GNU Maintainer: wget, screen, teseq
http://micah.cowan.name/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFInJ8R7M8hyUobTrERArJWAJ9CN1uwQp6MTkgMbKljWpRYmotklwCfe6ae
ELjB+S2tSxHEsovHSKfraTI=
=+qP0
-----END PGP SIGNATURE-----