| 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.) |