Re: Man pages missing

Re: Man pages missing

[ead]

Richard et al.,

Richard Coleman <coleman@math.gatech.edu>:
] ] Is it me, or has the documentation become a rat's nest, i.e., g/n/troff,
] ] TeX, texinfo and now yodl?  Just what we need, another text formatting
] ] package to learn. :-)  Sorry to sound negative, but when is the progression
] ] of manual preparation going to stick with one package?  If I run across
]
] But yodl is an attempt to bring order to this mess.  We've been
] searching for some time for a set of tools and meta-document format
] that would allow us to generate all the formats necessary, while
] maintaining only one document base.  I researched the problem
] when I was maintainer of zsh, but I couldn't find a solid (and
] free) solution.

I'm not a fan of yodl. Why? Because I've never heard of it before. And
because I have heard of other tools that have proven their utility.

I would think that if you didn't find Texinfo suitable, that POD (Plain
Old Documentation), the documentation format used by the Perl project,
would satisfy. pod2text(1) and Pod::Text(3) come with the Perl5
distribution, and there are pod2man(1), pod2html(1), pod2latex(1), and
pod2fm(1) converters available elsewhere. You can find out more about
POD by:

    * visiting <URL:ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/modules/
      by-module/Pod/PodParser-1.00.readme>

    * viewing the perlpod(1) manual page on a system where Perl5 is
      installed

Be well,
Eric De Mund <ead@ixian.com>
http://www.ixian.com/ixian/ead/

"It's harder to solve people's problems than it is to design really neat
products." --Stewart Alsop

Re: Man pages missing

[Richard Coleman]

> I'm not a fan of yodl. Why? Because I've never heard of it before. And
> because I have heard of other tools that have proven their utility.
> 
> I would think that if you didn't find Texinfo suitable, that POD (Plain
> Old Documentation), the documentation format used by the Perl project,
> would satisfy. pod2text(1) and Pod::Text(3) come with the Perl5
> distribution, and there are pod2man(1), pod2html(1), pod2latex(1), and
> pod2fm(1) converters available elsewhere. You can find out more about
> POD by:

You should give us some credit.  (When I was maintainer) I researched
this option as well as several other (pod, linux-doc, texinfo, ...)
None of these fit all our criteria, although pod was the closed.

Pod has some limitations.  Chief among them is that you cannot
put tags such as bold or italics in code fragments.  The zsh man pages
do this in many places in order to illustrate various syntatic things.
Also pod doesn't contain enough information to automatically create
html or texinfo files.  There are translators for them, but the output
requires manual changes and additions (I just downloaded the texinfo
files for Perl today, and the README contained with it says exactly
this).

linux-doc is nice for some things, but (at the time) did not have
a translator for man pages.  That kills it as a choice.

yodl seems to be a nice tool.  Give it a chance before you condemn
it.  If it doesn't work out, we can change formats again.

rc

Re: Man pages missing

[Peter Stephenson]

Juergen Christoffel wrote:
> I second Vidiot's suggestion to separate (a set of) terse man page(s)
> and a much larger/better manual. I'd even be willing to help in
> putting the latter together.

I have to say I'm very much against reducing the man pages.  It's more on
the theme of `what the average system administrator actually does', which
is install the man pages and no other documentation.  In my experience
(not theory, this is a real problem I've often had) if the information
disappears from the man pages it's simply not made available to the
user on a great many machines.

-- 
Peter Stephenson <pws@ifh.de>       Tel: +49 33762 77366
WWW:  http://www.ifh.de/~pws/       Fax: +49 33762 77413
Deutsches Elektronen-Synchrotron --- Institut fuer Hochenergiephysik Zeuthen
DESY-IfH, 15735 Zeuthen, Germany.