manpage dbx

[Joost van Baal]

On Mon, Jun 25, 2001 at 02:34:21PM -0400, Francis J. Lacoste wrote:
> On Mon, Jun 25, 2001 at 11:55:39AM +0200, Joost van Baal wrote:
> > > i like dbx, because is can be integrated with the manual's very well...
> > 
> > I don't like to ship a manpage twice: in the Lire User Manual and as a
> > stand alone manual.  I believe that in general, if a unix user wants to
> > read a manpage, she fires up a manpage viewer.  People don't go look in
> > the Lire User Manual to read the lr_xml2pdf manpage.
> > 
> 
> You're right here Joost : man page are online documentation which you read
> using man(1). But again, in the Reference section of the User Manual (see
> the proposed manual toc), there should be documentation about all user
> programs.  Including as reference directly the man page has the advantage of not
> having to maintain two different versions of the "Reference" material.

Of course, if we want complete documentation about commands to appear
in the Lire User Manual, we should use the same source for this as the
manpage sources.

However, if we include this, the tarball will grown in size, since every
manpage will have to get included twice.  FYI: There are 49 manpages being
shipped with lire now.  The stuff which gets installed in share/doc/lire
is about 800k now:

 93k    bin
 64k    etc
272k    libexec/lire
809k    share/doc
  4k    share/lire/sgml
 26k    share/lire/xml
 46k    share/perl5
359k    man

(BTW: we should get rid of installing *.tex in share/doc/lire)

> What I don't like too much about the DBX format (and for the way that some
> POD is used right now) is that the reference documentation is
> in a separate file than the program it documents. This makes it more easy 
> for the man page and the program to drift. (As opposed to having the POD
> man page directly in the program). 

Absolutely.

> If we want to keep POD, I would like
> to look for a way to embed the POD directly in the shell script (like
> we can do for perl script).

Should not be too difficult, and would be nice indeed.  (Wild guess:
just say:

 <shell code>

exit 0
=pod

 <pod code>

)

Bye,

Joost


-- 
To UNSUBSCRIBE, email to development-request at logreport.org with a subject of
"unsubscribe". Trouble? Send an email with subject "help" to
development-request at logreport.org