[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: doc compilations: build-time or pre-built?

On Tue, Jul 04, 2006 at 09:04:48PM -0300, marciotex@gmail.com wrote:
> tony mancill <tmancill@debian.org> writes:
> > Steinar H. Gunderson wrote:
> >> On Tue, Jul 04, 2006 at 07:25:16PM -0300, marciotex@gmail.com wrote:
> >>> 1) compile docs pre-build-time; or
> >>> 2)  compile docs in build-time
> >> 
> >> Definitely the latter. We build stuff at build time for a reason,
> >> architecture-specific or -independent alike.
> >
> > Is this the consensus/best-practice on this question?
> >
> > It seems like it would be quite taxing on the autobuilders to have to pull
> > something like docbook (and its chain of dependencies) into a pbuilder just
> > to recompile a manpage that doesn't change between architectures.
> >
> > I'm interested in this because I've typically done (2), but have recently
> > started to think that (1) is more appropriate, particularly for packages
> > where the documentation is a simple manpage.
> And It's exactly this the case in question, for me.

The SGML template for manpage is there to help producing decent usable
manpage for novice packager.  I think it is useful only for intial
packaging.  I usually erase SGML file and update groff source of the

NM guide states;
5.8 manpage.1.ex, manpage.sgml.ex

Your program(s) should have a manual page. If they don't, each of these
files is a template that you can fill out.

Manual pages are normally written in nroff(1). The manpage.1.ex example
is written in nroff, too. See the man(7) manual page for a brief
description of how to edit such a file.

If on the other hand you prefer writing SGML instead of nroff, you can
use the manpage.sgml.ex template. If you do this, you have to:

    * install the docbook-to-man package

    * add docbook-to-man to the Build-Depends line in the control file

    * remove the comment from the docbook-to-man invocation in the
    * `build' rule of your rules file

Note here of "normally written in nroff".  

So use of nroff source is better.


PS: This section was not touched by me :-)

Reply to: