[gentoo-doc] Project-specific documentation and dynamic documentation index

[Sven Vermeulen]

Hi all

Xavier kindly pointed me to a problem I'm now facing with the documentation
metadata that allows us to dynamically generate a documentation index.

Let me first restate why a dynamical documentation index is preferred imho:
- Ease of maintenance
- Hierarchical separation
- Removing duplicate documentation summary

A draft on the dynamical index can be found online at
http://www.gentoo.org/doc/en/index-dyn.xml

Using the metadoc, we can easily create a page that lists all Gentoo
documentation on a single page, without the additional summaries. 

A draft on this can be found online at 
http://www.gentoo.org/doc/en/list-dyn.xml

A final feature is creating an overview for translations in which they can
see the translated files, their version, and the version of the master
English file.

A draft on this can be found online at
http://wren.gentoo.org/doc/nl/overview-dyn.xml

Regarding the "Members" and "Bugs" chapters, a better example is the English
overview page, http://www.gentoo.org/doc/en/overview-dyn.xml

Now on to the issue: the XSLT code we use sources the linked documents to
get their version, summary, title, etc. As long as all documents exist, this
isn't a problem. However, when a document is removed from CVS, sourcing the 
inexisting document yields a "Internal Server 500" error which just doesn't
look nice.

When dealing with /doc/${LANG} documents, this isn't such a major issue
because we control our repository ourselves. Iow, when I would remove
alsa-guide.xml from the repository I should know that I have to remove the
file from the metadoc as well.

However, when dealing with project-specific documentation (such as the
Hardened Docs), the responsibility of the document itself is in hands of the
project documentation developer, not ours. This also means that "they" will
undoubtedly (re)move their documents without prior notice to the
documentation team. Each such action will lead to a "Internal Server 500"
error.

Their are a few solutions to this:

We can ignore the issue and "wait" for the projects to (re)move their
documents and hearing from our users that the index page doesn't work
anymore. This sounds like a no-go, yet not all indexes would fail, only
those that explicitly would list the document (index-dyn.xml originally
doesn't list any documents, you need to select a category). Imho, it's still
a no-go though.

We can ask the projects that we would like to list their docs on our
documentation index page as well, but that this would mean that they can't
(shouldn't) (re)move those documents without atomically updating the
metadoc.xml file. This might work, but requires continuous awareness.

We can implement any QA-tool on client-side ("repodoc") and keep asking all
developers to use repodoc to operate on xml files. Since they're usually
used to working with repoman, I don't think too much objections will be
stated.

We can implement a QA-tool on server-side (extend the current XML-Checker)
that verifies if the removal of a file can happen (see if the file is listed
in the English metadoc.xml) and, if not, issue an error.

We can request the used xml parsers on our webnodes to return an empty
node-set instead of generating an error and update our XSLT to verify if the
returned node-set is empty. If it is, ignore the document. We can then
create a new chapter in the overview-dyn.xml document that lists all
non-existing documents.

This latter solution is possible with Xavier's gorg application but has the
drawback that any other issues with missing xml files (for instance,
checking a handbook that lacks some files) will need to be covered in the
XSLT as well. The advantage is however that a nicer error can be shown to
the user that has a bit more information.

Thoughts, ideas?

Wkr,
      Sven Vermeulen
      

-- 
  Documentation & PR project leader

  The Gentoo Project   <<< http://www.gentoo.org >>>