[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Man-writing volunteers?
Trent W. Buck
Re: Man-writing volunteers?
Wed, 13 Aug 2008 11:13:44 +1000
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
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
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,
> 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.
Re: Man-writing volunteers?, Micah Cowan, 2008/08/12
Re: Man-writing volunteers?, Trent W. Buck, 2008/08/12
Re: Man-writing volunteers?,
Trent W. Buck <=