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
--
To UNSUBSCRIBE, email to debian-qt-kde-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110113065826.GA9945@burratino
