Docbook output to pdf

Note that this will only affect tabs in literal code spans and code blocks. Tabs in regular text are always treated as spaces. Both accept and reject ignore comments. The author and time of change is included. This option only affects the docx reader. Extract images and other media contained in or linked from the source document to the path DIR , creating it if necessary, and adjust the images references in the document so they point to the extracted files.

Media are downloaded, read from the file system, or extracted from a binary container e. The original file paths are used if they are relative paths not containing.. Otherwise filenames are constructed from the SHA1 hash of the contents. Specifies a custom abbreviations file, with abbreviations one to a line. If this option is not specified, pandoc will read the data file abbreviations from the user data directory or fall back on a system default.

The only use pandoc makes of this list is in the Markdown reader. Strings found in this list will be followed by a nonbreaking space, and the period will not produce sentence-ending space in formats like LaTeX. The strings may not contain spaces. Produce output with an appropriate header and footer e. This option is set automatically for pdf , epub , epub3 , fb2 , docx , and odt output. For native output, this option causes metadata to be included; otherwise, metadata is suppressed.

Use the specified file as a custom template for the generated document. Implies --standalone. See Templates , below, for a description of template syntax. If the template is not found, pandoc will search for it in the templates subdirectory of the user data directory see --data-dir.

If no VAL is specified, the key will be given the value true. Run pandoc in a sandbox, limiting IO operations in readers and writers to reading the files specified on the command line. But it does offer security against, for example, disclosure of files through the use of include directives.

Anyone using pandoc on untrusted user input should use this option. Templates in the user data directory are ignored. Note that some of the default templates use partials, for example styles. Print a system default data file.

Files in the user data directory are ignored. The default is native. Technically, the correct term would be ppi: pixels per inch. The default is 96dpi. When images contain information about dpi internally, the encoded value is used instead of the default specified by this option. Determine how text is wrapped in the output the source code, not the rendered version. With auto the default , pandoc will attempt to wrap lines to the column width specified by --columns default With none , pandoc will not wrap lines at all.

With preserve , pandoc will attempt to preserve the wrapping from the source document that is, where there are nonsemantic newlines in the source, there will be nonsemantic newlines in the output as well.

In ipynb output, this option affects wrapping of the contents of markdown cells. Specify length of lines in characters. This affects text wrapping in the generated source code see --wrap. It also affects calculation of column widths for plain text tables see Tables below. Include an automatically generated table of contents or, in the case of latex , context , docx , odt , opendocument , rst , or ms , an instruction to create one in the output document.

Note that if you are producing a PDF via ms , the table of contents will appear at the beginning of the document, before the title. Specify the number of section levels to include in the table of contents. The default is 3 which means that level-1, 2, and 3 headings will be listed in the contents.

Disables syntax highlighting for code blocks and inlines, even when a language attribute is given. Specifies the coloring style to be used in highlighted source code. Options are pygments the default , kate , monochrome , breezeDark , espresso , zenburn , haddock , and tango.

For more information on syntax highlighting in pandoc, see Syntax highlighting , below. See also --list-highlight-styles.

This will be parsed as a KDE syntax highlighting theme and if valid used as the highlighting style. To generate the JSON version of an existing style, use --print-highlight-style. Prints a JSON version of a highlighting style, which can be modified, saved with a. Instructs pandoc to load a KDE XML syntax definition file, which will be used for syntax highlighting of appropriately marked code blocks.

This can be used to add support for new languages or to use altered syntax definitions for existing languages. This option may be repeated to add multiple syntax definitions. Include contents of FILE , verbatim, at the end of the header.

This option can be used repeatedly to include multiple files in the header. They will be included in the order specified. Include contents of FILE , verbatim, at the beginning of the document body e.

This can be used to include navigation bars or banners in HTML documents. This option can be used repeatedly to include multiple files. List of paths to search for images and other resources.

If --resource-path is not specified, the default resource path is the working directory. Note that, if --resource-path is specified, the working directory must be explicitly listed or it will not be searched. This option can be used repeatedly. Search path components that come later on the command line will be searched before those that come earlier, so --resource-path foo:bar --resource-path baz:bim is equivalent to --resource-path baz:bim:foo:bar.

Disable the certificate verification to allow access to unsecure HTTP resources for example when the certificate is no longer valid or self signed. Produce a standalone HTML file with no external dependencies, using data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs will be sought relative to the working directory if the first source file is local or relative to the base URL if the first source file is remote.

Limitation: resources that are loaded dynamically through JavaScript cannot be incorporated; as a result, --self-contained does not work with --mathjax , and some advanced features e. This option only has an effect if the smart extension is enabled for the input format used. Currently supported for XML and HTML formats which use entities instead of UTF-8 when this option is selected , CommonMark, gfm, and Markdown which use entities , roff ms which use hexadecimal escapes , and to a limited degree LaTeX which uses standard commands for accented characters when possible.

Use reference-style links, rather than inline links, in writing Markdown or reStructuredText. By default inline links are used. The placement of link references is affected by the --reference-location option. Specify whether footnotes and references, if reference-links is set are placed at the end of the current top-level block, the current section, or the document. The default is document. Currently this option only affects the markdown , muse , html , epub , slidy , s5 , slideous , dzslides , and revealjs writers.

Specify whether to use ATX-style -prefixed or Setext-style underlined headings for level 1 and 2 headings in Markdown output. The default is atx. This option also affects Markdown cells in ipynb output.

The hierarchy order is part, chapter, then section; all headings are shifted such that the top-level heading becomes the specified type.

The default behavior is to determine the best division type via heuristics: unless other conditions apply, section is chosen. When the documentclass variable is set to report , book , or memoir unless the article option is specified , chapter is implied as the setting for this option.

By default, sections are not numbered. Sections with class unnumbered will never be numbered, even if --number-sections is specified. Offset for section headings in HTML output ignored in other output formats.

The first number is added to the section number for top-level headings, the second for second-level headings, and so on. Offsets are 0 by default. Implies --number-sections. Use the listings package for LaTeX code blocks. The package does not support multi-byte encoding for source code. To handle UTF-8 you would need to use a custom template. This issue is fully documented here: Encoding issue with the listings package.

Make list items in slide shows display incrementally one by one. The default is for lists to be displayed all at once. Specifies that headings with the specified level create slides for beamer , s5 , slidy , slideous , dzslides.

Headings above this level in the hierarchy are used to divide the slide show into sections; headings below this level create subheads within a slide.

Valid values are If a slide level of 0 is specified, slides will not be split automatically on headings, and horizontal rules must be used to indicate slide boundaries. If a slide level is not specified explicitly, the slide level will be set automatically based on the contents of the document; see Structuring the slide show. See Heading identifiers , below. Specify a method for obfuscating mailto: links in HTML documents. The default is none.

This is useful for preventing duplicate identifiers when generating fragments to be included in other pages. Link to a CSS style sheet. A stylesheet is required for generating EPUB. If none is provided using this option or the css or stylesheet metadata fields , pandoc will look for a file epub. If it is not found there, sensible defaults will be used. For best results, the reference docx should be a modified version of a docx file produced using pandoc.

The contents of the reference docx are ignored, but its stylesheets and document properties including margins, page size, header, and footer are used in the new docx. If no reference docx is specified on the command line, pandoc will look for a file reference. If this is not found either, sensible defaults will be used. To produce a custom reference. Then open custom-reference. For best results, do not make changes to this file other than modifying the styles used by pandoc:.

If no reference ODT is specified on the command line, pandoc will look for a file reference. Templates included with Microsoft PowerPoint either with. The specific requirement is that the template should contain layouts with the following names as seen within PowerPoint :. For each name, the first layout found with that name will be used.

If no layout is found with one of the names, pandoc will output a warning and use the layout with that name from the default reference doc instead.

How these layouts are used is described in PowerPoint layout choice. All templates included with a recent version of MS PowerPoint will fit these criteria.

You can click on Layout under the Home menu to check. You can also modify the default reference. Use the specified image as the EPUB cover. It is recommended that the image be less than px in width and height. The file should contain a series of Dublin Core elements. For example:. Any of these may be overridden by elements in the metadata file. Embed the specified font in the EPUB. This option can be repeated to embed multiple fonts. However, if you use wildcards on the command line, be sure to escape them or put the whole filename in single quotes, to prevent them from being interpreted by the shell.

To use the embedded fonts, you will need to add declarations like the following to your CSS see --css :. The default is to split into chapters at level-1 headings. This option only affects the internal composition of the EPUB, not the way chapters and sections are displayed to users. Some readers may be slow if the chapter files are too large, so for large documents with few level-1 headings, one might want to use a chapter level of 2 or 3.

The default is EPUB. To put the EPUB contents in the top level, use an empty string. Determines how ipynb output cells are treated. The default is best. Use the specified engine when producing PDF output. Valid values are pdflatex , lualatex , xelatex , latexmk , tectonic , wkhtmltopdf , weasyprint , prince , context , and pdfroff.

If the engine is not in your PATH, the full path of the engine may be specified here. Use the given string as a command-line argument to the pdf-engine. Note that no check for duplicate options is done. Process the citations in the file, replacing them with rendered citations and adding a bibliography. Citation processing will not take place unless bibliographic data is supplied, either through an external file specified using the --bibliography option or the bibliography field in metadata, or via a references section in metadata containing a list of citations in CSL YAML format with Markdown formatting.

The style is controlled by a CSL stylesheet specified using the --csl option or the csl field in metadata. If no stylesheet is specified, the chicago-author-date style will be used by default. The citation processing transformation may be applied before or after filters or Lua filters see --filter , --lua-filter : these transformations are applied in the order they appear on the command line. For more information, see the section on Citations. If you supply this argument multiple times, each FILE will be added to bibliography.

If FILE is not found relative to the working directory, it will be sought in the resource path see --resource-path. If FILE is not found relative to the working directory, it will be sought in the resource path see --resource-path and finally in the csl subdirectory of the pandoc user data directory. Use natbib for citations in LaTeX output. This option is not for use with the --citeproc option or with PDF output. It is intended for use in producing a LaTeX file that can be processed with bibtex.

Use biblatex for citations in LaTeX output. It is intended for use in producing a LaTeX file that can be processed with bibtex or biber. The default is to render TeX math as far as possible using Unicode characters.

However, this gives acceptable results only for basic math, usually you will want to use --mathjax or another of the following options. Then the MathJax JavaScript will render it. This is the default in odt output.

That directory should contain a katex. Print information about command-line arguments to stdout , then exit. This option is intended primarily for use in wrapper scripts. The first line of output contains the name of the output file specified with the -o option, or - for stdout if no output file was specified. The remaining lines contain the command-line arguments, one per line, in the order they appear.

These do not include regular pandoc options and their arguments, but do include any options appearing after a -- separator at the end of the line. Ignore command-line arguments for use in wrapper scripts. Regular pandoc options are not ignored. If pandoc completes successfully, it will return exit code 0. Nonzero exit codes have the following meanings:. The --defaults option may be used to specify a package of options. Here is a sample defaults file demonstrating all of the fields that may be used:.

Fields that are omitted will just have their regular default values. So a defaults file can be as simple as one line:. In fields that expect a file path or list of file paths , the following syntax may be used to interpolate environment variables:. This allows you to refer to resources contained in that directory:. This environment variable interpolation syntax only works in fields that expect file paths. Default files can be placed in the defaults subdirectory of the user data directory and used from any directory.

For example, one could create a file specifying defaults for writing letters, save it as letter. Note that, where command-line arguments may be repeated --metadata-file , --css , --include-in-header , --include-before-body , --include-after-body , --variable , --metadata , --syntax-definition , the values specified on the command line will combine with values specified in the defaults file, rather than replacing them.

To see the default template that is used, just type. A custom template can be specified using the --template option. Templates contain variables , which allow for the inclusion of arbitrary information at any point in the file.

In addition, some variables are given default values by pandoc. If you use custom templates, you may need to revise them as pandoc changes. We recommend tracking the changes in the default templates, and modifying your custom templates accordingly. An easy way to do this is to fork the pandoc-templates repository and merge in changes after each pandoc release.

The styles may also be mixed in the same template, but the opening and closing delimiter must match in each case. The opening delimiter may be followed by one or more spaces or tabs, which will be ignored. The closing delimiter may be followed by one or more spaces or tabs, which will be ignored. A slot for an interpolated variable is a variable name surrounded by matched delimiters.

The keywords it , if , else , endif , for , sep , and endfor may not be used as variable names. Variable names with periods are used to get at structured variable values. So, for example, employee. A conditional begins with if variable enclosed in matched delimiters and ends with endif enclosed in matched delimiters. It may optionally contain an else enclosed in matched delimiters.

The if section is used if variable has a non-empty value, otherwise the else section is used if present. The keyword elseif may be used to simplify complex nested conditionals:. A for loop begins with for variable enclosed in matched delimiters and ends with endfor enclosed in matched delimiters.

You may optionally specify a separator between consecutive values using sep enclosed in matched delimiters. The material between sep and the endfor is the separator.

Instead of using variable inside the loop, the special anaphoric keyword it may be used. Partials subtemplates stored in different files may be included by using the name of the partial, followed by , for example:.

Partials will be sought in the directory containing the main template. The file name will be assumed to have the same extension as the main template if it lacks an extension.

When calling the partial, the full name including file extension can also be used:. If a partial is not found in the directory of the template and the template path is given as a relative path, it will also be sought in the templates subdirectory of the user data directory.

If articles is an array, this will iterate over its values, applying the partial bibentry to each one. So the second example above is equivalent to. Note that the anaphoric keyword it must be used when iterating over partials.

In the above examples, the bibentry partial should contain it. A separator between values of an array may be specified in square brackets, immediately after the variable name or partial:. The separator in this case is literal and unlike with sep in an explicit for loop cannot contain interpolated variables or other template directives. In this example, if item. A pipe transforms the value of a variable or partial.

If the original value was an array, the key will be the array index, starting with 1. This can be used to get lettered enumeration from array indices. To get uppercase letters, chain with uppercase. To get uppercase roman, chain with uppercase. Has no effect on other values. This can be used to align material in tables. Widths are positive integers indicating the number of characters.

These can be set through a pandoc title block , which allows for multiple authors, or through a YAML metadata block :. Note that if you just want to set PDF or HTML metadata, without including a title block in the document itself, you can set the title-meta , author-meta , and date-meta variables. By default these are set automatically, based on title , author , and date.

The page title in HTML is set by pagetitle , which is equal to title by default. Additionally, any root-level string metadata, not included in ODT, docx or pptx metadata is added as a custom property. The following YAML metadata block for instance:. The Language subtag lookup tool can look up or verify these tags. Use native pandoc Divs and Spans with the lang attribute to switch the language:.

For bidirectional documents, native pandoc span s and div s with the dir attribute value rtl or ltr can be used to override the base direction in some output formats.

This may not always be necessary if the final renderer e. To override or extend some CSS for just one document, include for example:. All reveal. To turn off boolean flags that default to true in reveal. These variables change the appearance of PDF slides using beamer.

These variables control the visual aspects of a slide show that are not easily controlled via templates. For example, to use the Libertine font with proportional lowercase old-style figures through the libertinus package:.

Allow for any choices available through fontspec ; repeat for multiple options. For example, to use the TeX Gyre version of Palatino with lowercase figures:. These variables function when using BibLaTeX for citation rendering. Pandoc uses these variables when creating a PDF with wkhtmltopdf. The --css option also affects the output.

Pandoc sets these variables automatically in response to options or document contents; users can also modify them. These vary depending on the output format, and include the following:.

You can use the following snippet in your template to distinguish them:. Similarly, outputfile can be - if output goes to the terminal. If you need absolute paths, use e. The behavior of some of the readers and writers can be adjusted by enabling or disabling various extensions. The markdown reader and writer make by far the most use of extensions. In the following, extensions that also work for other formats are covered. Note that markdown extensions added to the ipynb format affect Markdown cells in Jupyter notebooks as do command-line options like --atx-headers.

Interpret straight quotes as curly quotes, as em-dashes, -- as en-dashes, and Note: If you are writing Markdown, then the smart extension has the reverse effect: what would have been curly quotes comes out straight. If smart is disabled, then in reading LaTeX pandoc will parse these characters literally.

In writing LaTeX, enabling smart tells pandoc to use the ligatures when possible; if smart is disabled pandoc will use unicode quotation mark and dash characters.

A heading without an explicitly specified identifier will be automatically assigned a unique identifier based on the heading text. These rules should, in most cases, allow one to determine the identifier from the heading text. The exception is when several headings have the same text; in this case, the first will get an identifier as described above; the second will get the same identifier with -1 appended; the third with -2 ; and so on.

These identifiers are used to provide link targets in the table of contents generated by the --toc --table-of-contents option. They also make it easy to provide links from one section of a document to another. A link to this section, for example, might look like this:. Accents are stripped off of accented Latin letters, and non-Latin letters are omitted.

Emojis are replaced by their names. However, they can also be used with HTML input. This is handy for reading web pages formatted using MathJax, for example. By default, this is disabled for HTML input. This means that. In Markdown output, code blocks with classes haskell and literate will be rendered using bird tracks, and block quotations will be indented one space, so they will not be treated as Haskell code.

In restructured text output, code blocks with class haskell will be rendered using bird tracks. In LaTeX input, text in code environments will be parsed as Haskell code. In LaTeX output, code blocks with class haskell will be rendered inside code environments. In HTML output, code blocks with class haskell will be rendered with class literatehaskell and bird tracks.

Note that GHC expects the bird tracks in the first column, so indented literate code blocks e. Links to headings, figures and tables inside the document are substituted with cross-references that will use the name or caption of the referenced item. The original link text is replaced once the generated document is refreshed. That's all there is to it. It's about the same as learning HTML: learn the basics in the first few minutes, and keep a reference handy to learn more as needed.

Depending on how much you know about XML, there can be a few surprises, but the DocBook website clearly defines valid parent and child relationships for each and every tag, and each entry for each tag provides big blocks of examples.

Finally, DocBook is important because it provides data about your data. DocBook tags aren't meant to dictate a style over your content, but to classify the information you are trying to convey. DocBook tags provide semantic meaning to your words. Semantics might not seem that important to you now, but here are two great examples of times that metadata became truly important in the real world:.

Here's a quick and easy way to get started with DocBook. This method emphasizes learning DocBook tags and syntax rather than building a complex and flexible tool chain. If you are ever in doubt about whether or not a tag is required, just refer to the tag's documentation. The synopsis section tells you what is required and what is optional.

And that's all there is to it. The more you write in DocBook, the more tags and attributes you learn, and eventually you'll probably find it hard to go back to a less explicit format. The default DocBook render from most processors aside from Pandoc looks a little something like this:. It's professional, but painfully so. Still, it's an important foundation upon which additional styles can be applied.

Otherwise, here's a brief introduction to XSL and the xsltproc command. If you install DocBook from your Linux distribution or from the DocBook website, you are installing all the default DocBook stylesheets.

These serve as the fallback styles whenever you use a tool like xsltproc or xmlto. If you cannot or choose not to install DocBook, you can point to the stylesheets manually in your xsltproc command. Building a PDF with xsltproc is a two-step process.

First, you must generate the. Then you process the. An easy modification to make when just getting started with styling DocBook is your font choice.

Fonts are easy to change and make a noticeable difference in your end product. This registers all the TTF fonts in your personal or system fonts directory. You don't have to point it to standard font directories, but it must be an absolute, not relative, path. I use both methods, depending on the gravity of the change. For simple styles that I change often, like page size sometimes I need A4, other times US Letter , fonts, and so on, I pass parameters as part of my command.

That way I can change them quickly and easily and independently of my custom stylesheets. To set fonts:. For styles less likely to change based on printer requirements, page size, or mood, I place rules in a custom XSL template. XSL templates can get very complex, so making minor adjustments and learning over time is a good approach. A common visual cue seen in printed books is an admonition, like a note, tip, or warning, printed over a background color to let the reader know it is separate from the current narrative but still important to the topic.

Admonitions are distinct elements in DocBook, so they're relatively simple to style. First, create a new file called mystyle. Edit it so that it contains this heading:. The xsl:import line must point to the stylesheet on your system, whether you have installed it or you are using it from a nonstandard location in your home directory.

This creates a template in your stylesheet for all elements that match the note. The syntax is nowhere as terse or simple as CSS syntax. However, simple styles follow the same format:. Like CSS, getting to know all your options takes time and practice, but once you get the hang of it, it's simple.

More complex XML gets you more complex rules with dependencies, variables, conditionals, and more. DocBook was invented for tech writers, and many of its tags reflect that. However, I use DocBook for everything, whether it's tech writing, fiction, or RPG design , it's a powerful, industry-strength system.

This doesn't mean that there's no place in the world for Markdown or org-mode or other text formats. Usually you write your own stylesheet that imports the 'standard' style sheet. It also sets a few parameters: - Set the maximum depth of the TOC table of contents to '1'. For other output format you need other settings. Makefile If you have multiple XML files or style sheets you may want to have all the processing done in a Makefile.

For some reason, the xsl-fo stylesheet is in the docbook-xsl-doc-pdf package. Note: The w3-Organization has blocked the download of the necessary dtd files by unknown user agents. The workaround seems to be to set up a local dtd repository, as noted here and here. The dblatex program can also do this.

Editing Programs Bluefish This editor has syntax highlighting and code snippets for DocBook and many other languages. Doesn't hide the gory details.

You still need to read the DocBook reference. Just makes it graphical. Some use Emacs only for psgml-mode. It does real-time syntax and error highlighting. See also DocBookEditors. DocBook last edited by Bolaram Paul. Partners Support Community Ubuntu. Page History Login to edit.