You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
370 lines
18 KiB
XML
370 lines
18 KiB
XML
<!--
|
|
Copyright (c) 2016 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_examples">
|
|
|
|
<!-- Chapter Title goes here. -->
|
|
<title>Documentation examples</title>
|
|
|
|
|
|
<section>
|
|
<title>Section Title goes here</title>
|
|
<para>This Section covers something of interest to a limited number of people and shows a 1st level section</para>
|
|
|
|
<section xml:id="list_example_label">
|
|
<title>Example Itemized List</title>
|
|
<para>
|
|
Here is an example of an itemized list</para>
|
|
<itemizedlist>
|
|
<title>A list title is completely optional</title>
|
|
<listitem>
|
|
<para>
|
|
Item you don't care about</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Perhaps you'd like a sub-list</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Oooh, here's about another</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Item you might care about </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Item you do care about </para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Example ordered list</title>
|
|
<para>
|
|
All good documents need ordered lists.</para>
|
|
<orderedlist>
|
|
<title>Another purely optional title</title>
|
|
<listitem>
|
|
<para>First item</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Second item</para>
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>first indented item</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para> second indented item</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Third item</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
<section>
|
|
<title>Example variable list</title>
|
|
<para>
|
|
One of my favorite list types for formating items with definitions is called a variablelist.
|
|
Here is an example with an embedded variablelist.</para>
|
|
<variablelist>
|
|
<varlistentry><term>Kirk</term><listitem><para>Captain</para></listitem></varlistentry>
|
|
<varlistentry><term>Crew</term><listitem><para>Members</para>
|
|
<variablelist spacing='compact'>
|
|
<varlistentry><term>Scotty</term><listitem><para>Engineering</para></listitem></varlistentry>
|
|
<varlistentry><term>McCoy</term><listitem><para>Doctor</para></listitem></varlistentry>
|
|
<varlistentry><term>Spock</term><listitem><para>Science Officer</para></listitem></varlistentry>
|
|
</variablelist>
|
|
</listitem></varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example figure with embedded graphic</title>
|
|
<para>
|
|
Here is how you embed a graphic.</para>
|
|
<figure pgwide="1" xml:id="figure_label">
|
|
<title>Example figure</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/example_graphic.bmp" format="BMP" scalefit="1" width="100%" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
<note><para>Raw images such as the bitmap (bmp) file above may become blurry as they are scaled.
|
|
Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best.</para></note>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example table</title>
|
|
<para>Of course all good documents need tables. Here's how you build a basic table.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="table_label">
|
|
<title>Example Table Title</title>
|
|
<tgroup cols="4">
|
|
<colspec colname="c1" colwidth="25*" />
|
|
<colspec colname="c2" colwidth="25*" />
|
|
<colspec colname="c3" colwidth="25*" />
|
|
<colspec colname="c4" colwidth="25*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">1st Column Heading</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">2nd Column Heading</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">3rd Column Heading</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">4th Column Heading</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>Yes</para>
|
|
</entry>
|
|
<entry>
|
|
<para><phrase role="color:red">Red</phrase></para>
|
|
<para><phrase role="color:green">Green</phrase></para>
|
|
<para><phrase role="color:blue">Blue</phrase></para>
|
|
<para><phrase role="color:#FFBF00">Custom (Amber)</phrase></para>
|
|
</entry>
|
|
<entry>
|
|
<para>MAIN_Junk</para>
|
|
</entry>
|
|
<entry>
|
|
<para>More_Junk</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry namest='c1' nameend='c3' align='center'>
|
|
<para>merged cells horizontal</para>
|
|
</entry>
|
|
<entry>
|
|
<para>cell_stuff</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows='1'>
|
|
<para>Merge cells vertical</para>
|
|
</entry>
|
|
<entry>
|
|
<para>filler</para>
|
|
</entry>
|
|
<entry namest='c3' nameend='c4' morerows='1' align='center'>
|
|
<para>merge cells both ways</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>filler 2</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>How about we put a list in the table cell</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>item 1</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>item 2</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>item 2</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
<entry>
|
|
<para>Another Cell</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Yet Another Cell</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Finally the last cell</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<?dbhtml bgcolor="#EEEEEE" ?><?dbfo bgcolor="#EEEEEE" ?>
|
|
<entry>
|
|
<para>This Row</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Has </para>
|
|
</entry>
|
|
<entry>
|
|
<para>background </para>
|
|
</entry>
|
|
<entry>
|
|
<para>color</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Eenie</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Meenie </para>
|
|
</entry>
|
|
<entry>
|
|
<para>Meinie </para>
|
|
</entry>
|
|
<entry>
|
|
<?dbhtml bgcolor="#EEEEEE" ?><?dbfo bgcolor="#EEEEEE" ?>
|
|
<para>Entry with background color</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</section>
|
|
<section>
|
|
<title>Example of crossreferences and footnotes</title>
|
|
<para>To reference another section or table is pretty easy. For example: see <xref linkend="table_label" /> for how tables look.</para>
|
|
<para>Lists are shown in <xref linkend="list_example_label" /> and if you need to make a footnote
|
|
<footnote xml:id="foot_id"><para>The footnote text goes here and can reference something like <xref linkend="figure_label" /> for additional explanation.</para></footnote>
|
|
For clarification that is easy. Of course you might want an additional reference to the footnote <footnoteref linkend="foot_id"/> which can also be done easily.</para>
|
|
<para>Lastly you probably want to mark text by making it <emphasis>italic text example</emphasis> or <emphasis role='bold'>Bold Text Example</emphasis>.</para>
|
|
</section>
|
|
<section>
|
|
<title>Example of code citations and user input</title>
|
|
<para>When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
|
|
<screen><prompt>$ </prompt><userinput>echo "Hello world"</userinput>
|
|
Hello world
|
|
<prompt>$ </prompt></screen>
|
|
</para>
|
|
<para>Docbook also allows for formatting and display of common languages, allowing for whitespace
|
|
and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:<programlisting linenumbering="numbered"><![CDATA[#include<stdio.h>
|
|
main()
|
|
{
|
|
printf("Hello world\n");
|
|
}]]></programlisting></para>
|
|
<para>If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: <literal>This is my literal
|
|
text. It ignores whitespace.</literal></para>
|
|
</section>
|
|
<section>
|
|
<title>Example of special characters in text</title>
|
|
<para>Sometimes in text you need special characters. These can be provided using their UNICODE values such as ≠ (&#8800),
|
|
Ω (&#x2126), and ∆ (&#8710;).
|
|
These can be "coded" using the form <literal>&#</literal><emphasis>ddddd</emphasis><literal>;</literal> where <emphasis>ddddd</emphasis> is
|
|
the up to five digit decimal representation of the character. The form <literal>&#x</literal><emphasis>hhhh</emphasis><literal>;</literal> where
|
|
<emphasis>hhhh</emphasis> is the up to 4 digit hexidecimal representation of the character.</para>
|
|
<para>This formatting works well as long as the symbol to which you are referring is contained in the font set
|
|
used for the document -- Arimo for standard text and Cousine for monospace. If when building a document, you see a message like
|
|
"WARNING, Glyph...not available in font 'Arimo',"
|
|
see <xref linkend="symbol_font" /> in <xref linkend="docbook_extensions" /> for details on using the provided symbol fonts explicitly.</para>
|
|
</section>
|
|
|
|
<xi:include href="sec_example.xml"/>
|
|
|
|
<section xml:id="docbook_extensions">
|
|
<title>Examples of OpenPOWER Foundation Docbook extensions</title>
|
|
|
|
<para>The OpenPOWER Foundation Maven Plugin supports a number of extensions that are not pure Docbook. These are:</para>
|
|
|
|
<simplesect>
|
|
<title>Setting text color explicitly</title>
|
|
|
|
<para>Text color can be controlled using <literal><phrase role="color:</literal><emphasis>color_name</emphasis><literal>"></literal>
|
|
tag where <emphasis>color_name</emphasis> contains the color setting. For example, this
|
|
text:<programlisting><![CDATA[<para role="color:red">A red sentence contains a <phrase role="color:blue">blue</phrase> word.</para>]]></programlisting> produces this sentence:</para>
|
|
<para role="color:red">A red sentence contains a <phrase role="color:blue">blue</phrase> word.</para>
|
|
<para>Valid colors include either a keyword color name or a numerical RGB specification. Keyword names are common with the HTML 4 specificiation:
|
|
<literal>aqua</literal>, <literal>black</literal>, <literal>blue</literal>, <literal>fuchsia</literal>, <literal>gray</literal>,
|
|
<literal>green</literal>, <literal>lime</literal>, <literal>maroon</literal>, <literal>navy</literal>, <literal>olive</literal>,
|
|
<literal>purple</literal>, <literal>red</literal>, <literal>silver</literal>, <literal>teal</literal>, <literal>white</literal>,
|
|
and <literal>yellow</literal>. Additionally, RGB values can be <literal>#nnnnnn</literal> where <literal>nnnnnn</literal> is a hexidecimal color value or
|
|
<literal>rgb(n1, n2, n3)</literal> where <literal>n1</literal>, <literal>n2</literal>, and <literal>n3</literal> are integers 0-255.</para>
|
|
<para>This tag has also been implemented on the following tags: <literal><thead></literal>,
|
|
<literal><tbody></literal>, and <literal><tfoot></literal>.</para>
|
|
<warning><para>This parameter should only be used for tags listed above.</para></warning>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Inserting line breaks</title>
|
|
<para>Line breaks can be introduced using <literal><?linebreak?></literal> tags. For example, this
|
|
text:<programlisting><![CDATA[<para>A line break <?linebreak?> in the middle of text</para>]]></programlisting> produces this sentence:</para>
|
|
<para>A line break <?linebreak?> in the middle of text</para>
|
|
<para>This tag becomes useful in table text spacing.</para>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Inserting page breaks</title>
|
|
<para>Page breaks can be introduced using <literal><?hard-pagebreak?></literal> tags. For example, this
|
|
text:<programlisting><![CDATA[<para>A page break</para> <?hard-pagebreak?> <para>Between two paragraphs</para>]]></programlisting> produces this output:</para>
|
|
<para>A page break</para> <?hard-pagebreak?> <para>Between two paragraphs</para>
|
|
<para>This tag becomes useful in placing tables on page. Placing this statement before a large table may prevent it from spanning a page.</para>
|
|
<warning><para>Because the XSL template behind the Processing Instruction generates
|
|
a <programlisting><![CDATA[<fo:block break-after='page'/>]]></programlisting> in
|
|
the book FO output, this instruction should be used in the outer most blocks of a section to work effectively. Use inside lists and other structural
|
|
components may result in the text after the break being dropped. <emphasis role="bold">User beware!</emphasis>.</para></warning>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Varying the font size</title>
|
|
<para>Font sizes can also be set using the
|
|
<literal><phrase role="font-size:</literal><emphasis>size</emphasis><literal>"></literal>
|
|
tag where <emphasis>size</emphasis> contains a size value such as "6pt" or "50%" or "1.5em".</para>
|
|
<para>For example, a paragraph can be made to be 6 point as follows:<programlisting><![CDATA[<para>A sentence that contains some <phrase role="font-size:6pt">6pt font</phrase>,
|
|
<phrase role="font-size:50%">50% font</phrase>, and
|
|
<phrase role="font-size:1.5em">1.5em font</phrase> in it.</para>]]></programlisting> produces this output:</para>
|
|
<para>A sentence that contains some <phrase role="font-size:6pt">6pt font</phrase>,
|
|
<phrase role="font-size:50%">50% font</phrase>, and <phrase role="font-size:1.5em">1.5em font</phrase> in it.</para>
|
|
<para>This tag has also been implemented on the following tags: <literal><para></literal>,
|
|
<literal><thead></literal>, <literal><tbody></literal>, and <literal><tfoot></literal>.</para>
|
|
<warning><para>This parameter should only be used for tags listed above.</para></warning>
|
|
</simplesect>
|
|
|
|
<simplesect xml:id="symbol_font">
|
|
<title>Using additional symbols</title>
|
|
<para>If you find that the Arimo and Cousine fonts do not contain the special symbol you need
|
|
for your document, you may use the additional symbol font provided for document (STIX Two Math).
|
|
Due to an unimplemented feature in the Apach FO Processor, selection of this
|
|
font needs to be explicitly performed using the
|
|
<literal><symbol role="symbolfont"></literal> wrapper around your symbol value.</para>
|
|
|
|
<para>For example, the symbol coding of <programlisting><![CDATA[⨁]]></programlisting> should produce
|
|
a circle with a cross in here "⨁", but instead creates a "Glyph...not available in font 'Arimo'" error
|
|
on document build and the PDF renders as a "#".</para>
|
|
|
|
<para>Re-coding this to use <programlisting><![CDATA[<symbol role="symbolfont">⨁</symbol>]]></programlisting> produces
|
|
the correct symbole here "<symbol role="symbolfont">⨁</symbol>".</para>
|
|
<para>If this still does not provide the symbol you expected, double check the code and the font maps found at
|
|
<link xlink:href="http://www.stixfonts.org/charactertable.html">http://www.stixfonts.org/charactertable.html</link>.</para>
|
|
</simplesect>
|
|
</section>
|
|
|
|
</section>
|
|
</chapter>
|