69 lines
2.4 KiB
Plaintext
69 lines
2.4 KiB
Plaintext
Images
|
|
======
|
|
|
|
This directory contains images for use in the documentation.
|
|
|
|
Creating an image
|
|
-----------------
|
|
|
|
A variety of tools can be used to create an image. The appropriate
|
|
choice depends on the nature of the image. We prefer workflows that
|
|
involve diffable source files.
|
|
|
|
These tools are acceptable:
|
|
|
|
- Graphviz (https://graphviz.org/)
|
|
- Ditaa (http://ditaa.sourceforge.net/)
|
|
|
|
We use SVG as the format for integrating the image into the ultimate
|
|
output formats of the documentation, that is, HTML, PDF, and others.
|
|
Therefore, any tool used needs to be able to produce SVG.
|
|
|
|
This directory contains makefile rules to build SVG from common input
|
|
formats, using some common styling.
|
|
|
|
Both the source and the SVG output file are committed in this
|
|
directory. That way, we don't need all developers to have all the
|
|
tools installed. While we accept that there could be some gratuitous
|
|
diffs in the SVG output depending the specific tool, let's keep an eye
|
|
on that and keep it to a minimum.
|
|
|
|
Using an image in DocBook
|
|
-------------------------
|
|
|
|
Here is an example for using an image in DocBook:
|
|
|
|
<figure id="gin-internals-figure">
|
|
<title>GIN Internals</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
|
|
Notes:
|
|
|
|
- The real action is in the <mediaobject> element, but typically a
|
|
<figure> should be wrapped around it and an <xref> to the figure
|
|
should be put into the text somewhere. Don't just put an image into
|
|
the documentation without a link to it and an explanation of it.
|
|
|
|
- Things are set up so that we only need one <imagedata> element, even
|
|
with different output formats.
|
|
|
|
- The attribute format="SVG" is required. If you omit it, it will
|
|
still appear to work, but the stylesheets do a better job if the
|
|
image is declared as SVG explicitly.
|
|
|
|
- The width should be set to something. This ensures that the image
|
|
is scaled to fit the page in PDF output. (Other widths than 100%
|
|
might be appropriate.)
|
|
|
|
- SVG images should be scalable as they will be rendered in a variety
|
|
of places (web, PDF, etc.) as well as in different viewports
|
|
(desktop, mobile, etc.). To help the images successfully scale,
|
|
employ a "viewBox" attribute in the SVG tag. For example,
|
|
to create an image with a default width and height of 400x300,
|
|
you would use viewBox="0.00 0.00 400.00 300.00"
|