DPH and a new documentation infrastructure

[Luca Brivio]

Several weeks, Manoj Srivastava wrote:

>         There is a proposal in the rewrite of the policy manual (*sigh*,
>  hopefully deadline pressure from work will yield soon) to allow for an
>  overarching policy multi-part book using docbook XML; with the
>  technical policy manual as one of the parts, and including any other
>  manual as well.
>
>         The idea is to set up the infrastructure to be able to re-order
>  the manual either by priority (MUST follow, SHOULD follow, RECOMMENDED,
>  MAY follow), or by topic, and allow for flexible ordering of the policy
>  manuals.
>
>         The format proposed was to create an XML entity for each policy
>  rule; (or smallest atomic unit of the manual, if not rule based), and
>  annotate it with title, version, priority, subject area.
>
>         If new re-writes of policy like texts can follow a common
>  standard, it would make it easy for people to re-order manuals on the
>  fly, print out subsets, and for sub projects and derivatives to add
>  their specific policies seamlessly.
>
>         If we can also achieve a closer relationship betweeen a policy
>  doc, and a package checker like lintian/linda; then people can get a
>  polic checking done based on the policy manuals included in the base
>  policy spec they are using.

This looked very exciting to me!

I think we should consider the option to edit our packaging handbook as a 
Docbook XML <book>, also because it would be useful to have annotations (e.g. 
author, status, last update time, tags) for each subsection/paragraph of the 
book. I believe we would benefit from such an architecture, but we'd need to 
use it through a wiki.

We are still about to switch to git+Ikiwiki+AsciiDoc (yet waiting for an 
Alioth upgrade). Currently AFAIK Ikiwiki doesn't support Docbook XML as the 
input format in any way.

However, do you think it would be good to have an architecture like that 
described above based on a distributed VCS (such as git) and accessible 
*also* through Ikiwiki (provided that some complexity inherent to the Docbook 
format is hided/managed thanks to an ad-hoc interface for editing the source 
files)?

Any thoughts or suggestions?

P.S. I didn't cc'ed debian-doc at l.d.o. mostly because this email may look 
really obscure. Of course any real discussion should involve more people!

--
Luca