From Fedora Project Wiki

(Sarma isn't viable considering it hasn't been touched in 3+ years.)
(bumping the section levels)
Line 1: Line 1:
= Innovative Approaches =
== 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.
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 ==
=== Wiki into DocBook ===


The [[DocsProject/MoinDocBookProject/Status|  MoinMoin Wiki converter]]  aims to "improve and facilitate the use of the Doc<code></code>Book format, inside a Moin<code></code>Moin-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 Doc<code></code>Book XML format. Much progress has been made, with the goal to merge the code with the upstream Moin<code></code>Moin 1.6 release.
The [[DocsProject/MoinDocBookProject/Status|  MoinMoin Wiki converter]]  aims to "improve and facilitate the use of the Doc<code></code>Book format, inside a Moin<code></code>Moin-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 Doc<code></code>Book XML format. Much progress has been made, with the goal to merge the code with the upstream Moin<code></code>Moin 1.6 release.


== Sarma ==
=== Sarma ===


One new approach the GNOME team is working on is Sarma, an online editor with Doc<code></code>Book 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.
One new approach the GNOME team is working on is Sarma, an online editor with Doc<code></code>Book 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.
Line 13: Line 13:
This is in contrast to our current approach, which requires knowledge of an editor like Emacs, Doc<code></code>Book XML, and CVS, along with the installation of some additional software packages.
This is in contrast to our current approach, which requires knowledge of an editor like Emacs, Doc<code></code>Book XML, and CVS, along with the installation of some additional software packages.


== Doxygen ==
=== Doxygen ===


"[http://www.stack.nl/~dimitri/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.
"[http://www.stack.nl/~dimitri/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.
Line 25: Line 25:
3. You can even <code>abuse' doxygen for creating normal documentation (as I did for this manual) ''[reference is to online doxygen manual] ''."
3. You can even <code>abuse' doxygen for creating normal documentation (as I did for this manual) ''[reference is to online doxygen manual] ''."


== OOo2DBK ==
=== OOo2DBK ===


[http://www.indesko.com/telechargements/ooo2dbk/ OOo2DBK]  "converts Open<code></code>Office.org documents into Doc<code></code>Book XML. The OOo2DBK package gives access to a set of tools which makes it possible to use Open<code></code>Office.org as an editor for Doc<code></code>Book documents.
[http://www.indesko.com/telechargements/ooo2dbk/ OOo2DBK]  "converts Open<code></code>Office.org documents into Doc<code></code>Book XML. The OOo2DBK package gives access to a set of tools which makes it possible to use Open<code></code>Office.org as an editor for Doc<code></code>Book documents.
Line 33: Line 33:
''Translated from the French''
''Translated from the French''


== A Distributed Content Model for Developer Documentation ==
=== A Distributed Content Model for Developer Documentation ===


(This was introduced to FDP in [http://www.redhat.com/archives/fedora-docs-list/2006-October/msg00043.html this mail list posting] .  The follow thread starts in [http://www.redhat.com/archives/fedora-docs-list/2006-December/msg00065.html this message] .)
(This was introduced to FDP in [http://www.redhat.com/archives/fedora-docs-list/2006-October/msg00043.html this mail list posting] .  The follow thread starts in [http://www.redhat.com/archives/fedora-docs-list/2006-December/msg00065.html this message] .)

Revision as of 23:11, 31 December 2008

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 OpenOffice.org documents into DocBook XML. The OOo2DBK package gives access to a set of tools which makes it possible to use OpenOffice.org as an editor for DocBook documents.

The ooo2dbk Python script allows the export of an OpenOffice.org file into DocBook XML. This script also makes it possible to manage images included in the document, using ole2img and pyUNO to export OLE objects as images."

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