DAPS Documentation › User Guide › Image Handling

Applies to DAPS 3.1

5 Image Handling #

5.1 Supported Image Types
5.2 Source Images and Generated Images
5.3 File Name Requirements
5.4 Referencing Images
5.5 DAPS Commands for Managing Images

This chapter covers the following topics:

Image formats supported by DAPS
Distinction between source images and generated images. The image directory structure required by DAPS.
Image directory structure required by DAPS.
File name requirements for source images
Referencing images in DocBook files
Managing images with DAPS commands

5.1 Supported Image Types #

Depending on the output format you generate (PDF or HTML, for example), DAPS automatically transforms the source images you provide (which are also referenced in your XML sources) into the appropriate output formats. For example, SVG images are converted to PNG for HTML builds, or color images to grayscale for black-and-white PDFs. You only need to decide which file format to use as source format. Of course, this decision depends on the purpose of the image. For more details, see the DAPS User Guide.

DAPS supports the following types of images:

DIA (input format only)
EPS (experimental)
FIG (input format only)
JPEG
PDF (experimental - only works for PDF output and with XEP formatter)
PNG
SVG

There are two types of image formats: pixel-based (also called bitmap formats) and vector-based. In pixel-based image formats the data describes the characteristics of each pixel. Vector-based image formats contain a geometric description that can be rendered smoothly. Vector-based images are resolution-independent— they can be displayed or printed as large or small as you want without showing pixel artifacts.

Among the supported image types listed below, only JPEG and PNG are pixel-based image formats.

5.1.1 DIA #

Can only be used as input format for DAPS.

DIA is a vector image format which means it is resolution-independent. Images in this format can be displayed or printed as large or small as you want without showing pixel artifacts. The format is suited especially well for creating diagrams. DIA files are XML files that are automatically compressed when saving, thus they are often quite small.

DIA files can be created using the Dia (https://live.gnome.org/Dia) application. Dia is a diagram editor for drawing entity-relationship diagrams, UML diagrams, and flowcharts.

Dia makes it easy to connect elements, add text, and use simple fill and border colors. Although Dia can import SVG files as shapes, it is not useful for freely drawing shapes itself. Dia is not designed for creating complex or effect-heavy vector illustrations and information graphics.

5.1.2 EPS #

The Encapsulated PostScript (EPS) format is a general purpose vector image format. As a Postscript-based format, it is similar to PDF. There is currently no mainstream Linux image editor software that creates EPS files natively, although various applications can export into it.

Where possible, use SVG files instead of EPS files (also because EPS images only work with XEP formatter at the moment). EPS can occasionally serve as an exchange format with contributors that use Adobe* graphics software.

Important: Limited Support with DAPS

This image format is only supported in combination with the XEP formatter. Using this format might also lead to longer document creation times.

5.1.3 JPEG #

JPEG stands for Joint Photographic Experts Group, the organization responsible for maintaining the JPEG standard designed specifically for storing photographic images. JPEG is the most common image format used by digital cameras and widely used for displaying photographs on the Web. Because of its lossy compression algorithm, the resulting file sizes are rather small compared to lossless graphics format such as TIFF, GIF, PNG, or a raw image format. The compression algorithm works well for photographs and paintings with smooth variations of tone and color. However, JPEG is not well suited for textual or iconic graphics, because sharp contrasts between adjacent pixels in such images can cause noticeable artifacts. It is also not advisable to use JPEG for files that will undergo multiple edits: the image quality deteriorates each time the file is decompressed and recompressed. This is especially true if the image is cropped or shifted.

5.1.4 PDF #

The Portable Document File format is a general purpose, page-based, fixed-layout document format. PDF is a PostScript-based format. There is a large number of Linux tools that can export PDF files natively. PDF files can also be used as an exchange format with contributors that cannot export to SVG.

Important: Limited Support with DAPS

This image format is only supported in combination with the XEP formatter. Using this format might also lead to longer document creation times.

5.1.5 PNG #

The Portable Network Graphics is a pixel-based format suitable for use with raster (point-based) images like screenshots and photographs.

PNG files can be created in several applications, including the GIMP graphics editor.

Tip: Make PNG Files Smaller with `daps optipng`

To decrease the file size of PNG images without affecting image quality, use daps optipng. It removes unused colors and alpha channels from the source PNG files. Note that it is the only DAPS command that alters sources.

To run optipng on all PNG images used in the book:

tux:~> daps -d PATH_TO_DC_FILE optipng

5.1.6 SVG #

The Scalable Vector Graphics format is a general purpose, vector image format. SVG is an XML format which can be displayed in most browsers and edited in many graphics programs.

Important: Use Plain SVG Format

Some SVG editors offer the option of saving your file in a custom SVG-based format or in Plain SVG (standard SVG). In this case, always use the plain version. Custom SVG formats might not be compatible with the components used by DAPS for processing SVG files.

XEP and FOP formatter only support SVG 1.0.

The multi-platform open source Inkscape (http://inkscape.org/) editor is a good choice for working with SVG files. You can also create SVG files in Adobe applications like Illustrator*. SVG is the preferred vector image format for DAPS.

5.2 Source Images and Generated Images #

DAPS differentiates between source images (any images that have been created outside of DAPS) and images that are generated by DAPS.

This clear distinction is also visible in the file system: source images are stored in a different directory than generated images.

DAPS requires you to use a specific directory structure for images. All images that you reference from your DocBook files must be stored in a subdirectory of the project directory named images/src/file_extension. For example, PNG files must be stored under images/src/png. If you used daps-init to set up your project, the appropriate directories should already exist. For a more detailed reference to the directory structure, see Section 2.5, “Directory Structure”.

DAPS uses source images to automatically generate appropriate image formats for each output format. The geneerated images are stored in build/.images/ within the project directory. If an image referenced in your DocBook files is changed, DAPS detects this and generates new versions of the image automatically.

DAPS provides commands for getting an overview of source images or generated images and for managing both. For details, refer to Section 5.5, “DAPS Commands for Managing Images”

5.3 File Name Requirements #

XML extension required

Always use the .xml extension, so DAPS can recognize the files, which are needed to build the document.

No Spaces and Colons In File and Directory Names

Avoid spaces and colons in file and directory names. The make command in DAPS has trouble understanding them. Use underscores (_) or hyphens (-) instead.

It is good practice to only use the following characters for file or directory names: alphabetic characters [a-z] or [A-Z], numerical characters [0-9], hyphens (-), or underscores (_).

Unique Image Names

Always store just one file with a particular name within the images/src directory of a project. As DAPS tries to create any missing image formats from original images, it will otherwise not know which one of the duplicate files to use for converting to the missing formats.

Additionally, having a file called example.png and another called example.svg in the same documentation project will often lead to questions like: Which file to use where? Do both files display the same content? Are both files current, or is one outdated?

When invoking DAPS with the parameter -v, a warning will be printed whenever a file name appears twice within a project. To specifically check for image name clashes upfront, use the daps list-images-multisrc subcommand.

It is a good idea to find a consistent file naming scheme. For example, when documenting software, it might prove helpful to include the name of the application at the beginning of the file name. You can also use prefixes like screenshot_ and diagram_ to separate between different types of images.

Note: Hint on Using UTF-8 characters in File Names

Depending on your environment, the build process could fail if you are using file names with UTF-8 characters. Run the locale command and check if the LANG environment variable contains UTF-8. Otherwise adjust the LANG environment variable accordingly.

5.4 Referencing Images #

As your images need to be located in a defined directory structure, DAPS automatically finds the path to your images. Therefore, referencing images in your XML sources is very straightforward: you must not include any path in the fileref attribute—the file name is enough.

Furthermore, DocBook allows you to reference more than one image to distinguish between different output formats. For example, you can add two references pointing to the same file, but using different images widths for PDF and HTML output. Use the role attribute to specify the output format, for example fo or html.

Example 5.1: Image Reference in an XML File #

Let us assume you have a source image file named graphic.dia. To make DAPS use an SVG version of your image for PDF output (role="fo") and a PNG version for HTML output (role="html"), reference the images as follows:

<figure>
  <title>Main Window</title>
  <mediaobject>
    <imageobject role="fo">
      <imagedata fileref="graphic.svg" width="70%"/>
    </imageobject>
    <imageobject role="html">
      <imagedata fileref="graphic.png" width="75%"/>
    </imageobject>
  </mediaobject>
</figure>

5.5 DAPS Commands for Managing Images #

DAPS offers several subcommands for managing images in a documentation project. These commands can be used to list images that are used or not used in a project, or referenced in a DocBook file but missing from the file system.

In addition to that, you can check the source images for non-unique names and reduce the size of the PNG files with an optimizer.

Subcommands for Image Listing #

Listing All Graphics Referenced in a Documentation Project

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles --noent --noxml --nodc

Lists all graphics file used by the DocBook files that are referenced in the document specified by the current DC file.

Listing Missing Graphics in a Documentation Project

tux:~> daps -d PATH_TO_DC_FILE list-images-missing

Lists all graphics that are referenced in your DocBook files, but could not be found in the file system. In case there are any missing graphics, you cannot build your project.

Listing Unused Graphics in a Documentation Project

tux:~> daps -d PATH_TO_DC_FILE list-srcfiles-unused --imgonly

Lists all graphics that are not referenced in your DocBook files, but are available in the images/src subdirectories. This command is useful if you want to clean up your source images and want to know which images are no longer needed for the documentation project.

Use this command in a directory containing a single DC-file or a DC-file referencing the whole set. Or else, images would be listed that may be used in files not referenced by the current DC-file.

Important: Use a `set` to Check for Superfluous Files

If you are storing multiple DC files in the same project directory, use the DC file of a set for this check. As it contains all articles and books in the project directory, this makes sure that any files found during the check are indeed unnecessary.

Checking for Non-Unique File Names

tux:~> daps -d PATH_TO_DC_FILE list-images-multisrc

Checks the images/src subdirectories for non-unique base names. For more information, refer to Section 5.3, “File Name Requirements”.

Reducing the File Size of PNG Graphics

tux:~> daps -d PATH_TO_DC_FILE optipng

Recompresses any PNG files in the images/src/png directory with the PNG optimizer optipng without reducing the image quality.

Deleting All Generated Images for a Documentation Project

tux:~> daps -d PATH_TO_DC_FILE clean-images

Deletes all images generated for the specified DC file. This is only necessary in rare cases; For example, when a file previously had an incorrect time stamp, or after you have changed your global DAPS configuration. In these cases, instead of re-generating the image, DAPS might wrongly assume that an already generated image should be inserted into the output file.

Viewing All Images Referenced in a File or Project

tux:~> daps -d DC-daps-example getimages --show --viewer ristretto

Opens and shows all images referenced in the documentation project in the specified image viewer (in this example, it is Ristretto). Alternatively, specify your preferred image viewer in the IMG_VIEWER parameter in the DAPS configuration file. To show only the images referenced in a specific XML file, specify the file with --file.

Note: Output of File Listings

By default, the output of the listing commands is a list of file names (including the absolute path), all printed in one line with the file names separated by blanks. This default output format is useful for piping (or copying and pasting) the output for use with another command.

If you need a pretty printed output where each file name is listed on a separate line, use the --pretty option.

See Example 5.2, “Default Output of an Image-related DAPS Command” and Example 5.3, “Pretty-printed Output of an Image-related DAPS Command” for a comparison of both outputs.

Example 5.2: Default Output of an Image-related DAPS Command #

YOUR_DOC_DIR/images/src/dia/example_dia1.dia YOUR_DOC_DIR/images/src/png/example_png1.png YOUR_DOC_DIR/images/src/png/example_png2.png YOUR_DOC_DIR/images/src/png/example_png3.png YOUR_DOC_DIR/images/src/svg/example_svg.svg ...

Example 5.3: Pretty-printed Output of an Image-related DAPS Command #

tux:~> daps -d PATH_TO_DC_FILE list-images-multisrc --pretty
YOUR_DOC_DIR/images/src/dia/example_dia1.dia
YOUR_DOC_DIR/images/src/png/example_png1.png
YOUR_DOC_DIR/images/src/png/example_png2.png
YOUR_DOC_DIR/images/src/png/example_png3.png
YOUR_DOC_DIR/images/src/svg/example_svg.svg ...

Tip: Use Pretty-Printed Output for Counting

To count the number of images listed in a given output, you can combine the --pretty parameter with the wc command:

tux:~> daps -d PATH_TO_DC_FILE list-images-multisrc --pretty | wc -l

For Example 5.3, the command above would return

5

as value.

Print this page

User Guide

5 Image Handling #

5.1 Supported Image Types #

5.1.1 DIA #

5.1.2 EPS #

Important: Limited Support with DAPS

5.1.3 JPEG #

5.1.4 PDF #

Important: Limited Support with DAPS

5.1.5 PNG #

Tip: Make PNG Files Smaller with daps optipng

5.1.6 SVG #

Important: Use Plain SVG Format

5.2 Source Images and Generated Images #

5.3 File Name Requirements #

Note: Hint on Using UTF-8 characters in File Names

5.4 Referencing Images #

Example 5.1: Image Reference in an XML File #

5.5 DAPS Commands for Managing Images #

Subcommands for Image Listing #

Important: Use a set to Check for Superfluous Files

Note: Output of File Listings

Example 5.2: Default Output of an Image-related DAPS Command #

Example 5.3: Pretty-printed Output of an Image-related DAPS Command #

Tip: Use Pretty-Printed Output for Counting

Tip: Make PNG Files Smaller with `daps optipng`

Important: Use a `set` to Check for Superfluous Files