Image support in the documentation is somewhat experimental. The mechanisms described here are unlikely to change, but that is not guaranteed.
To provide conversion between different image formats, the
graphics/ImageMagick
port must be installed. This port is not included in the
textproc/docproj
meta
port, and must be installed separately.
A good example of the use of images is the
doc/en_US.ISO8859-1/articles/vm-design/
document. Examine the files in that directory to see how
these elements are used together. Build different output
formats to see how the format determines what images are shown
in the rendered document.
Two image formats are currently supported. The type of image determines which format to use.
Images that are primarily vector based, such as network
diagrams, time lines, and similar, should be in
EPS (Encapsulated Postscript) format.
These images have a .eps
extension.
For bitmaps, such as screen captures, use the
PNG (Portable Network Graphic) format.
These images have the .png
extension.
These are the only formats in which images should be committed to the documentation repository.
Use the appropriate format for each image. Documentation
will often have a mix of EPS and
PNG images. The
Makefile
s ensure that the correct format
image is chosen depending on the output format used.
Do not commit the same image to the repository in
two different formats.
The Documentation Project may eventually switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes this impractical.
Image files can be stored in one of several locations, depending on the document and image:
In the same directory as the document itself, usually done for articles and small books that keep all their files in a single directory.
In a subdirectory of the main document. Typically done when a large book uses separate subdirectories to organize individual chapters.
When images are stored in a subdirectory of the
main document directory, the subdirectory name must be
included in their paths in the
Makefile
and the
imagedata
element.
In a subdirectory of
doc/share/images
named after the document. For example, images for the
Handbook are stored in doc/share/images/books/handbook
.
Images that work for multiple translations are stored in
this upper level of the documentation file tree.
Generally, these are images that can be used unchanged in
non-English translations of the document.
Images are included as part of a
mediaobject
. The
mediaobject
can contain other, more
specific objects. We are concerned with two, the
imageobject
and the
textobject
.
Include one imageobject
, and two
textobject
elements. The
imageobject
will point to the name of the
image file without the extension. The
textobject
elements contain information
that will be presented to the user as well as, or instead of,
the image itself.
Text elements are shown to the reader in several situations. When the document is viewed in HTML, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones.
This example shows how to include an image called
fig1.png
in a document. The image is a
rectangle with an A inside it:
<mediaobject>
<imageobject>
<imagedata fileref="fig1">
</imageobject>
<textobject>
<literallayout class="monospaced">
+---------------+ </literallayout>
</textobject>
<textobject>
<phrase>
A picture</phrase>
</textobject>
</mediaobject>
Include an | |
The first Notice how the first and last lines of the content
of the | |
The second |
Images must be listed in the Makefile
in the IMAGES
variable. This variable must
contain the names of all the source
images. For example, if there are three figures,
fig1.eps
, fig2.png
,
fig3.png
, then the
Makefile
should have lines like this in
it.
or
Again, the Makefile
will work out the
complete list of images it needs to build the source document,
you only need to list the image files you
provided.
Be careful when separating documentation into smaller files in different directories (see Section 7.7.1, “Using General Entities to Include Files”).
Suppose there is a book with three chapters, and the
chapters are stored in their own directories, called
chapter1/chapter.xml
,
chapter2/chapter.xml
, and
chapter3/chapter.xml
. If each chapter
has images associated with it, place
those images in each chapter's subdirectory
(chapter1/
,
chapter2/
, and
chapter3/
).
However, doing this requires including the directory
names in the IMAGES
variable in the
Makefile
, and
including the directory name in the
imagedata
element in the document
document.
For example, if the book has
chapter1/fig1.png
, then
chapter1/chapter.xml
should
contain:
The Makefile
must contain:
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.