Bora Document Processor - a command line translator for BDML documents
Synopsis
boradoc [OPTION...] [INPUT...]
Example commands can be found towards the end of this manual page.
Overview
The most simple command is to specify the input file to translate. This will default to the PDF target.
boradoc book.bdml
If no output file is specified, the output file name defaults to the same as the input file name with the .bdml extension replaced with the target extension (book.pdf in the above example).
When an output file is specified, the extension of the output file name determines the translation target. Thus, the following command translates to HTML.
boradoc output=book.html book.bdml
If the specified output file has a non-standard file extension, or no output file is specified and a target other than PDF is required, the target can be specified via the target option. In order to translate book.bdml into the HTML target, the command is:
boradoc target=html book.bdml
In order to translate book.bdml into the HTML target with the non-standard output file name book.html.backup, the command is:
boradoc target=html output=book.html.backup book.bdml
Multiple targets may also be specified via the target option, allowing multiple targets to be translated in a single command line. In order to translate book.bdml into the HTML, PDF, and ePUB targets, the command is:
boradoc target=html,pdf,epub book.bdml
If multiple targets are specified, no output file may be specified, and the output file names default to the same as the input file name with the .bdml extension replaced with the target extensions. If different output file names are required in multiple target mode, the prefix and/or suffix options may be used to embellish the input file name.
Multiple input files can be specified in the command line. In this case, the processor runs in batch mode. No output file may be specified, and the output file names default to the same as the input file names with the .bdml extension replaced with the target extension.
boradoc target=html book1.bdml book2.bdml book3.bdml
If different output file names are required in batch mode, the prefix and/or suffix options may be used to embellish the input file names.
boradoc target=html suffix=R1 book1.bdml book2.bdml book3.bdml
For the HTML target, the output CSS is placed inside the resulting HTML file by default. If an external CSS file should be used, this can be specified via the css-output-file option. This option is most useful when multiple BDML documents are being translated into HTML files and they share the same CSS.
boradoc target=html css-output-file=resources/site.css \ index.bdml products.bdml services.bdml
Common options
target=TARGET[,...]
Explicitly specify for which targets the output should be generated. The target specification is in the form of a comma delimited list. No whitespace is allowed in the list. Possible targets are pdf, html, epub, and mobi (Kindle). If this option is not specified, the default target is pdf.
variant=VARIANT[,...]
Specify which metadata and include elements should be applicable. The variant option is used to provide one or more arbitrary strings (separated by commas), which will be used to match on variant attributes in the source document. By default, there is no variant.
output=FILE
Specify output file where result of processing will be saved.
input-file-list=FILE
Specify a text file containing a list of input files to translate. The text file must have a single input file path per line. When relative paths are used in the file list, the path is relative to the location of the text file. When input-file-list is specified, no single input file and no output file option may be specified.
help
Displays this usage page.
prefix=PREFIX
Prefix the output file names with the specified prefix. This is most useful for output file name modifications when translating in batch mode.
suffix=SUFFIX
Insert the specified suffix into the output file names, after the input file name roots and before the automatic file extension. This is most useful for output file name modifications when translating in batch mode.
disable-default-css
Disable default bdml css from being applied to the document.
input-folder=FOLDER
Specify the input folder for an out of source build. The input folder will be used as the root of a folder hierarchy. Output paths will be constructed from the path of each input file, relative to the input folder.
output-folder=FOLDER
Specify the out of source output folder into which all files will be placed.
scan
When specified in conjunction with the input-folder and output-folder options, the processor will recursively scan the input folder for BDML files and will translate all qualifying BDML files that were found.
BDML files located in the input folder or sub-folders will qualify for translation if they are not directly or indirectly included (via an <include> element or via metadata elements) in another BDML file located in the input folder or sub-folders.
HTML specific options
css-output-file=FILE
Specify the CSS output file which will contain the translated and consolidated CSS. By default, the CSS of the HTML target translation is placed inside the resulting HTML file. Use of this option allows an external CSS file to be used. This is most useful when multiple BDML documents are being translated and they use the same CSS.
no-link-conversion
Disable automatic conversion of BDML links from .bdml to .html. By default, the processor will append the .html file extension to all BDML links. This configures the links to point to other html target pages. If this is not required (i.e. all BDML links in the document should continue to point to .bdml files), then this options disables the conversion.
Examples
Translate a single BDML input file to a PDF with name book.pdf:
boradoc book.bdml
Translate a single BDML input file to an HTML page with name book.html:
boradoc output=book.html book.bdml # Alternative form: boradoc target=html book.bdml
Translate a single BDML input file to a PDF with a different name:
boradoc output=version42.pdf book.bdml
Translate a single BDML input file to an HTML page with a different name:
boradoc output=version42.html book.bdml
Convert a single BDML input file to specified targets (HTML, ePUB, Mobi):
boradoc target=html book.bdml boradoc target=epub book.bdml boradoc target=mobi book.bdml
Convert a single BDML input file to PDF, HTML, ePUB, and MOBI targets in one command:
boradoc target=pdf,html,epub,mobi book.bdml
Translate multiple BDML input files in batch mode to PDF:
boradoc book1.bdml book2.bdml book3.bdml book4.bdml
Translate multiple BDML input files in batch mode to ePUB:
boradoc target=epub book1.bdml book2.bdml book3.bdml book4.bdml
Translate multiple BDML input files in batch mode to PDF, HTML, ePUB, and Mobi targets in one command, placing the HTML target CSS in a single file:
boradoc css-output-file=site.css target=pdf,html,epub,mobi \ book1.bdml book2.bdml book3.bdml
Translate multiple BDML input files in batch mode to PDF, HTML, ePUB, and Mobi targets in one command, via a file list in a text file and placing the HTML target CSS in a single file:
boradoc css-output-file=site.css \ target=pdf,html,epub,mobi \ input-file-list=fileList.txt