Documentation
From Friend2Friend Wiki
The ideal goal of the documentation would be a wide range of formats generated from a single set of XML sources. Currently, the documentation sources are:
- About 12 Open Document Presentations http://altruists.org/ff
- The F2F core and module files. The F2F documentation module (http://friend2friend.net/modules/documentation/) processes these into Docbook files
- This wiki (Mediawiki - so will probably never be XML)
Contents |
Important Document Formats
All the relevant formats are namespaced XML. There is no clear 'winner'.
Docbook
xmlns:docbook="http://docbook.org/ns/docbook"
Widely supported, early format for tehnical documentation, comes with a lot of XSL to export from Docbook. We are using v5.0 (the latest) for the documentation module. It goes slightly beyond the basic HTML style tables, lists etc. However, intended for technical manuals, it is lacking in colour and traditional style features. Customisable, but this would require study.
Open Document
xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0"
OASIS standard? Used by Sun, Open Office etc.
Office Open
M$-backed ISO standard. Widely criticised as an XML-isation of their archaic ".DOC" format, including a bunch of legacy garbage, introduced only because of the number of government who are mandating use of open document formats.
D.I.T.A.
xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
OASIS standard that is suggested as a rival to Docbook. Spreadsheets at http://trac.agavi.org/browser/documentation/branches/felix-build-scripts-rewrite/DITA-OT1.5/xsl to convert to Docbook, (X)HTML, RTF, troff, hhc etc.
Format Conversion
As an XML pipelining framework, F2F project is uniquely well suited to XSL-based transforms, as opposed to other languages, or software-based document convertors. XSL stylesheets are the only area of interest for automated documentation production within F2F.
Templates
The main sources are DOCBOOK & OpenOffice.
| Template | From | To | Origin | Notes | Summary |
|---|---|---|---|---|---|
| Documentation module | Core + Module XML files | #Docbook | F2F | Works, improvements would help | ? |
| dbk2ooo.xsl | #Docbook | #Open Document | DocBook 1.74.3 | Untested | ? |
| opendoc2xhtml.xsl | #Open Document | XHTML | OpenOffice 3.1.1 |
| OK for documents without pictures |
| odt2mediawiki.xsl | #Open Document | MediaWiki | OpenOffice 3.1.1 3rd party | Not so far got it to work much. | ? |
| ooo2wordml.xsl v1.10 | #Open Document | #Word 2003 | OpenOffice 3.1.1 | Untested | ? |
...
ToolChains
Idea is to automate the creation of a bunch of DOCs
- XML -> Docbook -> XHTML (Doc Module)
Use zip-expand service and then feed into toolchain.
Relevance to F2F
How to process the documentation?
