2008/8/8 Micah Cowan <[EMAIL PROTECTED]>: > -----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
