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.
221 lines
8.0 KiB
XML
221 lines
8.0 KiB
XML
7 years ago
|
<!--
|
||
|
|
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>
|