README.md

Convert BaseX Wiki to DocBook and PDF

An install script puts the required dependencies in place. Execute basex install.xq to download and extract what is necessary. For customization consult lib/config.xqm if desired. E.g. the temporary directory or the table of contents shall be changed.

Conversion of BaseX documentation from the wiki on the web to a DocBook and PDF document is invoked by basex makedocu.bxs.

The conversion is done in 12 steps, as described in meta/wiki2doc.pdf. Only articles linked from Table of Contents named page appear in the output in the same order (see lib/config.xqm).

If the software was run once, another invocation will update all files. Images are kept and contents of pages update.

Step 5 and 11 make use of external programs. Those have 2 GB memory assigned.

Files in Project

basex-docu
├── basex.svg                           BaseX Logo
├── data                                database folder (ignored in git)
├── doc
│   ├── wiki2docbook.key                program workflow raw
│   └── wiki2docbook.pdf                program workflow
├── install.xq                          installs all dependencies
├── lib                                 library directory (ignored in git, see dependencies)
├── makedocu.bxs                        basex command script to generate the documentation
├── README.md                           this file
├── tmp                                 temp directory (ignored in git)
└── src
    ├── 00-get-pages-list.xq
    ├── 01-get-wiki-pages.xq
    ├── 02-modify-page-content.xq
    ├── 03-extract-images.xq
    ├── 04-toc-to-docbook-master.xq
    ├── 05-conv2docbooks.xq
    ├── 06-db-add-docbook.xq
    ├── 07-care-for-link-ids.xq
    ├── 08-care-for-linkends.xq
    ├── 09-modify-docbooks.xq
    ├── 10-generate-all-in-one-docbook.xq
    ├── 11-make-pdf.xq
    ├── 99-export.xq                    exports database to tmp
    ├── config.xqm                      project configuration
    ├── links-to-nowhere.xq             for analysis: check for deadlinks in docbook
    └── list-missing-articles.xq        for analysis: existing articles that won't appear in the docbook

Dependencies

All dependencies (except BaseX) can be installed using the XQuery install script install.xq.

• Step 5: herold is used for conversion of xhtml to XML DocBook, e.g. http://www.dbdoclet.org/archives/herold-src-6.1.0-188.zip ; tied to 5-conv2docbooks.xq
• Step 11: Apache FOP is used to generate pdf from XML DocBook, see http://archive.apache.org/dist/xmlgraphics/fop/binaries/ ; tied to 11-make-pdf.xq
• Docbook Stylesheets (v1.78) or latest version

References

• FOP parameters (like TOC generator) at http://www.sagehill.net/docbookxsl/TOCcontrol.html#BriefSetToc
• XSL Stylesheets for Conversion http://snapshots.docbook.org/ (referred from http://wiki.docbook.org/DocBookXslStylesheets )
• Apache FOP - Quick Start Guide

TODO

• syntax highlighting
• incremental updating using metadata (i.e. only load changed articles on second run)
• styling
  • add some colour
• break longlonglong lines
• break br-tags -- deleted at present
• special chars, i.e. ⌘ is replaced by #
• implement authentication to API (neccessary if more than 500 articles available)