Re: Man-writing volunteers?

[Øyvind A . Holm]

On 2008-08-09 14:53:10, Trent W. Buck wrote:
> On Fri, Aug 08, 2008 at 01:20:03PM -0700, Micah Cowan 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.
>
> Surely texinfo can be automatically converted into a roff manpage?

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>

> > Actually, though, as it stands, a big-hulking man page strikes me as 
> > 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?

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 <address@hidden> - 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 |-------------+

signature.asc
Description: Digital signature