Re: Man-writing volunteers?

[Thomas Adam]

2008/8/8 Micah Cowan <address@hidden>:
> -----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.

I put myself forward as a volunteer.

> 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.

But something of a no-brainer, so it's easy to do just time-consuming.

> 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.

I will state at this point, categorically, that although being true to
GNU's roots is nice, I am dead against texinfo pages -- *no* one
actually reads them; heck, the existing info viewer is an abomination,
pinfo is "OK" but is not ubiquitous so it's out of the running for
most people.  No... I seriously suggest we just make the manpage a
fore-runner -- at least an "official" representation of our
documentation.

> Basically, I'm willing to maintain one big, hulking, autonomous manual;

You won't come close to FVWM's man page size.  :P

> 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),

As noted above, I am willing to maintain the *man*page.

> 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? ;)

Perhaps.

> 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).

Or use asciidoc or txt2tags, etc.

> 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).

I disagree.  Having one manpage for screen, and another for the
screenrc is in keeping with "tradition" -- splitting this mythical
screen(1) manpage up would only alienate its use -- how would/are
people supposed to know/remember which manpage to refer to?

-- Thomas Adam