DAPS AsciiDoc Quick Start Guide #

The following directory structure is recommended for AsciiDoc projects:

PROJECT_ROOT/ 1
     |--DC-* 2
     |--adoc/ 3
     |   |--MAIN.adoc 4
     |   |--\*.adoc
     |   |--images/ 5
     |   |  |--\*.dia/
     |   |  |--\*.jpg
     |   |  |--\*.png/
     |   |  |--\*.svg/

A configuration file in the project directory. Each book, article, or man page in a project can have its own documentation configuration file (DC file). It defines several parameters for your documentation deliverable (for example, the MAIN file, layout variants, or whether to render the sources as article or book). Although not mandatory, creating a DC file for each deliverable is recommended. You can store deliverable-specific configuration options in the DC-file that you otherwise need to enter on the command line each time you call DAPS.

DC files need to be placed in the project root. The file names need to start with DC-. The rest of the file name is used to name directories and files created by DAPS. For example, if a DC-file is named DC-adoc_test, file names and directories will start with adoc_test.

Of the multiple parameters that can be set in the DC file, the only one required is MAIN. It points to the MAIN AsciiDoc file that you want to process. Create at least one DC file per book or article.

## Doc config file for the DAPS example document
## See /etc/daps/config for documentation of the settings below
##

# MAIN file (mandatory) 1
#
MAIN="MAIN-example.adoc"

#----- optional parameters -----

# Image directory  2
#
ADOC_IMG_DIR="adoc/images"

# Type 3
#
ADOC_TYPE="book"

# Turn on postprocessing  4
#
ADOC_POST="yes"

# Stylesheet directory  5
#
STYLEROOT="/usr/share/xml/docbook/stylesheet/daps2013"

# XSLT Parameters for customizing the stylesheets 6
#
XSLTPARAM="--stringparam homepage=https://github.com/openSUSE/daps"
XSLTPARAM+="--param variablelist.as.blocks=1"

The example above only shows a few options you can set. For a complete reference, refer to the DAPS configuration file at /etc/daps/config. An overview of the AsciiDoc-specific configuration options is also available at Section A.1, “Command Line Options and Configuration Settings for AsciiDoc”.

One of the core features of DAPS is automatic image conversion. Whether images need to be converted to grayscale for a printable PDF, whether .dia images need to be converted to SVG, or whether .svg images need to be converted to PNG—​DAPS automatically takes care. You only need to make sure that the image is available in a supported format in the AsciiDoc images directory. Refer to Image Handling (https://opensuse.github.io/daps/doc/cha.daps.user.img.html) for details.

When linking an image in the AsciiDoc sources, use the attribute :imagesdir: in the document header. Always use the file name only. The path for :imagesdir: is best specified relatively (relative to the adoc/ directory). Specifying :imagesdir: is optional, but recommended. It allows you to also process your AsciiDoc sources with tools other than DAPS.

= Linking images

:author: John Doe
:imagesdir: images/

This is an example of how to link images in AsciiDoc documents processed with DAPS.

image::test.png[Test Image]

For the example above, the images need to reside in adoc/images. Possible sources for the images in adoc/images are:

The AsciiDoc source example requests a PNG file. If it exists, it will be used as is. If it does not exist, DAPS will search for an image with the base name test (test.svg, test.dia) and automatically convert it to PNG.

Important: Unique Image Names

Because of the procedure described above, DAPS requires unique base names for images. If you would have two files with different content but the same base name, for example test.svg and test.dia, the outcome of an automatic conversion would be uncertain (could be either one of the two files). Therefore make sure to always use unique base names. To test for non-unique images, use the following daps command: daps -d <DCFILE> list-images-multisrc.

In AsciiDoc, image scaling is often achieved by setting pixel height/width. However, using plain pixel values for scaling is not supported well in DAPS and will usually cause issues in PDF builds. To scale images, instead use the scaledwidth attribute with a percentage:

image::test.png[Test Image, scaledwidth=100%]

If you want to create output for parts of the documents (for example, to send a single chapter or section for review), you do not need to create the whole document and cut out the parts you need. DAPS supports creating partial documents on section titles for any of the supported output formats. All that is required is an anchor preceding the section title:

Example: Section title with an Anchor. 

[[new_chapter]]
== Brand New Chapter

This chapter is brand new

This anchor, new_chapter in the example above, can be passed to DAPS with the --rootid parameter. The following example shows how to build a PDF only containing the chapter "Brand New Chapter":

daps -d DC-_MYADOC_ pdf --rootid="new_chapter"

DAPS also supports spell checking your sources. This is especially convenient, when your sources contain include files. A spellcheck with DAPS automatically checks all included files. DAPS supports the backends aspell and hunspell for spellchecking.

daps -d DC-_MYADOC_ spellcheck --lang=en_GB --spell-checker=hunspell