You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

220 lines
8.0 KiB

<!--
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>
</section>
</chapter>