<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
 type="text/xml"
 title="Profiling step"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>
<chapter id="cha.daps.user.img">
 <title>Image Handling</title>
 <abstract>
  <para>
   This chapter covers the following topics:
   <itemizedlist>
    <listitem>
     <para>
      Image formats supported by &dapsacr;
     </para>
    </listitem>
    <listitem>
     <para>
      Distinction between source images and generated images. The
      image directory structure required by &dapsacr;.
     </para>
    </listitem>
    <listitem>
     <para>
      Image directory structure required by &dapsacr;.
     </para>
    </listitem>
    <listitem>
     <para>
      File name requirements for source images
     </para>
    </listitem>
    <listitem>
     <para>
      Referencing images in DocBook files
     </para>
    </listitem>
    <listitem>
     <para>
      Managing images with &dapsacr; commands
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </abstract>
 <sect1 id="sec.daps.user.imgs.usage">
  <title>Supported Image Types</title>
  &daps-images-intro;
  &daps-img-formats;

  <para>
    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&mdash;<remark>dpopov 2016-10-11: scalable is better
    than resolution-independent?</remark> they can be displayed or printed as
    large or small as you want without showing pixel artifacts.
  </para>

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

  <sect2 id="sec.daps.user.imgs.usage.dia">
   <title>DIA</title>
   <para>Can only be used as input format for &dapsacr;.</para>
   <para>
    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.
   </para>
   <para>
    DIA files can be created using the <ulink
    url="https://live.gnome.org/Dia">Dia</ulink> application. Dia is a diagram
    editor for drawing entity-relationship diagrams, UML diagrams, and
    flowcharts.
   </para>
   <para>
    Dia makes it easy to connect elements, add text, and use simple fill and
    border colors. Although Dia can import <acronym>SVG</acronym> 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.
   </para>
 </sect2>

  <sect2 id="sec.daps.user.imgs.usage.eps">
   <title>EPS</title>
   <para>
    The <emphasis>Encapsulated PostScript</emphasis> (EPS) format is a
    general purpose vector image format. As a Postscript-based format, it is
    similar to <acronym>PDF</acronym>. There is currently no mainstream
    Linux image editor software that creates <acronym>EPS</acronym> files
    natively, although various applications can export into it.
   </para>
   <para>
    Where possible, use <acronym>SVG</acronym> files instead of
    <acronym>EPS</acronym> files (also because EPS images only work with XEP
    formatter at the moment).  <acronym>EPS</acronym> can occasionally serve
    as an exchange format with contributors that use Adobe* graphics software.
   </para>
   &daps-img-format-support;
  </sect2>

  <sect2 id="sec.daps.user.imgs.usage.fig">
   <title>FIG</title>
   <para>Can only be used as input format for &dapsacr;.</para>
   <para>
    <acronym>FIG</acronym> is a vector image format that can be created with
    the <ulink url="http://www.xfig.org">Xfig</ulink> application. The support
    for <acronym>FIG</acronym> files can be useful when working with legacy
    images. However, it is recommended to use <acronym>SVG</acronym> format
    for new illustrations and <acronym>DIA</acronym> for new diagrams.
   </para>
  </sect2>
  
  <sect2 id="sec.daps.user.imgs.usage.jpeg">
   <title>JPEG</title>
   <para>
     <acronym>JPEG</acronym> stands for <emphasis>Joint Photographic Experts
     Group</emphasis>, 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.
   </para>
  </sect2>
  
  
  <sect2 id="sec.daps.user.imgs.usage.pdf">
   <title>PDF</title>
   <para>
    The <emphasis>Portable Document File</emphasis> format is a general
    purpose, page-based, fixed-layout document format. <acronym>PDF</acronym>
    is a PostScript-based format. There is a large number of Linux tools that
    can export <acronym>PDF</acronym> files natively. <acronym>PDF</acronym>
    files can also be used as an exchange format with contributors that cannot
    export to <acronym>SVG</acronym>.
   </para>
   &daps-img-format-support;
  </sect2>

  <sect2 id="sec.daps.user.imgs.usage.png">
   <title>PNG</title>
   <para>
    The <emphasis>Portable Network Graphics</emphasis> is a pixel-based format
    suitable for use with raster (point-based) images like screenshots and
    photographs.
   </para>
   <para>
    <acronym>PNG</acronym> files can be created in several
    applications, including the GIMP graphics editor.
   </para>
   <tip>
    <title>Make PNG Files Smaller with <command>daps optipng</command>
    </title>
    <para> To decrease the file size of PNG images without affecting image quality, use
     <command>daps optipng</command>. It removes unused colors and alpha channels from the source
     PNG files. Note that it is the only &dapsacr; command that alters sources.</para>
    <para>
     To run <command>optipng</command> on all <acronym>PNG</acronym> images used in the book:
    </para>
    <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> optipng</screen>
   </tip>
  </sect2>

  <sect2 id="sec.daps.user.imgs.usage.svg">
   <title>SVG</title>
   <para>
    The <emphasis>Scalable Vector Graphics</emphasis> format is a general
    purpose, vector image format. <acronym>SVG</acronym> is an XML format
    which can be displayed in most browsers and edited in many graphics
    programs.
   </para>
   <important>
    <title>Use <emphasis>Plain SVG</emphasis> Format</title>
    <para>
     Some SVG editors offer the option of saving your file in a custom
     SVG-based format or in <emphasis>Plain SVG</emphasis>
     (<emphasis>standard SVG</emphasis>). In this case, always use the plain
     version. Custom SVG formats might not be compatible with the components
     used by &dapsacr; for processing SVG files.
    </para>
    <para>XEP and FOP formatter only support SVG 1.0.</para>
   </important>
   <para>
    The multi-platform open source <ulink url="http://inkscape.org/">Inkscape</ulink> editor is a good choice for working with <acronym>SVG</acronym> files. You can also create <acronym>SVG</acronym>
    files in Adobe applications like Illustrator*. SVG is the preferred vector image format for &dapsacr;.
   </para>
  </sect2>


 </sect1>
 <sect1 id="sec.daps.user.imgs.src.gen">
  <title>Source Images and Generated Images</title>

  <para>
   &dapsacr; differentiates between source images (any images that
   have been created outside of &dapsacr;) and images that are generated by
   &dapsacr;.
  </para>

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

  <para>
   &daps-images-dir; For a more detailed reference to the directory structure, see
   <xref linkend="sec.daps.user.basics.dirstruct"/>.
  </para>

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

  <para>
   &dapsacr; provides commands for getting an overview of source images or
   generated images and for managing both. For details, refer to <xref
   linkend="sec.daps.user.imgs.manage"/>
  </para>
 </sect1>
 <sect1 id="sec.daps.user.imgs.req">
  <title>File Name Requirements</title>
   &daps-file-names-req;
  </sect1>
 <sect1 id="sec.daps.user.imgs.refer">
  <title>Referencing Images</title>
  &daps-img-ref;
  <example id="ex.daps.user.xml.img.ref">
   <title>Image Reference in an XML File</title>
     &ex-daps-img-ref;
  </example>
 </sect1>
 <sect1 id="sec.daps.user.imgs.manage">
  <title>&dapsacr; Commands for Managing Images</title>

  <para>
    &dapsacr; 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.
  </para>
  <para>
    In addition to that, you can check the source images for non-unique
    <remark>dpopov 2016-10-11: duplicate?</remark> names and reduce the size
    of the <acronym>PNG</acronym> files with an optimizer.
  </para>

  <variablelist id="vl.daps.user.imgs.manage.cmds">
   <title>Subcommands for Image Listing</title>
   <varlistentry>
    <term>Listing All Graphics Referenced in a Documentation Project
     </term>
    <listitem>
     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--noent&nbsp;--noxml&nbsp;--nodc</screen>
     <para> Lists all graphics file used by the DocBook files that are referenced in the document
      specified by the current &dc; file. </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
      Listing Missing Graphics in a Documentation Project</term>
    <listitem>
     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-images-missing</screen>
     <para> 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. </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Listing Unused Graphics in a Documentation Project</term>
    <listitem>
     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles-unused&nbsp;--imgonly</screen>
     <para> Lists all graphics that are <emphasis>not</emphasis> referenced in
      your DocBook files, but are available in the
       <filename>images/src</filename> subdirectories. <remark>taroth
       2013-01-04: fs, is the above correct?</remark> 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. </para>
     <para>
		 Use this command in a directory containing a single DC-file or a
		 DC-file referencing the whole <sgmltag>set</sgmltag>. Or else, 
		 images would be listed that may be used in files not referenced 
		 by the current DC-file.
	 </para>
    &daps-note-superfluous-files;
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Checking for Non-Unique File Names</term>
    <listitem>
     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-images-multisrc</screen>
     <para> Checks the <filename>images/src</filename> subdirectories for
      non-unique base names. For more information, refer to <xref
       linkend="sec.daps.user.imgs.req"/>. </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Reducing the File Size of PNG Graphics</term>
    <listitem>
     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;optipng</screen>
     <para> Recompresses any PNG files in the
       <filename>images/src/png</filename> directory with the PNG optimizer
       <literal>optipng</literal> without reducing the image quality. </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Deleting All Generated Images for a Documentation Project</term>
    <listitem>
     <screen>&prompt.user;&dapscmd; -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;clean-images</screen>
     <para> 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 &dapsacr;
      configuration. In these cases, instead of re-generating the image, &dapsacr; might wrongly assume that an
      already generated image should be inserted into the output file.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Viewing All Images Referenced in a File or Project</term>
    <listitem><screen>&prompt.user;&dapscmd; -d&nbsp;DC-daps-example&nbsp;getimages&nbsp;--show&nbsp;--viewer ristretto</screen>
     <para>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
       <parameter>IMG_VIEWER</parameter> parameter in the &dapsacr; configuration file. To show
      only the images referenced in a specific XML file, specify the file with
       <option>--file</option>. </para>
    </listitem>
   </varlistentry>
  </variablelist>
  
  <!--taroth 2015-04-24: keep in sync with similar content in daps_user_edit.xml-->
  &daps-note-filelists; 
  
  <para> See 
   <xref linkend="ex.daps.graphics.output.default"/> and 
   <xref linkend="ex.daps.graphics.output.pretty"/> for a comparison of both outputs.</para>
  
  <example id="ex.daps.graphics.output.default">
   <title>Default Output of an Image-related &dapsacr; Command</title>
   <screen><?dbsuse-fo font-size="0.70em"?><replaceable>YOUR_DOC_DIR</replaceable>/images/src/dia/example_dia1.dia <replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png1.png <replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png2.png <replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png3.png <replaceable>YOUR_DOC_DIR</replaceable>/images/src/svg/example_svg.svg <replaceable>YOUR_DOC_DIR</replaceable>/images/src/fig/example_fig1.fig ...</screen>
  </example>
  
  <example id="ex.daps.graphics.output.pretty">
   <title>Pretty-printed Output of an Image-related &dapsacr;
    Command</title>
   <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-images-multisrc&nbsp;--pretty</command>
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/dia/example_dia1.dia
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png1.png
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png2.png
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png3.png
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/svg/example_svg.svg
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/fig/example_fig1.fig ...</screen>
  </example>
  
  <tip>
   <title>Use Pretty-Printed Output for Counting</title>
   <para> To count the number of images listed in a given output, you can combine the <parameter>--pretty</parameter> parameter with the
    <command>wc</command> command: </para>
   <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> list-images-multisrc --pretty | wc -l</screen>
   <para> For <xref linkend="ex.daps.graphics.output.pretty"
    xrefstyle="select:label"/>, the command above would return 
    <computeroutput>5</computeroutput> as value.
   </para>
  </tip>
 </sect1>
</chapter>
