Skip to content

Latest commit

 

History

History
201 lines (159 loc) · 7.67 KB

sample_conversions.asciidoc

File metadata and controls

201 lines (159 loc) · 7.67 KB

Sample commands for AsciiDoc and DocBook

AsciiDoc files in these examples use the file extension .asciidoc to enable preview in github but you can use any extension that you prefer. The components for this file structure must be downloaded separately if they are not installed in your operating system.

Tools

Free tools, required

The following free tools can create HTML and PDF output:

  • AsciiDoc

  • DocBook XSL stylesheets

  • Apache FOP

  • Python 2.5 or later (for AsciiDoc)

  • Java (for Apache FOP)

  • Text editor like nano, TextWrangler or VIM

  • The xsltproc tool

Free tools, optional

AsciiDoc supports some free tools for additional content creation:

  • Graphviz

  • QR code plugin

  • pychart

Commercial tools, optional

The following are some optional commercial tools:

  • XEP instead of Apache FOP - for more PDF options and advanced DocBook editing

  • XMLMind XML editor instead of FOP - for output options like web help, Word, OpenOffice

  • Sublime Text 2 instead of a free text editor - for advanced text editing

Sample AsciiDoc commands

Convert AsciiDoc to Slidy presentation

python asciidoc-8.6.8\asciidoc.py --backend slidy book1/content/book_simple.asciidoc

Convert AsciiDoc to HTML5

python asciidoc-8.6.8\asciidoc.py --backend html5 book1/content/book_simple.asciidoc

Install qrcode plugin

python asciidoc-8.6.8\asciidoc.py --backend install qrcode-filter.zip

Convert AsciiDoc to DocBook file

python asciidoc-8.6.8\asciidoc.py -b docbook -o ./book1/output/book_simple.xml book1/content/book_simple.asciidoc

Convert AsciiDoc to DocBook file and include docinfo.xml file

python asciidoc-8.6.8\asciidoc.py -a docinfo1 -b docbook -o ./book1/output/book_simple.xml book1/content/book_simple.asciidoc

Running AsciiDoc on Microsoft Windows

python c:\mydocs\asciidoc-8.6.8\asciidoc.py -a docinfo1 -b docbook -o ./book1/output/book_simple.xml book1\content\book_simple.asciidoc

Convert AsciiDoc to slidy HTML presentation

python c:\mydocs\asciidoc-8.6.8\asciidoc.py -a iconsdir="../../common/images/" -b slidy -o ./book1/output/slidy.html book1/content/book_advanced.asciidoc

Convert AsciiDoc to HTML5 page

python c:\mydocs\asciidoc-8.6.8\asciidoc.py -a iconsdir="../../common/images/" -b html5 -o ./book1/output/myHTML5.html book1/content/book_advanced.asciidoc

Sample XSL conversions

Uses xsltproc and current XSL stylesheets to convert Docbook to FO. You must have already converted your document to a DocBook file with AsciiDoc.

Convert DocBook file to FO file

xsltproc.exe docbook-xsl-1.77.1/fo/docbook.xsl .\book1\output\book_simple.xml > \book1\output\book.fo

Rebuild custom title page layout from titlepage spec file

xsltproc.exe -o myCustomPDF\myTitlePage.xsl docbook-xsl-1.77.1\template\titlepage.xsl myCustomPDF\myTitlepageSpecFile.xml

Convert DocBook file to FO file using a custom stylesheet

xsltproc.exe .\myCustomPDF\myPDFstyles.xsl .\book1\output\book_simple.xml > \book1\output\book.fo

Convert DocBook file to FO file using a custom stylesheet an use xincludes (such as including legal text or code samples from a text file into the final output)

xsltproc.exe --xinclude .\myCustomPDF\myPDFstyles.xsl .\book1\output\book_simple.xml > \book1\output\book.fo
Additional information

The titlepage spec file should compile with any current XSL stylesheets for DocBook, however, I did not succeed with the 1.77.1 version and had to download the latest files from from http://50.56.245.89/xsl/template/ to correctly compile my custom titlepage.

Use of the titlepage spec file is discussed here https://lists.oasis-open.org/archives/docbook-apps/201207/msg00001.html

Sample FOP commands

Uses Apache FOP to create PDF from FO file.

Convert FO file to PDF file

fop1.1\fop.bat .\book1\output\book.fo .\book1\output\book.pdf

Using FOP 1.1, convert FO file to PDF file and disable complex scripts

fop1.1\fop.bat -nocs .\book1\output\book.fo .\book1\output\book.pdf

Convert FO file to PDF file and use custom FOP configuration file

fop1.1\fop.bat -c .\myCustomPDF\myFOPconf.xconf .\book1\output\book.fo .\book1\output\book.pdf

Using a configuration file for FOP enables things such as font substitutions and font embedding

Apache FOP can generate a lot of event log messages. One easy way to control that is to go into the script that runs FOP, fop or fop.bat, enable the following two lines:

set LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
set LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=INFO

The last line defines what level of event log messages to display. Change "INFO" to "WARN" or "ERROR" to display fewer messages.

Originally I was embedding fonts in Windows to oversome some FOP warnings. However doing the same in MacOSX was a bit more difficult and I found that I could simply apply font substitutions in the FOP configuration. This might also work in Windows but I have not tested it yet, so I have left two FOP configuration files, one for Windows and one for MacOSX. Again, this was just to avoid some pesky log messages (in my case) so if those messages do not bother you, you can skip using the special FOP configuration.

Sample batch files for Windows

Although these examples are for Windows, similar scripts can be written for different operating systems. Batch files (or scripts) can be useful to integrate into your text editor to build previews of your documentation or to use with a continuous integration server to automate your workflow.

For example, you can add custom build commands in the Sublime Text editor

Sample windows batch file
REM Batch file to create PDF from XML DocBook files
REM
REM build docbook XML file from AsciiDoc book
python asciidoc-8.6.8\asciidoc.py -a docinfo1 -b docbook -o .\book1\output\book_simple.xml .\book1\content\book_simple.asciidoc

REM create a FO file
xsltproc.exe --xinclude docbook-xsl-1.77.1/fo/docbook.xsl .\book1\content\book_simple.xml > .\book1\output\book.fo

REM create a PDF file
fop-1.1\fop.bat .\book1\output\book.fo .\book1\output\book.pdf
Sample windows batch file with XSL customizations
REM Batch file to create PDF from XML DocBook files
REM
REM build docbook XML file from AsciiDoc book
python asciidoc-8.6.8\asciidoc.py -a docinfo1 -b docbook .\book1\output\book_simple.xml .\book1\content\book_simple.asciidoc

REM create a FO file using a custom stylesheet
xsltproc.exe --xinclude .\myCustomPDF\myPDFstyles.xsl .\book1\content\book_simple.xml > .\book1\output\book.fo

REM create a PDF file with some custom parameters to minimize errors
fop-1.1\fop.bat -c .\myCustomPDF\myFOPconf_win.xconf .\book1\output\book.fo .\book1\output\book.pdf

Document file structure

Here is a sample document file structure for use with Windows. Tools such as asciidoc or xsltproc install to different folders in MacOSX or Linux.

/mydocs
	xsltproc.exe
	/asciidoc-8.6.8
	/book1
		/content
			bookname.asciidoc
			docinfo.xml
			chap1.asciidoc
			chap2.asciidoc
			chap3.asciidoc
			glossary.asciidoc
		/images
		/output
	/book2
	/book3
	/common
		/legal
			legal.txt
		/images
		/appendix
			MigrationNotes.asciidoc
	/docbook-xsl-1.77.1
	/fop-1.1
	/myCustomHTML
	/myCustomPDF
		myFOPconf_macosx.xconf
		myFOPconf_win.xconf
		myPDFstyles.xsl
		myTitlePage.xsl
		myTitlepageSpecFile.xml

This is just one example. You can also store chapters or sections into subject or product folders and then keep the book files separate.