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.
263 lines
11 KiB
XML
263 lines
11 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>
|
|
<listitem>
|
|
<para>
|
|
Item you don't care about</para>
|
|
</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>
|
|
<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 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="red">Red</phrase></para>
|
|
<para><phrase role="green">Green</phrase></para>
|
|
<para><phrase role="blue">Blue</phrase></para>
|
|
<para><phrase role="#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>
|
|
</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>
|
|
|
|
<xi:include href="sec_example.xml"/>
|
|
|
|
<section>
|
|
<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> tags. For example, this
|
|
text:<programlisting><![CDATA[<para><phrase role="red">A red sentence.</phrase></para>]]></programlisting> produces this sentence:</para>
|
|
<para><phrase role="red">A red sentence.</phrase></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 intergers 0-255.</para>
|
|
</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 sentence:</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>
|
|
</section>
|
|
|
|
</section>
|
|
</chapter>
|