[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Man-writing volunteers?
Re: Man-writing volunteers?
Tue, 12 Aug 2008 17:45:08 +0100
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
> 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? ;)
> 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
Re: Man-writing volunteers?, Micah Cowan, 2008/08/12
- Man-writing volunteers?, Micah Cowan, 2008/08/08
- Re: Man-writing volunteers?, Trent W. Buck, 2008/08/09
- Re: Man-writing volunteers?,
Thomas Adam <=
- Re: Man-writing volunteers?, Juergen Weigert, 2008/08/12
- Re: Man-writing volunteers?, Thomas Adam, 2008/08/12
- Re: Man-writing volunteers?, Juergen Weigert, 2008/08/13
- Re: Man-writing volunteers?, Thomas Adam, 2008/08/13
- Re: Man-writing volunteers?, Stephane Chazelas, 2008/08/13
- Re: Man-writing volunteers?, Aaron Davies, 2008/08/15
- Re: Man-writing volunteers?, Thomas Adam, 2008/08/15
- Re: [screen-devel] Re: Man-writing volunteers?, Geraint Edwards, 2008/08/13
- Re: Man-writing volunteers?, Trent W. Buck, 2008/08/12