Manual Generation 3.0

From Gramps
Revision as of 10:08, 28 January 2008 by Romjerome (talk | contribs) (wiki text to html)
Jump to: navigation, search

Creation of the GRAMPS manual (docbook/pdf/html) starting from the Gramps 3.0 Wiki Manual. This is a work in progress, no decision has been taken on how to proceed with this.

How creating a manual starting from wiki ?


  1. Wikipedia use Wikimedia DTD, a format based on XML, for sharing his data. SGML, docbook are based on XML too.
  2. We can make a test for exporting our wiki data to Wikimedia DTD.
  3. To generate a script (XSLT, python, perl, sh ?) for parsing data from Wikimedia DTD to docbook/SGML.

Text to XML

  1. All wiki pages are saved as txt: header.txt, preface.txt, chapter_01.txt, ..., which could be included into one file later.
  2. We make a python script to do the conversion for working with txt2tags, maybe sed commands according to txt2tags sample and current Mediawiki grammar or to modify the GPL script for working with mediawiki code. Also, there is possible output filter function on txt2tags which could help us.
  3. Output will be a full gramps.xml/gramps.sgml file with utf8 encoding to avoid non-ASCII characters issues. The present Makefiles in GRAMPS can create html/manual/pdf from these xml files. Possible solution for keeping docbook : OpenJade + DSSSL. Note that yelp may open xhtml too.

We should keep an eye on official developments here: [1]


An alternative is to proceed as Wikibooks do.


wiki2xml is a GPL script for parsing MediaWiki.


wt2db converts a text file in a special format similar to that used in WikiWikiWebs into DocBook XML/SGML

wiki text to html

A Python program can be used to generate html from the text of the Gramps manual wiki pages We can try to translate generated html by using translate toolkit

html2po <html> > <pot>
msgmerge <po> <pot> > <new_po>
po2html -t <html> -i <new_po> -o <new_html> 

where <x> is the file format, use your names.

Manual Text Guidelines

In order for the above scripts to work, we need to limit ourselves to a limited set of templates and syntax in the manual, as we cannot support everything. Hence, the Manual section does not have the full capabilities as a normal Mediawiki.

General textual guidelines

  • Only approved templates may be used. These are
    1. {{grampsmanualcopyright}}: the copyright template. This will be stripped out on manual generation.
    2. {{man label|Labels}}: template for GUI elements, example: Labels
    3. {{man button|Buttons}}: template for GUI buttons Buttons
    4. {{man tip| 1=title |2=text.}}: template to add a tip in the text
    5. {{man note| title |text}}: template to add a note to the text
    6. {{man warn| title |text}}: template to add a warning to the text
    7. {{man index|prevpage|nextpage}}: template to add the bottom index bar. This will be stripped out on manual generation.
    8. {{languages}}: template to add language bar. This will be stripped out on manual generation.
  • The following markup code may be used:
    1. ''' bold ''': for bold or menuselections in GRAMPS, eg. Edit->Preferences
    2. '' italic '': for italic or filenames in GRAMPS, eg. filename
    3. <code> code sections</code>: for commands you type in the command line.
    4. <tt>''Replaceable text''</tt>: for GUI elements the user must type in replacing text, eg John Doe.
    5. <tt>Anything you type in</tt>: for GUI elements the user must type in, eg John Doe.

Tables, lists

Tables are special. Can we support them? Perhaps only tables via a template? As far as I can see present manual only has one table, we can easily change that in a list.

Lists. Can we support the list tokens: * and #, also nested?

Indent. Can we support the indent token: :

Cross referencing images/text

One may NOT link to pages, only to subsections in the Manual, so

  • [[manualpage#subsection]]: only this is allowed
  • [http://non_manual_subsection description]: all the other links must be cross site links.

One may also link to Manual images in the text. See discussion on Talk:Manual_Generation_3.0

Pdf output

JadeTeX (need TeX)

openjade -t tex -d DSSL DCL file_XML
  • DSSL is the stylesheet
  • DCL is the declaration, something like : /usr/share/sgml/openjade-1.3.2/pubtext/xml.dcl
pdfjadetex TEX_file

xmlto (need PassiveTeX and TeX)

xmlto pdf mydoc.xml

Is it Tim Waugh, a gramps contributors ?

FOP (need Java)

see Manual generation