Date: Mon, 8 Jul 2013 19:03:31 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42194 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup Message-ID: <201307081903.r68J3VG0081299@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Mon Jul 8 19:03:30 2013 New Revision: 42194 URL: http://svnweb.freebsd.org/changeset/doc/42194 Log: Add section on location of images. Rework examples to use <sgmltag> instead of CDATA. Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Mon Jul 8 18:09:56 2013 (r42193) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Mon Jul 8 19:03:30 2013 (r42194) @@ -1742,8 +1742,8 @@ This is the file called 'foo2'</screen> <title>Images</title> <important> - <para>Image support in the documentation is currently - extremely experimental. The mechanisms described here are + <para>Image support in the documentation is somewhat + experimental. The mechanisms described here are unlikely to change, but that is not guaranteed.</para> <para>Installation of the @@ -1751,11 +1751,11 @@ This is the file called 'foo2'</screen> port is required. It is used to convert between the different image formats. This port is <emphasis>not</emphasis> in the <filename role="package">textproc/docproj</filename> meta - port, it must be installed by hand.</para> + port, it must be installed separately.</para> <para>The best example of what follows in practice is the <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> - document. If the description that follows is unclear, take a + document. If the description that follows is unclear, 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 @@ -1766,7 +1766,7 @@ This is the file called 'foo2'</screen> <title>Image Formats</title> <para>Two image formats are currently supported. Which to - choose will depend on the nature of the image.</para> + use depends on the nature of the image.</para> <para>Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in @@ -1787,8 +1787,8 @@ This is the file called 'foo2'</screen> expected that documentation will have a mix of <acronym>EPS</acronym> and <acronym>PNG</acronym> images. The <filename>Makefile</filename>s ensure that the correct format - image is chosen depending on the output format that you use - for your documentation. <emphasis>Do not commit the same + image is chosen depending on the output format used. + <emphasis>Do not commit the same image to the repository in two different formats</emphasis>.</para> @@ -1801,11 +1801,46 @@ This is the file called 'foo2'</screen> </important> </sect2> + <sect2 id="docbook-markup-image-file-locations"> + <title>Image File Locations</title> + + <para>Image files can be stored in one of several + locations, depending on the document and image:</para> + + <itemizedlist> + <listitem> + <para>In the same directory as the document itself, usually + done for articles and small books that keep all their + files in a single directory.</para> + </listitem> + + <listitem> + <para>In a subdirectory of the main document. Typically + done when a large book uses separate subdirectories to + organize individual chapters.</para> + + <para>When images are stored in a subdirectory of the + main document directory, the subdirectory name must be + included in their paths in the + <filename>Makefile</filename> and the + <sgmltag>imagedata</sgmltag> element.</para> + </listitem> + + <listitem> + <para>In a subdirectory of + <filename class="directory">doc/share/images</filename>. + Images that apply to multiple translations are stored in + this upper level of the documentation file tree. + Generally, these are images that do not require + translation for use in non-English documents.</para> + </listitem> + </itemizedlist> + </sect2> + <sect2 id="docbook-markup-image-markup"> <title>Image Markup</title> - <para>The markup for an image is relatively simple. First, - markup a <sgmltag>mediaobject</sgmltag>. The + <para>Images are included as part of a <sgmltag>mediaobject</sgmltag>. The <sgmltag>mediaobject</sgmltag> can contain other, more specific objects. We are concerned with two, the <sgmltag>imageobject</sgmltag> and the @@ -1814,7 +1849,7 @@ This is the file called 'foo2'</screen> <para>Include one <sgmltag>imageobject</sgmltag>, and two <sgmltag>textobject</sgmltag> elements. The <sgmltag>imageobject</sgmltag> will point to the name of the - image file (without the extension). The + image file without the extension. The <sgmltag>textobject</sgmltag> elements contain information that will be presented to the user as well as, or instead of, the image itself.</para> @@ -1825,10 +1860,10 @@ This is the file called 'foo2'</screen> <itemizedlist> <listitem> <para>When the reader is viewing the documentation in - <acronym>HTML</acronym>. 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.</para> + <acronym>HTML</acronym>. In this case, each image + needs associated alternate text to show the user, typically + while the image is loading, or if the mouse + pointer is hovered over the image.</para> </listitem> <listitem> @@ -1843,24 +1878,23 @@ This is the file called 'foo2'</screen> <para>An example will make things easier to understand. Suppose there is an image called <filename>fig1.png</filename> 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.</para> + with an A inside it:</para> - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="fig1"> <co id="co-image-ext"/> - </imageobject> + <programlisting><sgmltag class="starttag">mediaobject</sgmltag> + <sgmltag class="starttag">imageobject</sgmltag> + <sgmltag class="starttag">imagedata fileref="fig1"</sgmltag> <co id="co-image-ext"/> + <sgmltag class="endtag">imageobject</sgmltag> - <textobject> - <literallayout class="monospaced">+---------------+ <co id="co-image-literal"/> + <sgmltag class="starttag">textobject</sgmltag> + <sgmltag class="starttag">literallayout class="monospaced"</sgmltag>+---------------+ <co id="co-image-literal"/> | A | -+---------------+</literallayout> - </textobject> ++---------------+<sgmltag class="endtag">literallayout</sgmltag> + <sgmltag class="endtag">textobject</sgmltag> - <textobject> - <phrase>A picture</phrase> <co id="co-image-phrase"/> - </textobject> -</mediaobject></programlisting> + <sgmltag class="starttag">textobject</sgmltag> + <sgmltag class="starttag">phrase</sgmltag>A picture<sgmltag class="endtag">phrase</sgmltag> <co id="co-image-phrase"/> + <sgmltag class="endtag">textobject</sgmltag> +<sgmltag class="endtag">mediaobject</sgmltag></programlisting> <calloutlist> <callout arearefs="co-image-ext"> @@ -1940,7 +1974,7 @@ IMAGES+= fig3.png <filename>chapter1/chapter.xml</filename>, <filename>chapter2/chapter.xml</filename>, and <filename>chapter3/chapter.xml</filename>. If each chapter - has images associated with it, it is suggested to place + has images associated with it, place those images in each chapter's subdirectory (<filename>chapter1/</filename>, <filename>chapter2/</filename>, and @@ -1958,14 +1992,14 @@ IMAGES+= fig3.png <filename>chapter1/chapter.xml</filename> should contain:</para> - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/> - </imageobject> + <programlisting><sgmltag class="starttag">mediaobject</sgmltag> + <sgmltag class="starttag">imageobject</sgmltag> + <sgmltag class="emptytag">imagedata fileref="chapter1/fig1"</sgmltag> <co id="co-image-dir"/> + <sgmltag class="endtag">imageobject</sgmltag> … -</mediaobject></programlisting> +<sgmltag class="endtag">mediaobject</sgmltag></programlisting> <calloutlist> <callout arearefs="co-image-dir"> @@ -2011,18 +2045,18 @@ IMAGES= chapter1/fig1.png <title><literal>id</literal> on Chapters and Sections</title> - <programlisting><![CDATA[<chapter id="introduction"> - <title>Introduction</title> + <programlisting><sgmltag class="starttag">chapter id="introduction"</sgmltag> + <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag> - <para>This is the introduction. It contains a subsection, - which is identified as well.</para> + <sgmltag class="starttag">para</sgmltag>This is the introduction. It contains a subsection, + which is identified as well.<sgmltag class="endtag">para</sgmltag> - <sect1 id="introduction-moredetails"> - <title>More Details</title> + <sgmltag class="starttag">sect1 id="introduction-moredetails"</sgmltag> + <sgmltag class="starttag">title</sgmltag>More Details<sgmltag class="endtag">title</sgmltag> - <para>This is a subsection.</para> - </sect1> -</chapter>]]></programlisting> + <sgmltag class="starttag">para</sgmltag>This is a subsection.<sgmltag class="endtag">para</sgmltag> + <sgmltag class="endtag">sect1</sgmltag> +<sgmltag class="endtag">chapter</sgmltag></programlisting> </example> <para>Use descriptive values for <literal>id</literal> names. @@ -2043,9 +2077,9 @@ IMAGES= chapter1/fig1.png <example> <title><sgmltag>anchor</sgmltag></title> - <programlisting><![CDATA[<para>This paragraph has an embedded - <anchor id="para1">link target in it. It will not - show up in the document.</para>]]></programlisting> + <programlisting><sgmltag class="starttag">para</sgmltag>This paragraph has an embedded + <sgmltag class="emptytag">anchor id="para1"</sgmltag>link target in it. It will not + show up in the document.<sgmltag class="endtag">para</sgmltag></programlisting> </example> </sect2> @@ -2066,11 +2100,11 @@ IMAGES= chapter1/fig1.png document that includes the <literal>id</literal> example shown above:</para> - <programlisting><![CDATA[<para>More information can be found - in <xref linkend="introduction"/>.</para> + <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found + in <sgmltag class="emptytag">xref linkend="introduction"</sgmltag>.<sgmltag class="endtag">para</sgmltag> -<para>More specific information can be found - in <xref linkend="introduction-moredetails"/>.</para>]]></programlisting> +<sgmltag class="starttag">para</sgmltag>More specific information can be found + in <sgmltag class="emptytag">xref linkend="introduction-moredetails"</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> <para>The link text will be generated automatically, looking like (<emphasis>emphasized</emphasis> text indicates the @@ -2129,11 +2163,12 @@ IMAGES= chapter1/fig1.png document that includes the <literal>id</literal> example.</para> - <programlisting><![CDATA[<para>More information can be found in the - <link linkend="introduction">sample introduction</link>.</para> + <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found in the + <sgmltag class="starttag">link linkend="introduction"</sgmltag>sample introduction<sgmltag class="endtag">link</sgmltag>.<sgmltag class="endtag">para</sgmltag> -<para>More specific information can be found in the - <link linkend="introduction-moredetails">sample introduction with more details</link> section.</para>]]></programlisting> +<sgmltag class="starttag">para</sgmltag>More specific information can be found in the + <sgmltag class="starttag">link linkend="introduction-moredetails"</sgmltag>sample introduction with + more details<sgmltag class="endtag">link</sgmltag> section.<sgmltag class="endtag">para</sgmltag></programlisting> <para>This output will be generated (<emphasis>emphasized</emphasis> text is used to show the @@ -2181,12 +2216,12 @@ IMAGES= chapter1/fig1.png <para>Usage for book links:</para> - <programlisting><![CDATA[<para>Read the <ulink - url="&url.books.handbook;/svn.html#svn-intro">SVN - introduction</ulink>, then pick the nearest mirror from - the list of <ulink - url="&url.books.handbook;/subversion-mirrors.html">Subversion - mirror sites</ulink>.</para>]]></programlisting> + <programlisting><sgmltag class="starttag">para</sgmltag>Read the <sgmltag class="starttag">ulink + url="&url.books.handbook;/svn.html#svn-intro"</sgmltag>SVN + introduction<sgmltag class="endtag">ulink</sgmltag>, then pick the nearest mirror from + the list of <sgmltag class="starttag">ulink + url="&url.books.handbook;/subversion-mirrors.html"</sgmltag>Subversion + mirror sites<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endag">para</sgmltag></programlisting> <para>Appearance:</para> @@ -2199,9 +2234,10 @@ IMAGES= chapter1/fig1.png <para>Usage for article links:</para> - <programlisting><![CDATA[<para>Read this <ulink url="&url.articles.bsdl-gpl;">article - about the BSD license</ulink>, or just the <ulink - url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>]]></programlisting> + <programlisting><sgmltag class="starttag">para</sgmltag>Read this + <sgmltag class="starttag">ulink url="&url.articles.bsdl-gpl;"</sgmltag>article + about the BSD license<sgmltag class="endtag">ulink</sgmltag>, or just the + <sgmltag class="starttag">ulink url="&url.articles.bsdl-gpl;#intro"</sgmltag>introduction<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> <para>Appearance:</para> @@ -2215,9 +2251,8 @@ IMAGES= chapter1/fig1.png <para>Usage:</para> - <programlisting><![CDATA[<para>Of course, you could stop reading this document and - go to the <ulink url="&url.base;/index.html">FreeBSD - home page</ulink> instead.</para>]]></programlisting> + <programlisting><sgmltag class="starttag">para</sgmltag>Of course, you could stop reading this document and go to the + <sgmltag class="starttag">ulink url="&url.base;/index.html"</sgmltag>FreeBSD home page<sgmltag class="endtag">ulink</sgmltag> instead.<sgmltag class="endtag">para</sgmltag></programlisting> <para>Appearance:</para> @@ -2232,10 +2267,10 @@ IMAGES= chapter1/fig1.png <para>Usage:</para> - <programlisting><![CDATA[<para>Wikipedia has an excellent reference on - <ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Tables</ulink>.</para>]]></programlisting> + <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on + <sgmltag class="starttag">ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag>GUID + Partition Tables<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> <para>Appearance:</para> @@ -2247,9 +2282,9 @@ IMAGES= chapter1/fig1.png <para>The link text can be omitted to show the actual URL:</para> - <programlisting><![CDATA[<para>Wikipedia has an excellent reference on - GUID Partition Tables: <ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"></ulink>.</para>]]></programlisting>; + <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on + GUID Partition Tables: <sgmltag class="starttag">ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag><sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> <para>Appearance:</para>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307081903.r68J3VG0081299>