PDF Docs Project

From DDCIDeos
Jump to navigationJump to search

Project to publish DeosBook documents in PDF.

Rationale

  • Marketing wants to be able to provide customers with documentation in single files that they can review, without installing a DDS. The suggested format was PDF.
  • Engineering would like to generate "backend" documents as a single file. Single file is both for ease of customer consumption, and also so they can be easily digitally signed.

Other options:

  1. Josh suggested that embedding images as Data URLs, supported by all major modern browsers, as of 2008. However, Aaron notes that until 2011 IE only supported 32KB images and quite a few of our documents have images larger than 32KB, not to mention the inclusion of .css and .javascript

News

As of Deosbook 1.0.11, it is possible to generate PDF documents using either FOP or dblatex. Note that both can be installed at the same time.

Surprisingly generating PDF is reasonably fast.

Aaron is monitoring the DocBook mailing list and dblatex is reported as the better alternative to FOP, as are commercial tools such as sagehill. Aaron's experience is that dblatex is fragile, often failing to generate documents at all.

FOP seems to do a better job with most things, but hyperlinks are not well styled.

DBLatex

To use:

  1. Using Cygwin setup, install packages: deos-maintainer-tools dblatex
  2. Execute the following command from the directory where the document is generated: 
    make DBLATEX=dblatex foo.pdf

Breakage

With Cygwin 2018 generation of the kernel UG dies with the following error. 

 pdflatex failed
 ug.docbook.tex:22318: pdfTeX error (ext4): \pdfendlink ended up in different nesting level than \pdfstartlink.
 Unexpected error occured

Google provides several suggestions, but they are all terrible. The following brutal hack gets past the error, but leaves all hyperlinks non-hyperlinked.

In /usr/share/dblatex/latex/style/dbk_hyper.sty, change: 

 \ifpdf
   \usepackage[pdftex,plainpages=false,\hyperparam,\hyperparamadd]{hyperref}

to: 

 \ifpdf
   \usepackage[draft,pdftex,plainpages=false,\hyperparam,\hyperparamadd]{hyperref}

Formatting Issues

The resulting docs have several issues.

  1. Must Fix. Links (link and xref) to elements within tables default to page 1 (appear undefined).
  2. UG is missing list of functions
    • Most likely deosbook.xsl is generating incorrect docbook.
    • It would probably be acceptable to remove the "list-of-functions" tag.
  3. Must Fix. UGs and Reqs Docs missing the Document Number and Version.
    • KL: Why aren't corpauthor fields supported?
    • corpauthor is ignored in PDF output, various other articleinfo/bookinfo fields are ignored in HTML output.
  4. Problems with release notes:
    • They have a table of contents
    • All sections start with zero (e.g., 0.1, 0.2, etc.).
    • KL: I vote for not fixing this. It's arguable if this is a necessary fix or not, since release notes pertain to installed components. Users will refer to installed documentation, not PDFs.
    • The list of integrity keys in the release notes is very badly formatted.Fixed in SVNRevision:57252
  5. UG function signatures are formatted without indentation (all parameters on one line). Not as nice to look at, but probably acceptable.
  6. Must Fix. Inter document links refer to HTM docs, not PDF.
  7. Clicking links to section (other than in toc or bookmarks) leaves the section title slightly "off the top of the page" in Adobe.
  8. Problems with tables:
    • "Table 8.1. Deos™ Exception IDs" <apifun-xref> "suspendProcessWaitForDebugger()" exceeds cell width (does not wrap).
    • Table for "installThreadExceptionHandlerEx()" on page 105/199 in the kernel UG, cell content <programlisting> scrolls beyond cell border
    • See http://dblatex.sourceforge.net/example/manual.pdf table.default.position
  9. Other issues:
    • PDF version has additional subsections; e.g. References is section 1.3 in html, but generated as 1.3.1 in PDF
      • This is a difference in the stylesheets for PDF and HTM output. Not sure how difficult to fix.
    • PDF version includes a List of Tables and a List of Figures. Turn these lists off with "doc.lot.show".
    • PDF version generates table and figure titles below tables/figures. Configure above table/figure with table.title.top and figure.title.top.
    • Table header row in PDF version missing background (fill) color; e.g. see Table in Chap 5 of Kernel UG.
    • xref linkends are missing from <programlisting> blocks; e.g., see Figure 6.1. Kernel Startup Sequence in PDF Kernel UG, which is missing <xref linkend="DEBOOT"/> throughout the block. And links like <link linkend="platform-resource-library">Platform Resource Libraries.</link> are not hyperlinks within the <programlisting> block.
      • this requires customization to fix. The verbatim display representations don't grok various things, and the xsltproc output provides a warning on each occurrence: 
        • footnoteref: default template used in programlisting or screen
        • xref: default template used in programlisting or screen

Sample PDF output

Notes

You typically need to generate the UGs from one of the architecture release directories (the docs makefile usually has something like this at the top): 

 ifeq ($(HOST_ARCHITECTURE)-$(BUILD_VARIATION),x86-release)

So, to generate the ug, cd to x86-deos/release.

The xsltproc command that generates a .htm file has a bunch of "--stringparam foo val" options. dblatex expects "--param foo=val" and many, but not all, of the options are identical or very similar. Presumably we'd add rules to the deosbook makefile once we get the right set of options.

hyperlinks not working is a dblatex defect. Can work around it by ensuring that all xrefs and links are to IDs contained in one of the following tags:

  • chapter
  • section
  • para
  • entry
  • listitem
  • apifunction (is implemented as a section)
  • footnote (probably)
  • table (probably)
  • figure (probably)
  • firstterm (requires dblatex patch)
  • phrase (requires dblatex patch)

The patches required are:

  1. In /usr/share/dblatex/xsl/para.xsl add the following template (just before: <xsl:template match="para|simpara">
 <xsl:template match="phrase">
   <xsl:call-template name="label.id"/>
   <xsl:apply-templates/>
 </xsl:template>
  1. In /usr/share/dblatex/xsl/inlined.xsl, add:
 <xsl:call-template name="label.id"/>

immediately after: 

<xsl:template match="firstterm|glossterm">

FOP

  1. Using Cygwin setup, install packages: deos-maintainer-tools fop
  2. Execute the following command from the directory where the document is generated: 
    make FOP=fop foo.pdf

Issues

PDF generation seems reliable, including embedded figures, however, because the FOP processor doesn't do automatic table layout, the API signatures look terrible. A detailed evaluation of the output hasn't been performed.

A *very* quick scan through the UG shows:

  1. Links to elements in tables work.
  2. list of functions is present.
  3. document number and version is present.
  4. Didn't look at release notes.
  5. UG function signatures are formatted without indentation (all parameters on one line). Not as nice to look at, but probably acceptable.
  6. Must Fix. Inter document links refer to HTM docs, not PDF.
  7. Didn't investigate tables.

Approximately 50 margin violations are present in the kernel UG, although most look easily fixable.

Retrieved from "https://ddci.zapto.org/ddciWiki/index.php?title=PDF_Docs_Project&oldid=29420"