doc/src/sgml/images/README

   1 Images
   2 ======
   3
   4 This directory contains images for use in the documentation.
   5
   6 Creating an image
   7 -----------------
   8
   9 A variety of tools can be used to create an image.  The appropriate
  10 choice depends on the nature of the image.  We prefer workflows that
  11 involve diffable source files.
  12
  13 These tools are acceptable:
  14
  15 - Graphviz (https://graphviz.org/)
  16 - Ditaa (http://ditaa.sourceforge.net/)
  17
  18 We use SVG as the format for integrating the image into the ultimate
  19 output formats of the documentation, that is, HTML, PDF, and others.
  20 Therefore, any tool used needs to be able to produce SVG.
  21
  22 This directory contains makefile rules to build SVG from common input
  23 formats, using some common styling.
  24
  25 fixup-svg.xsl applies some postprocessing to the SVG files produced by
  26 those external tools to address assorted issues.  See comments in
  27 there, and adjust and expand as necessary.
  28
  29 Both the source and the SVG output file are committed in this
  30 directory.  That way, we don't need all developers to have all the
  31 tools installed.  While we accept that there could be some gratuitous
  32 diffs in the SVG output depending the specific tool, let's keep an eye
  33 on that and keep it to a minimum.
  34
  35 Using an image in DocBook
  36 -------------------------
  37
  38 Here is an example for using an image in DocBook:
  39
  40     <figure id="gin-internals-figure">
  41      <title>GIN Internals</title>
  42      <mediaobject>
  43       <imageobject>
  44        <imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
  45       </imageobject>
  46      </mediaobject>
  47     </figure>
  48
  49 Notes:
  50
  51 - The real action is in the <mediaobject> element, but typically a
  52   <figure> should be wrapped around it and an <xref> to the figure
  53   should be put into the text somewhere.  Don't just put an image into
  54   the documentation without a link to it and an explanation of it.
  55
  56 - Things are set up so that we only need one <imagedata> element, even
  57   with different output formats.
  58
  59 - The attribute format="SVG" is required.  If you omit it, it will
  60   still appear to work, but the stylesheets do a better job if the
  61   image is declared as SVG explicitly.
  62
  63 - The width should be set to something.  This ensures that the image
  64   is scaled to fit the page in PDF output.  (Other widths than 100%
  65   might be appropriate.)