Section 3.7 Images
You can include an image via the
<image>tag, using the
@sourceattribute to provide a filename, likely prefixed by a relative path from the top-level of the appropriate directory. Read Section 5.6 for details on how to set these directories correctly. If you are starting a new project, using the PreTeXt-CLI (with the command
pretext new book, for example), then most of the setup portion is done for you and the top-level directory for images that are created external to the project is called
assests, and it is a sibling of the
sourcedirectory. It is your responsibility to locate that file properly relative to this directory, and that the file format is compatible. So, for example, suppose your source contained
<image source="images/butterflies.jpg"/>. Then you would want to have a directory named
imagesbelow wherever you set the
@externaltop-level directory, and you would place the
butterflies.jpgfile inside of the
@widthattribute can be used to control the size of the image. Widths are expressed as a percentage of the available width, such as
width="60%". Instead of a width, you can also specify margins and the width will be deduced.
@rotateattribute controls the angular rotation of the image about its center, for example
image/@rotate="30"will rotate the image 30° counterclockwise.
You may want to wrap your image in a
<figure>to have it centered, and to have some vertical separation above and below. A
<figure>must also have a
<caption>, and the figure will be numbered.
You can also place an “anonymous” image (no caption, no number) almost anywhere you might place a paragraph (but not within a paragraph). Note also that the
<sidebyside>tag provides some very flexible options for placing several images (Section 3.19) together, or combining figures with subcaptions.
If you wish to construct technical diagrams, with editable source, and perhaps including the use of LaTeX macros, PreTeXt provides support for authoring with graphics languages such as Asymptote, TikZ, PGF, PSTricks, and xy-pic in addition to using Sage code to describe a plot or image. In most cases output can be obtained as smoothly-scalable SVG images, in addition to other formats like PDF or PNG. Making all this happen is one of the more technical aspects of PreTeXt, so read the details in Section 4.14 along with frequent references there to the
pretextscript described in Chapter 47.
For accessibility, every
<image>should either have a description or it should explicitly declare itself to be a decorative image setting
@decorativeto the value
yes. Descriptions are of two types. A
<shortdescription>should minimally describe the important information in the image that is not already present in the surrounding text. It should have no element children except possibly
<var>children. This content will be used as the
@altattribute for the HTML
<img>. Some screen readers may cut off reading this content after the first 100–140 characters, therefore you should keep this element short. A
<description>element should be structured with
<tabular>children and has no technical limit on length. It may describe the image more completely. The content of the
<description>should describe the image, but should not be necessary for a sighted reader to take in the important features of the image. (If there are features of the image that need to be explained to all readers, this should happen in the main body of the text.) An
<image>may have one or both types of description, but it is incorrect to have neither unless
@decorativeis set to value