Add section on location of images. Rework examples to use <sgmltag>
instead of CDATA.
This commit is contained in:
Warren Block
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
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue