add entry - create external link which opens in a new tab

[sitka/doc/style.git] / style / style-image.xml

<?xml version="1.0" encoding="utf-8"?>\r
<chapter xml:id="style-image" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
\r
    <info>\r
        <title>Image Formatting</title>\r
    </info>\r
\r
    <itemizedlist>\r
        <listitem>\r
            <para>.png is the preferred image format, though .jpg from legacy conversions are\r
                acceptable</para>\r
        </listitem>\r
        <listitem>\r
            <para>Images are stored in <emphasis>media</emphasis> directories for each <markup\r
                    linkend="part">part</markup>.</para>\r
        </listitem>\r
        <listitem>\r
            <para>Images up to 900px wide can be displayed without resizing. Images larger than\r
                900px are scaled down with the <emphasis>scalefit="1"</emphasis> attribute as shown\r
                below.</para>\r
        </listitem>\r
        <listitem>\r
            <para>When scaling DocBook uses both the size (pixels) and resolution (dpi or pixels/in)\r
                of image files. Source images should be at 96dpi, a default chosen to match legacy\r
                images. 96dpi seems to be standard in FullShot; if using Gimp change the default for\r
                new images from 72 pixels/in to 96 pixels/in under <menuchoice>\r
                    <guimenu>File</guimenu>\r
                    <guisubmenu>Preferences</guisubmenu>\r
                    <guimenuitem>Default Image</guimenuitem>\r
                </menuchoice></para>\r
        </listitem>\r
    </itemizedlist>\r
\r
    <simplesect>\r
        <title>Images 900px wide or less</title>\r
        <para>If the source image is 900px wide or less use the following code</para>\r
        <programlisting><![CDATA[ \r
    <mediaobject>\r
        <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
        <imageobject>\r
            <imagedata scalefit="0" fileref="media/FILENAME.png"/>\r
        </imageobject>\r
    </mediaobject>]]>\r
    </programlisting>\r
\r
        <para>In HTML output, the image will display at actual size; in PDF it will be scaled down\r
            to 75% (scale percentage set in\r
            <emphasis>~/stylesheets/sitka_fo_graphics.xsl</emphasis>). </para>\r
    </simplesect>\r
\r
\r
    <simplesect>\r
        <title>Images wider than 900px</title>\r
        <para>If the source image is wider than 900px use the following code</para>\r
        <programlisting><![CDATA[ \r
    <mediaobject>\r
        <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
        <imageobject>\r
            <imagedata width="100%" scalefit="1" fileref="media/FILENAME.png"/>\r
        </imageobject>\r
    </mediaobject>]]>\r
        </programlisting>\r
\r
        <para>In HTML the image will scale down to 900px width\r
                (<emphasis>default.image.width</emphasis> setting in\r
                <emphasis>~/stylesheets/sitka_xhtml.xsl</emphasis>). In PDF it will scale down to\r
            page width. </para>\r
\r
        <tip>\r
            <para>Wrap the <emphasis>mediaobject</emphasis> tag in a <emphasis>para</emphasis> to\r
                add a small space between the image and preceding content.</para>\r
        </tip>\r
    </simplesect>\r
\r
    <simplesect>\r
        <title>Keeping image and text together</title>\r
        <para>Content wrapped in any formal or informal object (eg <emphasis>informalfigure,\r
                formalfigure, informalexample, formalexample</emphasis>) is kept together on the\r
            same page in pdf output. Use <emphasis>informalfigure</emphasis> to keep an image with\r
            associated text, as in this example of a <emphasis>step</emphasis>:.</para>\r
        <programlisting><![CDATA[ \r
    <step>   \r
       <informalfigure>\r
          <para>STEP TEXT HERE</para>\r
          <para>\r
             <mediaobject>\r
                <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
                <imageobject>\r
                   <imagedata width="100%" scalefit="1" fileref="media/FILENAME.png"/>\r
                </imageobject>\r
             </mediaobject>\r
          </para>\r
       </informalfigure>\r
    </step>]]>\r
        </programlisting>\r
\r
        \r
\r
    </simplesect>\r
\r
\r
\r
</chapter>\r