man pages

Panu Matilainen pmatilai at laiskiainen.org
Mon May 29 09:44:42 PDT 2006


On Mon, 2006-05-29 at 07:24 +0200, Ralf Corsepius wrote:
> 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.

Seems to work as advertised :) Applied, thanks!
The fr/es/pt_BR translations aren't built at all now but considering how
totally out of date those are it's not much of a loss. We can add them
back if somebody provides updates to them someday.

> 
> > 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.

Like said, moving things around / renaming is fine by me, but I think
this is already a nice improvement as is.

	- Panu -




More information about the Apt-Rpm mailing list