Innovative Approaches
This section covers new approaches as we collectively discover and/or devise them. The tools listed below are tools that are difficult to categorize. The sections following this section address the tools available for GNOME, KDE and Java environments, respectively.
Wiki into DocBook
The MoinMoin Wiki converter aims to "improve and facilitate the use of the DocBook format, inside a MoinMoin-wiki". In other words, by using an agreed subset of the MoinMoin wiki markup language, writers and editors can do distributive online editing, which is then easily converted into valid DocBook XML format. Much progress has been made, with the goal to merge the code with the upstream MoinMoin 1.6 release.
Sarma
One new approach the GNOME team is working on is Sarma, an online editor with DocBook XML import and export support. CVS commits are handled automatically. Refer to http://live.gnome.org/LiveDocumentationEditing for further details. However, this project hasn't been touched in over three years.
This is in contrast to our current approach, which requires knowledge of an editor like Emacs, DocBook XML, and CVS, along with the installation of some additional software packages.
Doxygen
"Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.
It can help you in three ways:
1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX} from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
3. You can even abuse' doxygen for creating normal documentation (as I did for this manual) [reference is to online doxygen manual] ."
OOo2DBK
OOo2DBK "converts Open
The ooo2dbk Python script allows the export of an Open
Translated from the French
A Distributed Content Model for Developer Documentation
(This was introduced to FDP in this mail list posting . The follow thread starts in this message .)
"The OSDL DTL Technical Board (organized) an IRC session on developer
documentation. This (was) a follow up to discussions that took place on the
first OSDL Desktop Architect Meeting and in preparation of DAM III where we would like to move this topic forward.
At the first Desktop Architects meeting (Dec, 2005) it was found that
ISVs have difficulty finding documentation, and choosing between
alternative libraries and tools. ISVs would like a site with complete,
up-to-date, high-quality Linux documentation. They need roadmaps
(perhaps more than one). There's a lot of misleading documentation out
there which discusses deprecated interfaces as if they were preferred;
the site should help people avoid those.
A key concern raised with respect to any portal is the maintenance
burden. The only viable way to guarantee that information in a
development portal is kept up to date is through a strong relation with
upstream projects that can provide key information with authority.
Another requirement to take into account is the desire of OSVs to point
their customers to a company site that reflects more closely their
products instead of a third party site.
The above requirements hint towards a distributed content model that
facilitates multiple distinct content owners with a feedback mechanism
to route feedback back to the authorative content owner. It may be that
the solution to the documentation problem will not be so much a single
documental portal but more so a standardized documentation
infrastructure that the various stakeholders can tap into; as a consumer
of content, as a provider of content, or as a combination of the two.
See
http://developer.osdl.org/dev/desktop_architects/index.php/Key_Topics#Developer_Portal for more information.
Previous Page - Advancing the Project
Table of Contents
Next Page - GNOME Tools