openstack/openstack-manuals
Code Issues Proposed changes

Provide a conventions section

Browse Source 
Detail conventions used in all books. First and only conventions detailed
for now: prompts and admonitions.

Use a common ch_preface.xml for all books.

Change-Id: I7ed5c8b63ed9277dfdbccc55eb76e97e364118c8
This commit is contained in:
Gauvain Pocentek 2014-03-10 21:08:31 +01:00 committed by Lana Brindley
parent 25c95b418b
commit 552ed9399a
12 changed files with 62 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/admin-guide-cloud/bk-admin-guide-cloud.xml
View File

@ -115,6 +115,7 @@
</revhistory>
</info>
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
<xi:include href="../common/ch_preface.xml"/>
<xi:include href="../common/ch_getstart.xml"/>
<xi:include href="ch_identity_mgmt.xml"/>
<xi:include href="ch_dashboard.xml"/>

2
doc/cli-reference/bk-cli-reference.xml
View File

@ -55,7 +55,7 @@
</revhistory>
</info>
<xi:include href="ch_preface.xml"/>
<xi:include href="../common/ch_preface.xml"/>
<xi:include href="ch_cli.xml"/>
<xi:include href="../common/ch_cli_cinder_commands.xml"/>
<xi:include href="../common/ch_cli_nova_commands.xml"/>

3
doc/cli-reference/ch_preface.xml → doc/common/ch_preface.xml
View File

@ -10,5 +10,6 @@
<title>Preface</title>
<?dbhtml stop-chunking?>
<xi:include href="../common/section_dochistory.xml"/>
<xi:include href="section_conventions.xml"/>
<xi:include href="section_dochistory.xml"/>
</preface>

1
doc/common/ch_using_openstack_overview.xml
View File

@ -49,5 +49,6 @@
<para>To use the OpenStack APIs, it helps to be familiar with
HTTP/1.1, RESTful web services, the OpenStack services, and
JSON or XML data serialization formats.</para>
<xi:include href="../common/section_conventions.xml"/>
<xi:include href="../common/section_dochistory.xml"/>
</preface>

53
doc/common/section_conventions.xml Normal file
View File

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_conventions">
<?dbhtml stop-chunking?>
<title>Conventions</title>
<para>
The OpenStack documentation uses several typesetting conventions:
</para>
<simplesect xml:id="conventions-admonitions">
<title>Admonitions</title>
<para>
Admonitions take three forms:
</para>
<note>
<para>
This is a note. The information in a note is usually in the form
of a handy tip or reminder.
</para>
</note>
<important>
<para>
This is important. The information in an important admonition is
something you must be aware of before moving on.
</para>
</important>
<warning>
<para>
This is a warning. The information in warnings is critical.
Warnings provide additional information about risk of data loss or
security issues.
</para>
</warning>
</simplesect>
<simplesect xml:id="conventions-prompts">
<title>Command prompts</title>
<para>
Commands prefixed with the <literal>#</literal> prompt are to be
executed by the <literal>root</literal> user. These examples can
also be executed using the <command>sudo</command> command, if
available.
</para>
<para>
Commands prefixed with the <literal>$</literal> prompt can be
executed by any user, including <literal>root</literal>.
</para>
</simplesect>
</section>

1
doc/config-reference/ch_config-overview.xml
View File

@ -21,5 +21,6 @@
<listitem><para>OpenStack Object Storage</para></listitem>
<listitem><para>OpenStack Block Storage</para></listitem>
</itemizedlist>
<xi:include href="../common/section_conventions.xml"/>
<xi:include href="../common/section_dochistory.xml"/>
</preface>

2
doc/image-guide/bk-imageguide.xml
View File

@ -83,7 +83,7 @@
</revhistory>
</info>
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
<xi:include href="ch_preface.xml"/>
<xi:include href="../common/ch_preface.xml"/>
<xi:include href="ch_introduction.xml"/>
<xi:include href="ch_obtaining_images.xml"/>
<xi:include href="ch_openstack_images.xml"/>

14
doc/image-guide/ch_preface.xml
View File

@ -1,14 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<preface xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="ch_preface">
<title>Preface</title>
<?dbhtml stop-chunking?>
<xi:include href="../common/section_dochistory.xml"/>
</preface>

2
doc/install-guide/bk_openstackinstallguide.xml
View File

@ -181,7 +181,7 @@
<!-- Chapters are referred from the book file through these
include statements. You can add additional chapters using
these types of statements. -->
<xi:include href="ch_preface.xml"/>
<xi:include href="../common/ch_preface.xml"/>
<xi:include href="ch_overview.xml"/>
<xi:include href="ch_basics.xml"/>
<xi:include href="ch_debconf.xml"/>

14
doc/install-guide/ch_preface.xml
View File

@ -1,14 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<preface xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="ch_preface">
<title>Preface</title>
<?dbhtml stop-chunking?>
<xi:include href="../common/section_dochistory.xml"/>
</preface>

2
doc/security-guide/bk_openstack-sec-guide.xml
View File

@ -66,7 +66,7 @@
</revision>
</revhistory>
</info>
<xi:include href="ch_preface.xml"/>
<xi:include href="../common/ch_preface.xml"/>
<xi:include href="ch001_acknowledgements.xml"/>
<xi:include href="ch002_why-and-how-we-wrote-this-book.xml"/>
<xi:include href="ch004_book-introduction.xml"/>

14
doc/security-guide/ch_preface.xml
View File

@ -1,14 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<preface xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="openstack_user_guide">
<title>Preface</title>
<?dbhtml stop-chunking?>
<xi:include href="../common/section_dochistory.xml"/>
</preface>