08fcd01d76bb3388dd46ae56166a0ec71cd6503b
[sitka/doc/style.git] / style / style-image.xml
1 <?xml version="1.0" encoding="utf-8"?>\r
2 <chapter xml:id="style-image" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
4 \r
5     <info>\r
6         <title>Image Formatting</title>\r
7     </info>\r
8 \r
9     <itemizedlist>\r
10         <listitem>\r
11             <para>.png is the preferred image format, though .jpg from legacy conversions are\r
12                 acceptable</para>\r
13         </listitem>\r
14         <listitem>\r
15             <para>Images are stored in <emphasis>media</emphasis> directories for each <markup\r
16                     linkend="part">part</markup>.</para>\r
17         </listitem>\r
18         <listitem>\r
19             <para>Images up to 900px wide can be displayed without resizing. Images larger than\r
20                 900px are scaled down with the <emphasis>scalefit="1"</emphasis> attribute as shown\r
21                 below.</para>\r
22         </listitem>\r
23         <listitem>\r
24             <para>When scaling DocBook uses both the size (pixels) and resolution (dpi or pixels/in)\r
25                 of image files. Source images should be at 96dpi, a default chosen to match legacy\r
26                 images. 96dpi seems to be standard in FullShot; if using Gimp change the default for\r
27                 new images from 72 pixels/in to 96 pixels/in under <menuchoice>\r
28                     <guimenu>File</guimenu>\r
29                     <guisubmenu>Preferences</guisubmenu>\r
30                     <guimenuitem>Default Image</guimenuitem>\r
31                 </menuchoice></para>\r
32         </listitem>\r
33 <listitem>\r
34             <para>Add Capture Effects - <emphasis>Drop Shadow</emphasis> (Direction=Lower Right, Distance=5, Size=5)</para>\r
35         </listitem>\r
36 <para>Add Capture Effects - <emphasis>Stroke/Frame<emphasis> (Width=1, Colour=000000)</para>\r
37         </listitem>\r
38 \r
39     </itemizedlist>\r
40 \r
41     <simplesect>\r
42         <title>Images 900px wide or less</title>\r
43         <para>If the source image is 900px wide or less use the following code</para>\r
44         <programlisting><![CDATA[ \r
45     <mediaobject>\r
46         <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
47         <imageobject>\r
48             <imagedata scalefit="0" fileref="media/FILENAME.png"/>\r
49         </imageobject>\r
50     </mediaobject>]]>\r
51     </programlisting>\r
52 \r
53         <para>In HTML output, the image will display at actual size; in PDF it will be scaled down\r
54             to 75% (scale percentage set in\r
55             <emphasis>~/stylesheets/sitka_fo_graphics.xsl</emphasis>). </para>\r
56     </simplesect>\r
57 \r
58 \r
59     <simplesect>\r
60         <title>Images wider than 900px</title>\r
61         <para>If the source image is wider than 900px use the following code</para>\r
62         <programlisting><![CDATA[ \r
63     <mediaobject>\r
64         <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
65         <imageobject>\r
66             <imagedata width="100%" scalefit="1" fileref="media/FILENAME.png"/>\r
67         </imageobject>\r
68     </mediaobject>]]>\r
69         </programlisting>\r
70 \r
71         <para>In HTML the image will scale down to 900px width\r
72                 (<emphasis>default.image.width</emphasis> setting in\r
73                 <emphasis>~/stylesheets/sitka_xhtml.xsl</emphasis>). In PDF it will scale down to\r
74             page width. </para>\r
75 \r
76         <tip>\r
77             <para>Wrap the <emphasis>mediaobject</emphasis> tag in a <emphasis>para</emphasis> to\r
78                 add a small space between the image and preceding content.</para>\r
79         </tip>\r
80     </simplesect>\r
81 \r
82     <simplesect>\r
83         <title>Keeping image and text together</title>\r
84         <para>Content wrapped in any formal or informal object (eg <emphasis>informalfigure,\r
85                 formalfigure, informalexample, formalexample</emphasis>) is kept together on the\r
86             same page in pdf output. Use <emphasis>informalfigure</emphasis> to keep an image with\r
87             associated text, as in this example of a <emphasis>step</emphasis>:.</para>\r
88         <programlisting><![CDATA[ \r
89     <step>   \r
90        <informalfigure>\r
91           <para>STEP TEXT HERE</para>\r
92           <para>\r
93              <mediaobject>\r
94                 <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
95                 <imageobject>\r
96                    <imagedata width="100%" scalefit="1" fileref="media/FILENAME.png"/>\r
97                 </imageobject>\r
98              </mediaobject>\r
99           </para>\r
100        </informalfigure>\r
101     </step>]]>\r
102         </programlisting>\r
103 \r
104         \r
105 \r
106     </simplesect>\r
107 \r
108 \r
109 \r
110 </chapter>\r