Manual Generation

From Gramps
Revision as of 07:55, 11 October 2023 by Patsyblefebre (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Gnome-important.png
Manual Generation for Gramps 2.x and older

From Gramps Version 3.0:, we moved towards a community driven manual, the Gramps 3.0 Wiki Manual. To generate a html/pdf/docbook manual from this, a new strategy must be followed

Tango-Dialog-information.png
The process for creating version 5.1 of the manual is described at Manual Generation 5.1.


Manual creation and generation

Every now and then, the manual on the gramps-project website should be updated. This page explains how to create this manual. Information on how to do the translation is in Translating the Gramps User manual. Part of this text is already automized via Makefiles by typing in the help directory make html. The reason of this page is so people would understand why Makefiles do what they do, or to generate the manuals outside of the build system.

From Gramps Version 3.0:, we moved towards a community driven manual, the Gramps 3.0 Wiki Manual. To generate a html/pdf/docbook manual from this, a new strategy must be followed

Get latest version

See Translating the Gramps User manual. You should have the Git version locally. Obtain latest version of the translations with git pull. Now do make to generate the manual in all supported languages.

The directory help should now contain all manuals, the standard english one in help/C/gramps.xml. At the time of writing, manuals are available for locales:

  • C (English) -- basis of other translations
  • fr (French) -- complete
  • nl (Dutch) -- almost complete
  • nb (Bokmaal, Norwegian) -- barely started
  • sk (Slovak) -- complete

Install necessary software

You will need the following:

  • docbook-xml -- to enable to convert gramps.xml in a Docbook manual
  • docbook-xsl -- to allow export of manual to other formats.
  • xsltproc -- tool that facilitates XSLT transformations.
  • fop -- file object processor, to generate pdf documents.
  • fop-hyph.jar -- hyphenation patterns needed to correctly split words with fop.

For extended-latin alphabets or non-latin alphabet you need also:

  • java -- JRE is needed, perhaps JDK too...
  • The free unicode fonts -- FreeSerif.ttf and FreeMono.ttf should be installed on all modern linux distributions
  • Adobe Reader -- free pdf readers cannot read (at the time of writing) the pdf files we will make for these alphabets, due to a bug in core pdf libraries. A bug has been submitted upstream. You should use Adobe Reader for the time being.

FOP (Formatting Objects Processor)

For fop, download latest version, fop-0.93-bin-jdk1.4.tar.gz , and read the install and usage instructions: in the fop-0.93 dir, you can do ./fop and see the usage options. For futher reference, we assume fop is installed in ~/Downloads/fop-0.93.

For fop-hyph, download the version corresponding to your fop install from offo, and make it available to fop as indicated on that website. The easiest way with an install of fop in ~/Downloads/fop-0.93 is to copy fop-hyph.jar into ~/Downloads/fop-0.93/lib

Fonts

Fop uses the standard pdf fonts: times new roman, helvitca, monospace, however these fonts do NOT cover all unicode symbols. So eg Slovak or Russian cannot be created with this. For these languages, FOP must be instructed to use other fonts than the standard fonts. A new font can be installed and included in the pdf, see the dedicated section below.

Resources

Read up on how to export in DocBook XSL: The Complete Guide, specifically the chapters on html export and pdf export.

Automatisation

A python script htmlpdfmanual.py is given which can perform html and pdf creation automtically based on some constants on my systhem. This intention is to convert all functionality to the GRAMPS make files in the future.

All needed data (css, png, conf) is present in Git in the help/output dir. To run the script, save it in help/output directory of your Git version of Gramps (on linux only). Edit constants in this script as necessary (recreate for non-standard latin alphabets the fonts if those of Git give errors).

All constants should be self-explanatory, except two:

  • admonimagepdf should direct to the absolute path with quality png's (15mm wide) of the admon icons (note, tip and warning.png). You can direct it to the standard admonimage directory, but if you do that, the icons will look bad in the created pdfs.
  • fop_conf_fs should direct to the custom made FOP configuration file (available in Git). This is only needed if languages_fs constant is not empty. See below on what the configuration file must consist of.

Run the script, it will create a directory 2.2, with all manuals as pdf and html, ready to upload to the site, or to test it yourself.

HTML manual creation

This works for all alphabets if your linux distribution makes use of the standard free fonts. In the directory with gramps.xml do: 

xsltproc -o html/index.html \
 --stringparam  chunker.output.encoding UTF-8 \
 --stringparam html.stylesheet  ../gramps-help-screen.css \
 --stringparam admon.graphics 1 \
 --stringparam admon.graphics.path ../images/ \
 --stringparam navig.graphics 1 \
 --stringparam navig.graphics.extension .png \
 --stringparam navig.graphics.path ../images/ \
 /usr/share/xml/docbook/stylesheet/nwalsh/html/chunk.xsl \
 gramps.xml

Note that in above all the paths are the relative paths as they should appear in the html. You still have to copy the correct directories in the correct place to view the html in a correct way. Next, upload all html files, as well as the figures directory to the gramps-project website, and an image directory containing the admon graphics (Gramps xml only uses 'note.png', 'tip.png' and 'warning.png' at this moment), navigation graphics and splash picture, and upload the css as well.

Another option is to use a Python test program to generate html-files from the Gramps Manual 3.0 wiki pages.

PDF manual creation for West-European languages

The alphabets of these languages are supported by the default pdf fonts. Pdf creation consists of two steps. First create the .fo files in the directory where gramps.xml lives. This is important as the xml contains references to figures, and FOP must be able to follow these relative links. 

xsltproc  --output myfile.fo    \
 --stringparam  paper.type A4  \
 --stringparam  double.sided 1 \
 --stringparam  admon.graphics 1 \
 --stringparam  admon.graphics.path abs_path_to_admonpdf \
 --stringparam  section.autolabel 1 \
 --stringparam  section.autolabel.max.depth 3 \
 --stringparam  section.label.includes.component.label 1 \
 --stringparam  body.start.indent 0pt  \
 --stringparam  fop.extensions  1 \
 /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl \
 gramps.xml

Note that here absolute path to admon images must be given, as next we will include it in the pdf, so the post-processor must find these images. For USletter, set paper.type to USletter. Next create the pdf in the same directory: 

~/Downloads/fop-0.93/fop -fo myfile.fo -pdf myfile.pdf

Now upload the pdf to gramps-project website.

Note: As said above, this standard method of creating a pdf does not support all Unicode characters. The not supported characters will appear as the symbol #. For this, there is a general method to font creation, as described below, however, at the moment a bug prevents OSS linux pdf viewers to handle the resulting pdf file.

General PDF manual creation

The following is for manual creation in eg Slovak, or for non-latin alphabets. At the moment, I am only aware of Adobe Reader on linux to read these pdf files. This is due to a bug in library handling ttf (the bug is filed upstream).

For extra information see Fop website (be carefull, instructions are in general for the Microsoft platforms).

Preperation: Creation of the fonts

All linux distributions should have in /usr/share/fonts/truetype/freefont/ the free Unicode fonts: FreeSerif, FreeMono and FreeSans, in truetype (ttf) format. These need to be compiled so that fop can use them. In the ~/Downloads/fop-0.93/ directory do (adapt the code to reflect the correct version numbering you downloaded!) 

java -cp build/fop.jar:lib/avalon-framework-4.2.0.jar:\
 lib/commons-logging-1.0.4.jar:lib/commons-io-1.1.jar \
 org.apache.fop.fonts.apps.TTFReader \
 /usr/share/fonts/truetype/freefont/FreeSerif.ttf \
 FreeSerif.xml

Repeat the above for the fonts FreeSerifBold, FreeSerifItalic, FreeSerifBoldItalic, FreeMono, FreeMonoBold, FreeMonoOblique, FreeMonoBoldOblique. The resulting xml files are in Git, but should you have problems, regenerate them.

Preperation: A custom FOP config file

You find this file in Gramps Git in dir help/output. We made a config file with the name grampsfop.xconf, and content (change in following file /path_to_gramps into the absolute path where Gramps Git is downloaded.): 

 <?xml version="1.0"?> 
 <fop version="1.0">
  <!-- Source resolution in dpi (dots/pixels per inch) for 
     determining the size of pixels in SVG and bitmap images, 
     default: 72dpi -->
  <source-resolution>72</source-resolution>
  <!-- Target resolution in dpi (dots/pixels per inch) for 
     specifying the target resolution for generated bitmaps, 
     default: 72dpi -->
  <target-resolution>72</target-resolution>
 
  <renderers>
    <renderer mime="application/pdf">
       <fonts>
        <!-- embedded fonts -->
        <!--
        This information must exactly match the font specified
        in the fo file. Otherwise it will use a default font.
        -->
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeSerif.xml"
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeSerif.ttf">
          <font-triplet name="FreeSerif" style="normal" weight="normal"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeSerifBold.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeSerifBold.ttf">
          <font-triplet name="FreeSerif" style="normal" weight="bold"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeSerifItalic.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeSerifItalic.ttf">
          <font-triplet name="FreeSerif" style="italic" weight="normal"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeSerifBoldItalic.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeSerifBoldItalic.ttf">
          <font-triplet name="FreeSerif" style="italic" weight="bold"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeMono.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeMono.ttf">
          <font-triplet name="FreeMono" style="normal" weight="normal"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeMonoBold.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeMonoBold.ttf">
          <font-triplet name="FreeMono" style="normal" weight="bold"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeMonoOblique.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeMonoOblique.ttf">
          <font-triplet name="FreeMono" style="oblique" weight="normal"/>
        </font>
        <font metrics-url="file:///path_to_gramps/gramps2/help/FreeMonoBoldOblique.xml" 
          kerning="yes" embed-url="file:///usr/share/fonts/truetype/freefont/FreeMonoBoldOblique.ttf">
          <font-triplet name="FreeMono" style="oblique" weight="bold"/>
        </font>
      </fonts>
    </renderer>
  </renderers>
 </fop>

PDF creation: step 1

First we create the .fo files, indicating the font. This must be done in directory where gramps.xml resides. 

xsltproc  --output myfile.fo    \
 --stringparam  paper.type A4  \
 --stringparam  double.sided 1 \
 --stringparam  section.autolabel 1 \
 --stringparam  section.autolabel.max.depth 3 \
 --stringparam  section.label.includes.component.label 1 \
 --stringparam  admon.graphics 1 \
 --stringparam  admon.graphics.path abs_path_to_admonpdf \
 --stringparam  body.start.indent 0pt  \
 --stringparam  body.font.family FreeSerif \
 --stringparam  title.font.family FreeSerif \
 --stringparam  monospace.font.family FreeMono \
 --stringparam  symbol.font.family FreeSerif \
 --stringparam  fop.extensions  1 \
 /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl \
 gramps.xml

For USletter, set paper.type to USletter.

PDF creation: step 2

Now we create the pdf, indicating where to find the fonts. This is also done in the gramps.xml directory (eg help/sk), as otherwise the figures will not be found. Remember the fop configuration file grampsfop.xconf contains absolute font paths, pointing FOP to the file will make sure all needed fonts are found. 

~/Downloads/fop-0.93/fop \
 -c /path_to_grampsfop_xconf/grampsfop.xconf \
 -fo myfile.fo -pdf myfile.pdf

The file myfile.fo can be deleted, and myfile.pdf uploaded to gramps-project website with a better name.

See also

Retrieved from "https://gramps-project.org/wiki/index.php?title=Manual_Generation&oldid=99870"