Manual Generation 5.1
|
Manual Generation for Gramps 5.1.x and newer |
The Gramps 5.1 offline PDF manual was created for various Language using unix commands and process described here.
It has these main stages:
- collating the chapters of the User Manual to local files
- cleaning the MediaWiki markdown and linking to a format appropriate to a single file
- converting the MediaWiki markdown HTML file to a PDF with internal links
Contents
Preparing for consolidated manual creation
All of the pages must be compliant with the following restrictions
- All pages should have a Navigation then Language in header area
- All pages should have a Navigation then Language in footer area
- No pages should use Heading 1. If they do, increase level of headings for whole page. All H2 become H3, for instance. This only impacts the auto-generated Table of Contents.
Tools needed
To use the templates provided, your system must have the following Unix programs:
The BSD version was used in the templates.
The command curl(1) is used to download the existing wiki page in HTML format. Then the scripts (sed commands) modify and assemble into a consolidated HTML file. The program wkhtmltopdf (available on github) is used to convert the HTML to PDF.
Download language-specific wiki pages
Some translated pages have the english name with a suffix of the two letter language code. Other translated pages have the wiki name translated. This process needs to work with either or a mixture of these.
- Go to main wiki page. Then select language. This is the translated main wiki page
- save page name, then hover over the Next link and save page name. click on Next link and save page name if different. Repeat until complete
- This saves page name of both the redirect and the link linked page for all pages that will be consolidated.
Templates
A template for creating en, he, nl, and ru PDF manuals is provided File:UserManual51.zip . A template for version 5.2 is available for testing File:UserManual52.zip . The 5.2 version creates 6 manuals (en, he, nl, ru, fr, de). This version is backward compatible to 5.1 (See README for how to run the 5.2 scripts to generate the 5.1 PDF files).
Copy a language template that is similar as a starting point. The template contains many files that will need customized. The he version uses wiki names that have a suffix of the language. The nl version translates each page name and is redirected from the wiki name that has a suffix.
- Makefile - rules for generating the PDF
- main.script - sed script file for generating the main page
- L.script - sed script file for chapter pages
- Lenglish.script - Optional sed script file for processing untranslated pages
- glossary.script - sed script file for glossary
- toc.xsl - XSLT for generating the Table of Contents (no edits needed). The customization is to only include 2 levels.
- remove_page_toc.css - Style sheet to remove the ToC section of the chapter pages. (no edits needed)
Update Makefile
- Update TODAY to use appropriate language
- Update TOCFOOTOPT to translate Published
- Update SRCS to be the list of page names (not redirects). These should NOT have the language suffix on them.
- Update FILEPRE with the prefix name for all of the wiki pages. Needed if page names have been translated
- Update TARGETS to use the language suffix.
- Update target rules for language suffix.
Update scripts
The scripts are the commands to the unix command sed. The templates all use the BSD version of sed, which is the most restrictive. gnu sed may require a slightly different syntax. The sed commands are processed in order.
- L.script - this file edits all chapter pages
- Put a page break at the top of each chapter
- Change the internal and external links to have a consistent name for the consolidated file
- Change the anchors to have a consistent name for the consolidated file
- Remove the header section
- Remove the top Language table
- Remove the top navigation and search links
- Remove the bottom navigation table. This is optional
- Remove the bottom Language table
- Truncate the h1 heading to make the PDF footer and ToC (Table of Contents) easier to read
- main.script - this file edits the main wiki page
- Change the internal and external links to have a consistent name for the consolidated file
- Change the anchors to have a consistent name for the consolidated file
- Remove the top Language table
- Remove the top navigation and search links
- Remove the bottom navigation table. This is optional
- Remove the bottom Language table
- glossary.script - this file edits the glossary page. Similar to chapter pages
- Lenglish.script - this file edits any english pages that have no equivalent translated version. No edits should be needed.
Config files
There are a few configuration files that should not need changed
- toc.xsl - XSLT for the Table of Contents that is auto-generated
- remove-page-toc.css - Style sheet to remove the chapter page Table of Contents
Test
Run 'make' to create the chapter HTML files, consolidate and convert to PDF. This is an iterative process to find errors and fix. 'make clobber' will remove all created files for retrying.
