man pages

[Ralf Corsepius]

On Sun, 2006-05-28 at 23:52 +0300, Panu Matilainen wrote:
> On Sun, 2006-05-28 at 19:22 +0200, Ralf Corsepius wrote:
> > On Sun, 2006-05-28 at 14:47 +0300, Panu Matilainen wrote:
> > > On Sun, 2006-05-28 at 11:29 +0200, Dag Wieers wrote:
> > > > On Sat, 27 May 2006, Vincent Danen wrote:
> > > > 
> > > > > * Panu Matilainen <pmatilai at laiskiainen.org> [2006-05-27 21:08:59 +0300]:
> > > > > 
> > > > > > Please use the sgml/xml documentation format. It's nice for creating
> > > > > > non-manpage documentation, but I certainly agree having to "compile" man
> > > > > > pages is silly. I wouldn't be against somebody submitting a patch to
> > > > > > make "make dist" build the documentation as well for inclusion in
> > > > > > distribution tarballs, hint hint :)
> > > > > 
> > > > > Yeah, but the problem with sgml/xml documentation is you need to have
> > > > > the appropriate dtd's and whatnot available... I could only do so by
> > > > > either a) adding about a half-dozen or so packages to Annvix (for use by
> > > > > a single package in *compiling*, nevermind day-to-day use), or b)
> > > > > compile them on a Mandriva system and make a separate tarball.
> > > > > 
> > > > > So forgive me if I'm not too keen on the xml/sgml idea.  =)
> > > 
> > > Re-read my comment, I wouldn't be opposed to having pre-compiled manual
> > > pages in the distribution tarballs, somebody just send me a patch to
> > > make the compilation happen automatically in "make dist".
> > I had a stab at this some weeks ago, but never finished it, because
> > support to ship precompiled man-pages isn't as easy as it seems at first
> > glance, because the apt's manpages' contents isn't static and rather
> > unfortunately placed/packages inside of the source-tree.
> > 
> > So, if we could live with some regression on the man-pages' contents,
> > adding pre-compiled manpages is doable.
> 
> I'd appreciate it, and obviously others would as well.
Cf. the patch below.

[Warning: This patch implements a pretty rough ride and hasn't had too
much testing.]

After having applied the patch, inside of the source tree (and having
having docbook2man installed) run 
./configure --enable-maintainer-mode
cd doc
make
svn add *.8 *.5

Then check in all resulting changes to autogenerated files.

Afterwards, with this patch applied, man-pages will only be generated if
configuring with maintainer-mode enabled (--enable-maintainer-mode) and
if having docbook2man installed. Something, nobody but you (the
maintainer) and developers working on the man-pages will want to do.
Normal users and packagers should never need to do so.

> If things need to be moved around to make it possible/easier, then so be
> it. If we lose some flexibility on the "dynamic" content.. is there
> anything actually *important* in the manuals depending on build-time
> environment? I wouldn't think so.
> 
> Considering the amount of debianisms and out-of-datedness in the current
> man pages real regressions would be hard to achieve I think :)
Right, things are fairly broken ;)

BTW: The dynamical stuff primarily is in doc/apt.ent. In an ideal
sgml-world it would be dynamically generated (e.g. to propagate dirs
into the docs), which then would render all attempts to ship static
man-pages hardly possible without major changes. 
An alternative approach would be to apply @...@ patterns in apt.ent and
to "sed" their actual values from "precompiled man-pages containing
@...@" into "to-be-installed man-pages with @...@ expanded". The latter
would require some re-vamping of the source layout, or renaming the
files.

Ralf


-------------- next part --------------
A non-text attachment was scrubbed...
Name: apt-rpm-rc-20060529-2.diff
Type: text/x-patch
Size: 4252 bytes
Desc: not available
URL: <http://lists.laiskiainen.org/pipermail/apt-rpm-laiskiainen.org/attachments/20060529/d22b14a9/attachment-0003.bin>