doc-base sections (Re: doc-base revisited)

[Jonathan Nieder]

Robert Luberda wrote:
> On 11.01.2011 09:27, Jonathan Nieder writes:

>>  * The registered documentation is very sparse.  It is not obvious
>> where any given kind of information is to be found (the categories are
>> especially unhelpful and I suspect something more faceted like debtags
>> might do a little better).
[...]
> There's a similar request in bug#171955, and in general it would be nice
> to have such thing implemented in both doc-base and frontends like dwww
> or dhelp. I'm aware that currently is quite hard for maintainer to
> choose the most appropriate section
[...]

Okay, I'd like to start with this.  Surely there is some cross-desktop
and cross-distro prior art for documentation categories, right?
[1][2][3][4][5][6][7]

Oh.  Well, what do yelp and khelpcenter4 do, then?

yelp has tables of contents in data/toc.xml and data/scrollkeeper.xml,
like so:

 <toc id="Core">
   <title>Desktop</title>
   <description>Welcome to the GNOME Help Browser</description>
   <toc id="Accessibility" icon="accessibility-directory">
     <title>Accessibility</title>
     <description>Learn more about making your system more accessible for a range of disabilities</description>
   </toc>
   <toc id="GNOME">
     <title>GNOME Applications</title>
 [...]

The categories are imho better in many ways than the current list from
doc-base.txt (e.g., it has a category for version control, which is
what I was last looking for) but they are far from perfect.  Seems to
be based on the XDG Menu specification[8].  Each document's rarian
metadata file includes a semicolon-delimited of categories from that
spec.

rarian's docs/rar-mdf.xhtml[9] describes the preferred metadata
format.  omf files work and the documentation says they are preferred
for compatibility, too.

KHelpCenter uses .desktop files, with a hierarchy of .desktop files
determining the hierarchy of documents displayed[10].

The toplevel table of contents:

 Welcome to KDE
 KDE Users' Manual
 Application Manuals (organized according to the menu spec)
 Control Center Modules
 KInfoCenter Modules
 Kioslaves
 Scrollkeeper - Additional non-KDE documentation
 Plasma Manual - documentation for the core interface
 Tutorials
 Unix Manual Pages (organized by section)
 Browse Info Pages (uses dir.info)
 The KDE FAQ
 Contact Information
 KDE on the Web
 Supporting KDE

Also notable is the X-DOC-Weight field, which allows "heavier" manuals
to be shown below "lighter" documents.

This sort of categorization seems quite valuable to me.  I would
like to separate

 - tutorials and how-to documents
 - papers/articles covering some specific topic in depth (still for
   users)
 - specifications (file formats, protocols, etc) and design documents
 - command-line reference (perhaps by requiring that such
   documentation be provided as man pages/info pages and not be
   registered separately)
 - API documentation
 - user manuals
 - GUI help collections

To start, it seems most important to separate the user manuals and GUI
help from the rest.  That is somewhat orthogonal to the application
hierarchy.  This could be achieved by adding a new (optional at first)
field to .doc-base files indicating what role the documentation is
meant to play.

> I agree, it would be a good idea to have some team to review the
> doc-base files, especially that something similar is already done for
> debconf templates and packages' descriptions.

Given a way to register translations (and translations of abstracts)
it should be easy to justify "volunteering" debian-l10n-english to
help with editorial control over the English version.  Maybe even
without (would have to ask).

Thanks, that was helpful.

Jonathan

[1] 2003-12-07: discussion on documentation system begins on xdg-list.
    http://lists.freedesktop.org/archives/xdg/2003-December/001306.html
[2] 2003-12-10: "All I really need from the help system is a listing of
                the documents installed, though having more metadata is
                always better than less."
    http://lists.freedesktop.org/archives/xdg/2003-December/001370.html
[3] 2004-01-04: "At this point, I've basically agreed on desktop files as
                the metadata format."
    http://lists.freedesktop.org/archives/xdg/2004-January/001488.html
[4] 2005-05-17: first draft of a help system spec based on .desktop files
    http://www.freedesktop.org/wiki/Standards/help-system?action=recall&rev=1
[5] 2007-03-22: latest version of that help system spec
    http://www.freedesktop.org/wiki/Specifications/help-system
[6] 2010-04-16: the latest spec, based on a /usr/share/help/ directory.
                "This does not provide a mechanism for installing metadata
                 files. I'm not really interested in doing that anymore, and
                 nobody else seemed to want it either. I can go into reasons
                 why I don't think it matters if anybody wants to hear it."
    http://lists.freedesktop.org/archives/xdg/2010-April/011443.html
[7] 2010-05-07: more precisely:
    "My general take is that document formats can embed metadata, so
     there's no need to provide a separate metadata file. We can look
     at index.page or index.docbook or index.html and grab the title.
     If we need any other metadata (and I suspect there is metadata
     that would be useful), we can figure out ways to encode it into
     the document files. And we can talk about those things on the
     list and add them to this specification."
    http://lists.freedesktop.org/archives/xdg/2010-May/011486.html
[8] http://standards.freedesktop.org/menu-spec/latest/apa.html
[9] http://rarian.freedesktop.org/Releases/rarian-0.8.1.tar.bz2
[10] http://websvn.kde.org/*checkout*/trunk/KDE/kdebase/runtime/khelpcenter/README.metadata?revision=739398&pathrev=848326