Changeset 3348

Timestamp:

May 16, 2007, 2:36:19 PM (16 years ago)

Author:

Nicklas Nordborg

Message:

Updated documentation about how to add screenshots

Location:

trunk/doc/src/docbook

Files:

• developerdoc/write_docbook_doc.xml (modified) (3 diffs)
• userdoc/webclient.xml (modified) (7 diffs)

trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml

@@ -897 +897 @@
               <imageobject>
                 <imagedata 
-                  contentwidth="7cm" 
-                  width="7cm" 
+                  scalefit="1" 
+                  width="100%"
                   fileref="figures/menuchoice.png" format="PNG" 
                 />
@@ -932 +932 @@
         Images and figures are normally implemented like the following example. The
         image-file must be located in
-        <filename class="directory">doc/src/docbook/figures</filename>
-        ,otherwise the image won't be visible in the generated output files.
+        <filename class="directory">doc/src/docbook/figures</filename>,
+        otherwise the image won't be visible in the generated output files.
       </para>
       <warning>
         <para>
-          Images in the pdf-output are, unlike images in html-output, not scaled and can
-          therefore be out of proportion in the document. Avoid this by e.g. setting the
-          attributes
-          <sgmltag class="attribute">contentwidth</sgmltag>
-          and
-          <sgmltag class="attribute">width</sgmltag>
-          in
-          <sgmltag>imagedata</sgmltag>
-          to appropriate values.
+          When using images in docbook you will always have problems with scaling.
+          Since we are generating output for both HTML and PDF it is even worse.
+          What we have found to work is this:
+          
+          <itemizedlist>
+          <listitem>
+            <para>
+            Scaling in HTML has been disabled. The images will always be the 
+            same size as they actually are. Please, don't make the screenshots
+            too wide!
+            </para>
+          </listitem>
+          
+          <listitem>
+            <para>
+            For small images, less than the width of the PDF page,
+            do not specify scaling factors or widths. We have configured PDF to
+            use 96dpi instead of 72dpi, so the images will appear almost
+            exactly as they do in the HTML version.
+            </para>
+          </listitem>
+          
+          <listitem>
+            <para>
+            Images that are wider than the PDF page will be clipped. To 
+            prevent this you must add the following attributes to the
+            <sgmltag class="starttag">imagedata</sgmltag> tag:
+            <code>scalefit="1" width="100%"</code>
+            </para>
+          </listitem>
+          
+          <listitem>
+            <para>
+            If you still need to scale the image differently in the PDF use
+            the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag>
+            attributes.
+            </para>
+          </listitem>
+          </itemizedlist>
         </para>
       </warning>
@@ -951 +981 @@
         <title>Screen-shot in the documentation</title>
         <para>
-          <xref linkend="write_docbook_doc.figures.menuchoice" />
+          <xref linkend="webclient.figures.homepage" />
           is implemented with the following code
         </para>
         <programlisting>
 &lt;figure id="write_docbook_doc.figures.menuchoice"&gt;
-  &lt;title&gt;Menu choice&lt;/title&gt;
-  &lt;screenshot&gt;
-    &lt;mediaobject&gt;
-      &lt;imageobject&gt;
-        &lt;imagedata 
-          contentwidth="7cm" 
-          width="7cm" 
-          fileref="figures/menuchoice.png" format="PNG" 
-        /&gt;
-      &lt;/imageobject&gt;
-    &lt;/mediaobject&gt;
-  &lt;/screenshot&gt;
+  &lt;title&gt;The home page&lt;/title&gt;
+  &lt;screenshot&gt;
+    &lt;mediaobject&gt;
+      &lt;imageobject&gt;
+        &lt;imagedata 
+          scalefit="1"
+          width="100%"
+          fileref="figures/homapage.png" format="PNG" 
+        /&gt;
+      &lt;/imageobject&gt;
+    &lt;/mediaobject&gt;
+  &lt;/screenshot&gt;
 &lt;/figure&gt;
         </programlisting>

trunk/doc/src/docbook/userdoc/webclient.xml

@@ -107 +107 @@
           <mediaobject>
             <imageobject><imagedata fileref="figures/homepage.png" format="PNG"
-              scalefit="1" width="100%" contentdepth="100%"/></imageobject>
+              scalefit="1" width="100%"/></imageobject>
           </mediaobject>
         </screenshot>
@@ -204 +204 @@
             <inlinemediaobject>
             <imageobject><imagedata fileref="figures/refresh.gif" format="GIF" align="left"
-              scalefit="1" width="100%" contentwidth="100%"/></imageobject>
+              /></imageobject>
             </inlinemediaobject>
             Refresh page
@@ -1012 +1012 @@
             <imageobject>
               <imagedata fileref="figures/set_permissions.png" format="PNG" 
-                scalefit="1" width="100%" contentdepth="100%" />
+                scalefit="1" width="100%" />
             </imageobject>
           </mediaobject>
@@ -1193 +1193 @@
           <mediaobject>
             <imageobject><imagedata fileref="figures/listpage.png" format="PNG"
-              scalefit="1" width="100%" contentdepth="100%" /></imageobject>
+              scalefit="1" width="100%" /></imageobject>
           </mediaobject>
         </screenshot>
@@ -1369 +1369 @@
           <mediaobject>
             <imageobject>
-              <imagedata contentwidth="10cm" width="10cm"  fileref="figures/configure_columns.png" format="PNG"/>
+              <imagedata fileref="figures/configure_columns.png" format="PNG"/>
             </imageobject>
           </mediaobject>
@@ -1571 +1571 @@
             <screenshot>
               <mediaobject>
-                <imageobject><imagedata contentwidth="10cm" width="10cm" fileref="figures/save_preset.png" format="PNG" /></imageobject>
+                <imageobject><imagedata fileref="figures/save_preset.png" format="PNG" /></imageobject>
               </mediaobject>
             </screenshot>
@@ -1641 +1641 @@
             <screenshot>
               <mediaobject>
-                <imageobject><imagedata contentwidth="7cm" width="7cm" fileref="figures/manage_presets.png" format="PNG" /></imageobject>
+                <imageobject><imagedata fileref="figures/manage_presets.png" format="PNG" /></imageobject>
               </mediaobject>
             </screenshot>