Image support in the documentation is currently extremely experimental. The mechanisms described here are unlikely to change, but that is not guaranteed.
Installation of the
graphics/ImageMagick
port is required. It is used to convert between the different
image formats. This port is not in
the textproc/docproj
meta
port, it must be installed by hand.
The best example of what follows in practice is the
doc/en_US.ISO8859-1/articles/vm-design/
document. If the description that follows is unclear, take a
look at the files in that directory to see how everything
hangs together. Experiment with creating different formatted
versions of the document to see how the image markup appears
in the formatted output.
Two image formats are currently supported. Which to choose will depend on the nature of the image.
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 Subversion repository.
Use the appropriate format for each image. It is to be
expected that documentation will have a mix of
EPS and PNG images. The
Makefile
s ensure that the correct format
image is chosen depending on the output format that you use
for your documentation. Do not commit the same
image to the repository in two different
formats.
It is anticipated that the Documentation Project will switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes this impractical.
The markup for an image is relatively simple. First,
markup 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.
There are two circumstances where this can happen.
When the reader is viewing the documentation in HTML. In this case, each image will need associated alternate text to show the user, typically while the image is loading, or if they hover the mouse pointer over the image.
When the reader is viewing the documentation in plain text. In this case, each image should have an ASCII art equivalent to show the user.
An example will make things easier to understand. Suppose
there is an image called fig1.png
that is
to be included in the document. This image is of a rectangle
with an A inside it. The markup for this would be as
follows.
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 3.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, it is suggested to 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:
Then everything will work.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.