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 <[EMAIL PROTECTED]> - 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
_______________________________________________ screen-users mailing list screen-users@gnu.org http://lists.gnu.org/mailman/listinfo/screen-users
