Re: [Refdb-devel] Docs in split packages

[Markus H. <mar...@mh...>]

David Nebauer <dav...@sw...> was heard to say:

> Hi Markus,
>
> I've been thinking about Justus' suggestion to split the Debian package
> into server and client.  You clearly anticipate such an eventuality with
> the 'disable-[server|clients]' configure flags.  Most of the machinery,
> in fact, is already available to build separate packages.  I can see
> only one problem: the monolithic documentation.  It cannot be split
> during the build process.  At the moment the choice would be building
> full documentation in both, or only one, of the packages.  Both
> approaches are obviously less than perfect.
>
> Have you considered splitting refdb's documentation into two parts --
> able to be installed individually but, when installed together, making a
> cohesive whole?
>
> Or perhaps there is another approach?

Well, a third approach is to build the docs as a separate package and make both
the client and the server package depend on it. This would require a few minor
changes to configure.in.

Splitting the docs is a non-trivial task as I've put a lot of work into
cross-linking the contents. The only part of the docs which could be built
separately is the reference manual which is composed mostly of the man pages.
But then you'd end up with a client reference manual, a server reference
manual, and a maintenance/usage manual. The latter would contain large parts of
the installation and administration stuff that most users would probably expect
in the client or server manuals. I guess this makes the separate docs package
the more obvious choice.

Could you please check whether the Debian policy has specific requirements for
the docs? I mean, the proper man pages would be installed anyway with both the
server and the client package. If the Debian policy doesn't mind, you could
even make the docs package recommended instead of required, for those who want
to access the docs through the internet.

regards,
Markus


-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de