os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add section on location of images. Rework examples to use <sgmltag>

Browse source 
instead of CDATA.
This commit is contained in:
Warren Block 2013-07-08 19:03:30 +00:00
parent 3f25d0e742
commit 1c8b414266
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=42194
1 changed files with 108 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

181
en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
View file

@ -1742,8 +1742,8 @@ This is the file called 'foo2'</screen>
<title>Images</title> <title>Images</title>
<important> <important>
<para>Image support in the documentation is currently <para>Image support in the documentation is somewhat
extremely experimental. The mechanisms described here are experimental. The mechanisms described here are
unlikely to change, but that is not guaranteed.</para> unlikely to change, but that is not guaranteed.</para>
<para>Installation of the <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 port is required. It is used to convert between the different
image formats. This port is <emphasis>not</emphasis> in image formats. This port is <emphasis>not</emphasis> in
the <filename role="package">textproc/docproj</filename> meta 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 <para>The best example of what follows in practice is the
<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> <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 look at the files in that directory to see how everything
hangs together. Experiment with creating different formatted hangs together. Experiment with creating different formatted
versions of the document to see how the image markup appears 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> <title>Image Formats</title>
<para>Two image formats are currently supported. Which to <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 <para>Images that are primarily vector based, such as network
diagrams, time lines, and similar, should be in 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 expected that documentation will have a mix of
<acronym>EPS</acronym> and <acronym>PNG</acronym> images. The <acronym>EPS</acronym> and <acronym>PNG</acronym> images. The
<filename>Makefile</filename>s ensure that the correct format <filename>Makefile</filename>s ensure that the correct format
image is chosen depending on the output format that you use image is chosen depending on the output format used.
for your documentation. <emphasis>Do not commit the same <emphasis>Do not commit the same
image to the repository in two different image to the repository in two different
formats</emphasis>.</para> formats</emphasis>.</para>
@ -1801,11 +1801,46 @@ This is the file called 'foo2'</screen>
</important> </important>
</sect2> </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"> <sect2 id="docbook-markup-image-markup">
<title>Image Markup</title> <title>Image Markup</title>
<para>The markup for an image is relatively simple. First, <para>Images are included as part of a <sgmltag>mediaobject</sgmltag>. The
markup a <sgmltag>mediaobject</sgmltag>. The
<sgmltag>mediaobject</sgmltag> can contain other, more <sgmltag>mediaobject</sgmltag> can contain other, more
specific objects. We are concerned with two, the specific objects. We are concerned with two, the
<sgmltag>imageobject</sgmltag> and the <sgmltag>imageobject</sgmltag> and the
@ -1814,7 +1849,7 @@ This is the file called 'foo2'</screen>
<para>Include one <sgmltag>imageobject</sgmltag>, <para>Include one <sgmltag>imageobject</sgmltag>,
and two <sgmltag>textobject</sgmltag> elements. The and two <sgmltag>textobject</sgmltag> elements. The
<sgmltag>imageobject</sgmltag> will point to the name of 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 <sgmltag>textobject</sgmltag> elements contain information
that will be presented to the user as well as, or instead of, that will be presented to the user as well as, or instead of,
the image itself.</para> the image itself.</para>
@ -1825,10 +1860,10 @@ This is the file called 'foo2'</screen>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>When the reader is viewing the documentation in <para>When the reader is viewing the documentation in
<acronym>HTML</acronym>. In this case, each image will <acronym>HTML</acronym>. In this case, each image
need associated alternate text to show the user, typically needs associated alternate text to show the user, typically
while the image is loading, or if they hover the mouse while the image is loading, or if the mouse
pointer over the image.</para> pointer is hovered over the image.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -1843,24 +1878,23 @@ This is the file called 'foo2'</screen>
<para>An example will make things easier to understand. Suppose <para>An example will make things easier to understand. Suppose
there is an image called <filename>fig1.png</filename> that is there is an image called <filename>fig1.png</filename> that is
to be included in the document. This image is of a rectangle to be included in the document. This image is of a rectangle
with an A inside it. The markup for this would be as with an A inside it:</para>
follows.</para>
<programlisting>&lt;mediaobject> <programlisting><sgmltag class="starttag">mediaobject</sgmltag>
&lt;imageobject> <sgmltag class="starttag">imageobject</sgmltag>
&lt;imagedata fileref="fig1"> <co id="co-image-ext"/> <sgmltag class="starttag">imagedata fileref="fig1"</sgmltag> <co id="co-image-ext"/>
&lt;/imageobject> <sgmltag class="endtag">imageobject</sgmltag>
&lt;textobject> <sgmltag class="starttag">textobject</sgmltag>
&lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal"/> <sgmltag class="starttag">literallayout class="monospaced"</sgmltag>+---------------+ <co id="co-image-literal"/>
| A | | A |
+---------------+&lt;/literallayout> +---------------+<sgmltag class="endtag">literallayout</sgmltag>
&lt;/textobject> <sgmltag class="endtag">textobject</sgmltag>
&lt;textobject> <sgmltag class="starttag">textobject</sgmltag>
&lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase"/> <sgmltag class="starttag">phrase</sgmltag>A picture<sgmltag class="endtag">phrase</sgmltag> <co id="co-image-phrase"/>
&lt;/textobject> <sgmltag class="endtag">textobject</sgmltag>
&lt;/mediaobject></programlisting> <sgmltag class="endtag">mediaobject</sgmltag></programlisting>
<calloutlist> <calloutlist>
<callout arearefs="co-image-ext"> <callout arearefs="co-image-ext">
@ -1940,7 +1974,7 @@ IMAGES+= fig3.png
<filename>chapter1/chapter.xml</filename>, <filename>chapter1/chapter.xml</filename>,
<filename>chapter2/chapter.xml</filename>, and <filename>chapter2/chapter.xml</filename>, and
<filename>chapter3/chapter.xml</filename>. If each chapter <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 those images in each chapter's subdirectory
(<filename>chapter1/</filename>, (<filename>chapter1/</filename>,
<filename>chapter2/</filename>, and <filename>chapter2/</filename>, and
@ -1958,14 +1992,14 @@ IMAGES+= fig3.png
<filename>chapter1/chapter.xml</filename> should <filename>chapter1/chapter.xml</filename> should
contain:</para> contain:</para>
<programlisting>&lt;mediaobject> <programlisting><sgmltag class="starttag">mediaobject</sgmltag>
&lt;imageobject> <sgmltag class="starttag">imageobject</sgmltag>
&lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/> <sgmltag class="emptytag">imagedata fileref="chapter1/fig1"</sgmltag> <co id="co-image-dir"/>
&lt;/imageobject> <sgmltag class="endtag">imageobject</sgmltag>
&hellip; &hellip;
&lt;/mediaobject></programlisting> <sgmltag class="endtag">mediaobject</sgmltag></programlisting>
<calloutlist> <calloutlist>
<callout arearefs="co-image-dir"> <callout arearefs="co-image-dir">
@ -2011,18 +2045,18 @@ IMAGES= chapter1/fig1.png
<title><literal>id</literal> on Chapters and <title><literal>id</literal> on Chapters and
Sections</title> Sections</title>
<programlisting><![CDATA[<chapter id="introduction"> <programlisting><sgmltag class="starttag">chapter id="introduction"</sgmltag>
<title>Introduction</title> <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag>
<para>This is the introduction. It contains a subsection, <sgmltag class="starttag">para</sgmltag>This is the introduction. It contains a subsection,
which is identified as well.</para> which is identified as well.<sgmltag class="endtag">para</sgmltag>
<sect1 id="introduction-moredetails"> <sgmltag class="starttag">sect1 id="introduction-moredetails"</sgmltag>
<title>More Details</title> <sgmltag class="starttag">title</sgmltag>More Details<sgmltag class="endtag">title</sgmltag>
<para>This is a subsection.</para> <sgmltag class="starttag">para</sgmltag>This is a subsection.<sgmltag class="endtag">para</sgmltag>
</sect1> <sgmltag class="endtag">sect1</sgmltag>
</chapter>]]></programlisting> <sgmltag class="endtag">chapter</sgmltag></programlisting>
</example> </example>
<para>Use descriptive values for <literal>id</literal> names. <para>Use descriptive values for <literal>id</literal> names.
@ -2043,9 +2077,9 @@ IMAGES= chapter1/fig1.png
<example> <example>
<title><sgmltag>anchor</sgmltag></title> <title><sgmltag>anchor</sgmltag></title>
<programlisting><![CDATA[<para>This paragraph has an embedded <programlisting><sgmltag class="starttag">para</sgmltag>This paragraph has an embedded
<anchor id="para1">link target in it. It will not <sgmltag class="emptytag">anchor id="para1"</sgmltag>link target in it. It will not
show up in the document.</para>]]></programlisting> show up in the document.<sgmltag class="endtag">para</sgmltag></programlisting>
</example> </example>
</sect2> </sect2>
@ -2066,11 +2100,11 @@ IMAGES= chapter1/fig1.png
document that includes the <literal>id</literal> document that includes the <literal>id</literal>
example shown above:</para> example shown above:</para>
<programlisting><![CDATA[<para>More information can be found <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found
in <xref linkend="introduction"/>.</para> in <sgmltag class="emptytag">xref linkend="introduction"</sgmltag>.<sgmltag class="endtag">para</sgmltag>
<para>More specific information can be found <sgmltag class="starttag">para</sgmltag>More specific information can be found
in <xref linkend="introduction-moredetails"/>.</para>]]></programlisting> in <sgmltag class="emptytag">xref linkend="introduction-moredetails"</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>The link text will be generated automatically, looking <para>The link text will be generated automatically, looking
like (<emphasis>emphasized</emphasis> text indicates the like (<emphasis>emphasized</emphasis> text indicates the
@ -2129,11 +2163,12 @@ IMAGES= chapter1/fig1.png
document that includes the <literal>id</literal> document that includes the <literal>id</literal>
example.</para> example.</para>
<programlisting><![CDATA[<para>More information can be found in the <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found in the
<link linkend="introduction">sample introduction</link>.</para> <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 <sgmltag class="starttag">para</sgmltag>More specific information can be found in the
<link linkend="introduction-moredetails">sample introduction with more details</link> section.</para>]]></programlisting> <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 <para>This output will be generated
(<emphasis>emphasized</emphasis> text is used to show the (<emphasis>emphasized</emphasis> text is used to show the
@ -2181,12 +2216,12 @@ IMAGES= chapter1/fig1.png
<para>Usage for book links:</para> <para>Usage for book links:</para>
<programlisting><![CDATA[<para>Read the <ulink <programlisting><sgmltag class="starttag">para</sgmltag>Read the <sgmltag class="starttag">ulink
url="&url.books.handbook;/svn.html#svn-intro">SVN url="&amp;url.books.handbook;/svn.html#svn-intro"</sgmltag>SVN
introduction</ulink>, then pick the nearest mirror from introduction<sgmltag class="endtag">ulink</sgmltag>, then pick the nearest mirror from
the list of <ulink the list of <sgmltag class="starttag">ulink
url="&url.books.handbook;/subversion-mirrors.html">Subversion url="&amp;url.books.handbook;/subversion-mirrors.html"</sgmltag>Subversion
mirror sites</ulink>.</para>]]></programlisting> mirror sites<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endag">para</sgmltag></programlisting>
<para>Appearance:</para> <para>Appearance:</para>
@ -2199,9 +2234,10 @@ IMAGES= chapter1/fig1.png
<para>Usage for article links:</para> <para>Usage for article links:</para>
<programlisting><![CDATA[<para>Read this <ulink url="&url.articles.bsdl-gpl;">article <programlisting><sgmltag class="starttag">para</sgmltag>Read this
about the BSD license</ulink>, or just the <ulink <sgmltag class="starttag">ulink url="&amp;url.articles.bsdl-gpl;"</sgmltag>article
url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>]]></programlisting> about the BSD license<sgmltag class="endtag">ulink</sgmltag>, or just the
<sgmltag class="starttag">ulink url="&amp;url.articles.bsdl-gpl;#intro"</sgmltag>introduction<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para> <para>Appearance:</para>
@ -2215,9 +2251,8 @@ IMAGES= chapter1/fig1.png
<para>Usage:</para> <para>Usage:</para>
<programlisting><![CDATA[<para>Of course, you could stop reading this document and <programlisting><sgmltag class="starttag">para</sgmltag>Of course, you could stop reading this document and go to the
go to the <ulink url="&url.base;/index.html">FreeBSD <sgmltag class="starttag">ulink url="&amp;url.base;/index.html"</sgmltag>FreeBSD home page<sgmltag class="endtag">ulink</sgmltag> instead.<sgmltag class="endtag">para</sgmltag></programlisting>
home page</ulink> instead.</para>]]></programlisting>
<para>Appearance:</para> <para>Appearance:</para>
@ -2232,10 +2267,10 @@ IMAGES= chapter1/fig1.png
<para>Usage:</para> <para>Usage:</para>
<programlisting><![CDATA[<para>Wikipedia has an excellent reference on <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on
<ulink <sgmltag class="starttag">ulink
url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag>GUID
Partition Tables</ulink>.</para>]]></programlisting> Partition Tables<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para> <para>Appearance:</para>
@ -2247,9 +2282,9 @@ IMAGES= chapter1/fig1.png
<para>The link text can be omitted to show the actual <para>The link text can be omitted to show the actual
URL:</para> URL:</para>
<programlisting><![CDATA[<para>Wikipedia has an excellent reference on <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on
GUID Partition Tables: <ulink GUID Partition Tables: <sgmltag class="starttag">ulink
url="http://en.wikipedia.org/wiki/GUID_Partition_Table"></ulink>.</para>]]></programlisting> url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag><sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para> <para>Appearance:</para>