Subject: Man-writing volunteers?

From: Micah Cowan <[email-masked]>
Date: Fri, 08 Aug 2008 13:20:03 -0700

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.

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.

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.

Basically, I'm willing to maintain one big, hulking, autonomous manual;
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),
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).

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

- --
Micah J. Cowan
Programmer, musician, typesetting enthusiast, gamer.
GNU Maintainer: wget, screen, teseq
http://micah.cowan.name/

_______________________________________________
screen-users mailing list
[email-masked]
http://lists.gnu.org/mailman/listinfo/screen-users

---

From: "Trent W. Buck" <[email-masked]>
Date: Sat, 9 Aug 2008 14:53:10 +1000

> differences. Tedious work, obviously.

Surely texinfo can be automatically converted into a roff manpage?

> remarkably untraditional.

The GNU convention would be to have a simple one- or two-page manpage,
which includes a SYNOPSIS and a brief DESCRIPTION and then says "use
info for the complete manual".

IMO this is a reasonable approach.  How do other stakeholders feel?

---

From: Øyvind A. Holm <[email-masked]>
Date: Sat, 9 Aug 2008 07:34:12 +0200

On 2008-08-09 14:53:10, Trent W. Buck wrote:
> > 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.
>

Not according to Wikipedia:

  Notable is the lack of man as an output format from the standard 
  Texinfo tools. True, Texinfo is used for writing the documentation of 
  GNU software, which typically is used in Unix-like environments such 
  as GNU/Linux, where the traditional format for documentation is man. 
  But the design rationale for the standard Texinfo tools' omission of 
  man as an output format is that man pages have a strict conventional 
  format, used traditionally as quick reference guides, whereas typical 
  Texinfo applications are for tutorials as well as reference manuals. 
  As such, no benefit is seen in expressing Texinfo content in man page 
  format. Moreover, many GNU projects eschew man pages almost 
  completely, referring the reader of the provided man page (which often 
  describes itself as seldom maintained) to the Info document.

                              <http://en.wikipedia.org/wiki/Texinfo>

> IMO this is a reasonable approach.  How do other stakeholders feel?

I like manpages, I think it's a nice format for reference. I never 
understood why the GNU Project dislikes manpages, and personally I tend 
to get a little annoyed when I have to do a _second_ search in the info 
material (which sometimes has to be installed separately) when it easily 
could've been included in the man page.

To make both worlds happy, maybe an idea would be to convert the Texinfo 
documentation into DocBook, which is able to create pretty manpages in 
addition to the formats Texinfo generates. If this is of interest, I can 
volunteer for the Texinfo → DocBook conversion.

Øyvind

+-| Øyvind A. Holm <[email-masked]> - N 60.39548° E 5.31735° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2  E77E FB0C BEE8 94A5 06E5 |
+------------| 9fa36d42-65d2-11dd-b930-000475e441b9 |-------------+
_______________________________________________
screen-users mailing list
[email-masked]
http://lists.gnu.org/mailman/listinfo/screen-users

---

From: "Thomas Adam" <[email-masked]>
Date: Tue, 12 Aug 2008 17:45:08 +0100

2008/8/8 Micah Cowan <[email-masked]>:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>

I put myself forward as a volunteer.

> differences. Tedious work, obviously.

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

> 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

> out-of-date man page (lacking information on all the nifty new stuff),

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

> enough to scare a few of you into volunteering? ;)

Perhaps.

> the standard ones, currently).

Or use asciidoc or txt2tags, etc.

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

---

From: Juergen Weigert <[email-masked]>
Date: Tue, 12 Aug 2008 20:03:43 +0200

Thomas, thanks for stepping forward!
Personally, I also prefer manpages. Probably mostly because
I know how to search and jump with less.

> fore-runner -- at least an "official" representation of our

Having only a texinfo page, is not that bad.
- one could always do 'info gdb | less' as a workaround.
- It just looks great, when printed on paper.

> Or use asciidoc or txt2tags, etc.

I like that plan!

        cheers,
                Jw.

-- 
 o \  Juergen Weigert      unix-software __/ _=======.=======_     
<V> | [email-masked]         creator    __/        _---|____________\/    
 \  |            0179/2069677      __/          (____/            /\
(/) | ____________________________/              _/ \_ vim:set sw=2 wm=8

---

From: "Thomas Adam" <[email-masked]>
Date: Tue, 12 Aug 2008 19:09:03 +0100

> I know how to search and jump with less.

No worries -- it makes a change from programming for me, but expect
the odd patch now and then.  ;)

>> Or use asciidoc or txt2tags, etc.

Which?  ;)  I'm going to sit tight on this thread for a few days, so I
know the best direction to take.

-- Thomas Adam

---

From: Micah Cowan <[email-masked]>
Date: Tue, 12 Aug 2008 12:08:16 -0700

> I put myself forward as a volunteer.

Thanks very much!

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

That's exactly what I meant by the term "tedious".

> actually reads them;

Obviously incorrect, as I prefer the info manual. Especially since it is
much, _much_ easier to find the node corresponding to a given screen
command via info than via man:

  iscr="info '(screen)Command Index'"
  iscr shelltitle
  iscr hardstatus
  iscr zombie

The equivalent for man is typing "/^[[:space:]]*shelltitle<RET>". and
good luck if your command corresponds to a real word that shows up at
the beginnings of lines...

Taking away the easiest-to-navigate documentation (and the only one with
a set of indices) seems counter-productive.

> I seriously suggest we just make the manpage a

Removing the Texinfo documentation for a GNU project is, simply, not an
option. It's the choice that was made by making it a GNU project.

> people supposed to know/remember which manpage to refer to?

In what way are you disagreeing with me? One for screen, and another for
screenrc, _would_ be splitting the manual up. The only disagreement we
seem to have is how many splits to make, apparently. IMO, having even
just two manpages would be a significant improvement.

Anyway, enough ranting... down to logistics. It seems simplest to me for
you to have push access on git. For that, you'll need to register an
account with Savannah (if you don't have one), submit a public ssh key
you'll use to identify yourself for pushes, and request membership to
the Screen group.

- --
Micah J. Cowan

---

From: "Thomas Adam" <[email-masked]>
Date: Tue, 12 Aug 2008 20:13:36 +0100

> just two manpages would be a significant improvement.

I was disagreeing with having a manpage for caption/hardstatus, one
for window layouts, etc.  If there's going to be any split files, then
I agree (for now -- unless there's some flurry of documentation from
elsewhere  :P) that having screen(1) and screenrc(5) is something I
too would welcome.

> you'll use to identify yourself for pushes, and request membership to

Okey dokey.  Will do so shortly after dinner.  Thanks very much!

-- Thomas Adam

---

From: Micah Cowan <[email-masked]>
Date: Tue, 12 Aug 2008 12:16:10 -0700

> Okey dokey.  Will do so shortly after dinner.  Thanks very much!

Are you kidding? Thank you! You're either saving me a ton of work, or
saving Screen from quality issues due to a woefully out-of-date manpage. :)

- --
Micah J. Cowan

---

From: "Trent W. Buck" <[email-masked]>
Date: 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

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.

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

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.

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

---

From: "Trent W. Buck" <[email-masked]>
Date: Wed, 13 Aug 2008 11:18:57 +1000

On Tue, Aug 12, 2008 at 08:03:43PM +0200, Juergen Weigert wrote:
> - [texinfo] just looks great, when printed on paper.

On GNU systems, at least, "man -Tps" results in a reasonably good
paper version, unless the manpage author made formatting blunders that
weren't apparent on his tty (such as using 'foo' instead of `foo').

PDFs generated in this way unfortunately don't have clickable
hyperlinks and don't have a PDF ToC; I suspect texinfo (by way of
LaTeX) wins on both those points.

---

From: "Trent W. Buck" <[email-masked]>
Date: Wed, 13 Aug 2008 11:22:04 +1000

> the beginnings of lines...

In Emacs' info reader, the "jump to index entry" and "jump to
subsection" commands also autocomplete, so it's easy to see what your
choices are (by hitting TAB twice).

---

From: Juergen Weigert <[email-masked]>
Date: Wed, 13 Aug 2008 16:55:26 +0200

> know the best direction to take.

The choice of weapons is yours.
What I wanted to say is, I am glad you know a range of tools that could help with
automation. I had no such tools for years, and tried to keep them both in
sync manually, which was always a pain.

So your plan looks like this:
- compare man and texinfo, 
- bring them back in sync 
- (later) find a tool to generate both from one source

right?

        cheers,
                JW.

---

From: "Thomas Adam" <[email-masked]>
Date: Wed, 13 Aug 2008 15:56:27 +0100

> - (later) find a tool to generate both from one source

Yep.  Spot on.  :)

-- Thomas Adam

---

From: Stephane Chazelas <[email-masked]>
Date: Wed, 13 Aug 2008 16:45:38 +0100

On Wed, Aug 13, 2008 at 04:55:26PM +0200, Juergen Weigert wrote:
[...]
> - (later) find a tool to generate both from one source
[...]

About that, zsh uses yodl as a format that is then used to
produce texinfo and man pages. The result is good at least on
the info side.

So you may want to consider that. I don't know what other
projects use.

-- 
Stéphane

---

From: Geraint Edwards <[email-masked]>
Date: Wed, 13 Aug 2008 17:09:57 +0100

Juergen Weigert <[email-masked]> said
> - (later) find a tool to generate both from one source

Count me in.  I much prefer manpages to texinfo,
so I'm keen to help keep them in sync.

-- 
Geraint A. Edwards (aka "Gedge")
[email-masked]

---

From: "Aaron Davies" <[email-masked]>
Date: Fri, 15 Aug 2008 16:07:38 +0800

> So you may want to consider that. I don't know what other

funny you should mention that--the zsh list in the middle of a thread
called "Yodl has been discontinued for 13 years... zsh still uses it
for texi docs?" otoh, their consensus seems to be that it would be
hard enough for them to move to some other tool that they should
become the new yodl maintainers....
-- 
Aaron Davies
[email-masked]

---

From: "Thomas Adam" <[email-masked]>
Date: Fri, 15 Aug 2008 09:26:01 +0100

> become the new yodl maintainers....

Well, I already have a few candidates in mind as potential
single-source markup; yodl was never one of them, and certainly won't
be now.

-- Thomas Adam