Documentation Planning Session
We will be discussing a Grand Unified Documentation System to be adopted by the various free desktops and applications. Current, desktop environments provide their own documentation systems, and applications must either depend on one desktop, or roll their own system.
We will consider the needs of the existing desktops, as well as third-party applications such as the GIMP, look at the strengths and weaknesses of each system, and design a shared system to meet everybody's needs.
There is a lot of room for improvement in help systems and help file formats. However, we should concentrate only on the base problems that prevent us from having a common help system. Other problems and improvements can be tackled later. The following problems must be addressed:
- How are documents found by the help system?
- How are documents uniquely identified?
- How are documents categorized in a help browser?
- How do applications invoke their help file?
If people come to the session having thought about these problems, we can probably hammer out some answers pretty quickly. If you plan to attend, please add your name under 'Who's Coming' at the bottom of this page.
Wiki discussion
Wiki discussion is going on on the freedesktop.org wiki. Please go there and add your own thoughts. We should be able to come to lots of conclusions before we get to guadec.
Chris' suggestions about what to talk about
How do you specify chunks inside a document?
In my write up, I specify the way that KDE currently does it. Another possibility might be to specify chunks as part of a document using #. This is slightly different than the usual use of # because you can't just scroll to the other #s.
If we switch to using #s, then all of a sudden, you can reference multiple xml files inside a single directory.
I grow less happy with the way kde currently does it. I think we should use #s.
Do we specify the ability to use file: uris to reference chunks? (and perhaps ghelp: for backward compat?)
This is heavily related to the above comment. It would be useful to handle any chunk inside any docbook xml that happens to be on the file system.
How do you display a TOC of the chunks inside a document?
This is written up in my spec, but maybe that's a mistake. We should do some user teseting on a couple different methods here. Expansion like in KDE and my spec, replacing the TOC, any other suggestions.
KDE backward compat
KDE currently already uses the help: but it doesn't use XDG_SHARE_DIRS as well as having a few other problems (It should be help instead of doc. Why are xml documents under HTML?) How do we solve this problem? Do we just search both locations when we see help: Do we use a different string as our uri domain (fdo-help: or something nicer than that?)
Who's Coming?
Shaun McCance, Yelp maintainer and GDP lead
- Roman Joost, GIMP documentation lead
Sven Neumann, GIMP developer (hopefully Roman can get him to this session
- JPR, Chris' boss