Re: Man-writing volunteers?

[Micah Cowan]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Thomas Adam wrote:
> 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.

Thanks very much!

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

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

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

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
> fore-runner -- at least an "official" representation of our
> documentation.

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.

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

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
Programmer, musician, typesetting enthusiast, gamer.
GNU Maintainer: wget, screen, teseq
http://micah.cowan.name/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFIod+g7M8hyUobTrERAu09AJ0dDWIPVfNpq/Maske9hvysG21cqACbB6bf
srOpmdWJqfb4Eh4Hyyng5/k=
=Q5wf
-----END PGP SIGNATURE-----