Re: Man-writing volunteers?

[Trent W. Buck]

On Tue, Aug 12, 2008 at 05:45:08PM +0100, Thomas Adam wrote:
> 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,

I think it would be more accurate to say that primarily Emacs users
read them.  I like them because (most manuals) have command and
subject indexes, and the browsers have a "back button" (l) to go to
the previous page, and because the search functions (C-s and C-M-s)
can search beyond the current page.  The man format doesn't have
indexes, and HTML doesn't support searching across a multi-page
document.

I also use manpages, but for *quick reference* -- not as a manual, but
as a refresher to remind me of the name of a switch or command.  I
*like* the way GNU coreutils has quick reference content in manpages
(e.g. cp.1) and a *separate* manual that describes the package in
detail.  I prefer this to bash's manpage, where I feel overwhelmed; or
to perl's manpages, where it takes me ages to find the right one.

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

I'd prefer the screen manpage to simply have a one-line synopsis, a
two-paragraph description and then a one-line (.TP) description of
each switch and :command.

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

Do those have good support for large manuals, with cross-referencing
and multiple indexes within the document?  My memory of them is that
they implement headings, literal blocks and emphatic/strong text; if
you want anything more, too bad.

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

I'm not bothered by having a second manpage for screenrc; but how do
you decide what should go in it?  Should :commands be described in
screen(1) or screenrc(5)?  They can be used both interactively and in
.screenrc.  The same applies for the description of string escapes.