Extension:DocBookExport

MediaWiki extensions manual

DocBookExport Release status: beta
Implementation	Parser function
Description	Lets you create DocBook from pages
Author(s)	Nischay Nahata (Nischayn22talk)
Latest version	0.0.0
MediaWiki	1.25
PHP	5.5+
Database changes	No
License	MIT License
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history code review README
Parameters $wgDocBookExportPandocPath
Hooks used ParserFirstCallInit
Translate the DocBookExport extension if it is available at translatewiki.net
Check usage and version matrix.

The DocBookExport extension lets you create a DocBook from selected wiki pages. You can download the DocBook as an XML file or in PDF format.

Installation

Make sure that you installed all required dependencies on your server.

• Download and place the file(s) in a directory called DocBookExport in your extensions/ folder.

• Add the following code at the bottom of your LocalSettings.php:

  wfLoadExtension( 'DocBookExport' );
  

• Configure as required
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

$wgDocbookExportPandocServerPath

Set the URL for the html to docbook script installed in your server. Eg. http://example.com/html_to_docbook/wikiHtmlToDocbookConvertor.php

Dependencies

• Install the following dependencies on the same or different server, that would be used to handle the html to docbook generation:
  • "pandoc": See https://github.com/jgm/pandoc/releases for the latest version

For Ubuntu use the following commands, replace the version number as per the latest releas

sudo wget https://github.com/jgm/pandoc/releases/download/2.2.1/pandoc-2.2.1-1-amd64.deb
sudo dpkg -i pandoc-2.2.1-1-amd64.deb

• To download DocBook files in Zip format install the following software:
  • ZipArchive php extension: See https://stackoverflow.com/q/3872555/1150075
• To download DocBook in PDF format install the following software:
  • "xsltproc": See https://www.howtoinstall.co/en/ubuntu/xenial/xsltproc
  • "fop": See https://www.howtoinstall.co/en/ubuntu/xenial/fop
• Install html_to_docbook as per directions in the README file

• On the wiki, install the "Figures" extension - that supports defining figures in MediaWiki

Usage

To create a book define the page structure using the docbook parser function or tag extension. See examples below.

Parser function example:

{{#docbook:
page structure=
? Bowling Introduction
* How I buy shoes
* Testing page
** Buying clothes intro,Buying shoes(title=Buying the right clothes,header=section header)
? Appendix
|title=My Guide to Bowling
|cover page=Cover Contents
|header=My Guide to Bowling
|footer=My Guide to Bowling
|index term categories=index terms
|index terms=shoe,clothes
}}

On saving the page two links will be made available to download the DocBook: one to download the DocBook as XML files in a zip file and another to download in PDF format.

The parameters shown can be customized as follows:

• page structure is used to defines the wiki pages that will be part of the docbook as cover, sections and chapters. The first line starts with a '?' and indicates the preface, * indicates a chapter and ** indicates a section of that chapter. Sub-sections can be defined using *** or **** and so on. The last line again starts with a '?' and indicates the wiki page to be used as the appendix. Sometimes you may want to merge contents of multiple wiki pages to one section/chapter. For that you can add a comma separated list of such pages as well. You can also customize the title of such a section by adding the following wikitext (title=) at the end of the line. Similarly you can customize the header for a specific section by using the (header=) syntax at the end of the line as shown in the example.

• title This parameter defines the name of the Docbook. This doesn't relate to any wiki page and is only used to name the files and the title of the docbook.
• cover page This parameter specifies the wiki page to be used as the cover page.
• headerThis parameter specifies the header to be used for every page of the docbook.
• footerThis parameter specifies the footer to be used for every page of the docbook.
• index terms This parameter is a comma separated list of terms that should be indexed.
• index term categories If you have wiki pages for all your index terms you can add them to a category and mention it here.

DocBook supports figures which are images or other media that can be referenced elsewhere in the document. A separate list of figures is also prepared. To define a figure you need to use the Figures extension.

Credits

This extension has been written by WikiWorks for NATO.

Development and Help

You are welcome to submit bug fixes and further contributions on Github.

Please also feel free to contact the author or WikiWorks for consulting on further developments, feature requests or bug fixes on this extension.

See also

• PDF export - summary of all PDF export extensions