Documentation Requirements

Purpose of this page is to collect the requirements, which must or should be met in case we want to change the documentation file format (source language). See Bug 722016 - We should change the Documentation file format.

Target Languages by OS or Environment

Linux

Yelp

Docbook, Mallard (Gnome only), DITA (experimental), man, info, and HTML

KHelpcenter (alternative, currently unsupported)

Docbook, man, info, and HTML

Macos, WWW

HTML

Windows

CHM (aging)

Paper

PDF

Several Mobiles, Tablets etc.

EPub, Mobi

Other Criteria

Semantic vs. descriptive Markup

Descriptive languages use direct formatting like <bold>, <italic>, ... while in semantic languages you mark the meaning <guilabel>, <title>, ... and the rest is done by stylesheets like XSL, CSS, .... That will lead to a more consistent appearance.

I18N

We want also create translations in an easy way, also in non-latin writing, currently having japanese and cyrillic. How difficult is the conversion of existing translations?

Links, indexes etc

We want to link inside and between documents, generate lists of Equations, Figures, ...

Variables/Macros

There a many things like URLs, appname, version, which we want to define at one place and use at several others.

Software Stability

For a project, which evolved over 2 decades this is an important criterium.

First and last release

There should be several years of active development. If the last release was several years ago, it can be considered "dead".

Major reference projects

Do they have a major community of users?

Source Languages

Docbook

Semantic markup, all target languages supported by XSLTs or FOP.