Difference between revisions of "Manual Generation 3.0"

From Gramps
Jump to: navigation, search
(html to docbook)
(xmlto (need PassiveTeX and TeX))
Line 90: Line 90:
===xmlto (need PassiveTeX and TeX)===
===xmlto (need PassiveTeX and TeX)===
  [http://cyberelk.net/tim/software/xmlto/ xmlto] pdf mydoc.xml
  [http://cyberelk.net/tim/software/xmlto/ xmlto] pdf mydoc.xml
Is it [http://www.gramps-project.org/wiki/index.php?title=Gramps-about Tim Waugh], a gramps contributors ?
Is it [http://www.gramps-project.org/wiki/index.php?title=Gramps-about Tim Waugh] ?
[[media:Ancestors.xsl.gz|Ancestors.xsl]] [[media:Birthday.xsl.gz|Birthday.xsl]]
===FOP (need Java)===
===FOP (need Java)===
see [http://www.gramps-project.org/wiki/index.php?title=Manual_Generation Manual generation]
see [http://www.gramps-project.org/wiki/index.php?title=Manual_Generation Manual generation]

Revision as of 09:42, 31 July 2008

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.

html to html translation

We can try to translate generated html by using translate toolkit

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

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

html to docbook

Html2Docbook converts project documentation from HTML to DocBook.

  1. Convert all of your HTML to XHTML using Tidy. Enable 'enclose-block-text' in the configfile, else any unenclosed text (where this is allowed under XHTML Transitional but not under XHTML Strict) will vanish.
  2. Use the XSL stylesheet (below) to convert the XHTML into DocBook (There's no way to merge the multiple XHTML files into a single document, so the stylesheet converts each HTML page into a section). Be sure to pass in the filename (minus the extension) as a parameter. This will become the section id.
  3. Combine the multiple DocBook section files into a single file, and re-arrange the sections into the proper order
  4. Correct any validity errors. (At this point, there are likely to be a few, depending on how good the original HTML was.)
  5. Peruse the now valid DocBook document, and look for the following:
  • Broken links xref elements that should be links
  • Missing headers (the heading logic isn't perfect. You'll lose at most 1 header per page, though, and most pages come through with all headers intact.)
  • Overuse of emphasis and emphasis role="bold"

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 ? Ancestors.xsl Birthday.xsl

FOP (need Java)

see Manual generation