[documentation-guide] Fix formatting, add section id's.
rkratky
rkratky at fedoraproject.org
Fri Aug 8 14:45:38 UTC 2014
commit 9d22d58cce615de19226c92d14c51183cc8e6995
Author: Robert Krátký <rkratky at redhat.com>
Date: Fri Aug 8 16:00:09 2014 +0200
Fix formatting, add section id's.
en-US/docbook.xml | 255 ++++++++++++++++++++++-------------------------------
1 files changed, 106 insertions(+), 149 deletions(-)
---
diff --git a/en-US/docbook.xml b/en-US/docbook.xml
index 2d675c5..8bc4d72 100644
--- a/en-US/docbook.xml
+++ b/en-US/docbook.xml
@@ -5,155 +5,112 @@
]>
<chapter id="chap-documentation_guide-docbook">
- <title>Brief Introduction to DocBook</title>
- <para>
- This chapter will give you a brief introduction to DocBook.
- </para>
- <section>
- <title>Why DocBook?</title>
- <para>
- DocBook has many features which make it suitable for
- documentation in Fedora and other projects.
- </para>
- <section>
- <title>DocBook as an XML Markup Language</title>
- <para>
- DocBook is an implementation of
- <firstterm>Extensible Markup Language (XML)
- </firstterm>. XML gives DocBook powerful
- flexibility.
- </para>
- </section>
- <section>
- <title>Human-readable Tags</title>
- <para>
- DocBook tags are generally self-explaining.
- They are named after what they define, even
- though shorter terms might make more effiecient
- use of space. This makes it easy for writers
- and editors to quickly look at a document and
- understand how it is constructed.
- </para>
- </section>
- <section>
- <title>Text-based Format for Easy Revision Control</title>
- <para>
- Version control provides two critical features
- for collaborative documentation work:
- concurrent editing and history. The text-based
- format of DocBook makes it well-suited to
- being managed by a version control system.
- </para>
- </section>
- <section>
- <title>Separation Between Content and Style</title>
- <para>
- The DocBook standard separates a document's
- content and its formatting. The writer uses XML
- tags to structure the elements of document, and
- the formatting can be changed independently
- later. A change to the formatting of an element
- does not require changing every instance of that
- element.
- </para>
- </section>
- <section>
- <title>Output in a Variety of Formats</title>
- <para>
- DocBook is a source format. The
- <command>publican</command> tool is used to
- generate rendered documents in several different
- formats. publican can generate HTML, PDF, and
- epub formats from the same source file.
- </para>
- </section>
- </section>
- <section>
- <title>Parts of a DocBook File</title>
- <section>
- <title>Entities</title>
- <para>
- Entities are like variables. They allow
- for one change to be reflected many
- times in a document. Entities are
- usually defined early in the document
- using the following syntax:
-<screen><!ENTITY ENTITYNAME "value"></screen>
- Entities are then referred to in the
- document source with
- <literal>&</literal><replaceable>ENTITYNAME</replaceable><literal>;</literal>. The
- most common use of entities are for
- phrases like the current version of a
- product or the product name.
- </para>
- <warning>
- <title>Use entities sparingly</title>
- <para>
- Entities do not appear in the
- PO files for a document, and are
- therefore untranslateable. Only
- use an entity for wording that
- does not require translation
- ("Fedora", for example)
- </para>
- </warning>
- </section>
- </section>
-
-<!-- <section>
- <title>Common DocBook Tags</title>
- <para>In this section, we'll look at the most common DocBook XML tags
- as accepted by <command>publican print_known</command>.
- We will also describe and use them inline, so the effect of
- each tag can be demonstrated. More detailed information can be found at
- <ulink url="http://www.docbook.org">http://www.docbook.org</ulink> .
- </para>
-
- <section id="sect-documentation_guide-docbook_tags-structure">
- <title>Structure Tags</title>
- <para>DocBook publications are structured in outline form.</para>
-
- <section id="sect-documentation_guide-docbook_tags-structure-id_attr">
- <title>Identify your content: The <code>id</code> Attribute</title>
- <para>All structure tags should have an <code>id</code> attribute. Uniquely identifying
- a chapter or section allows it to be linked to, avoids unfortunate page breaks, and makes
- your code more readable. Convention is to first state the type of element,
- then describe the element relative to the whole document.
- </para>
- <example>
- <title>A generic <code>id</code> attribute in action</title>
- <para>id="sect-book_name-chapter_name-section_name-subsection"</para>
- </example>
- </section>
-
- <section id="sect-documentation_guide-docbook_tags-structure-basic_outline">
- <title>Basic Docbook Structure</title>
- <para>visual guide below</para>
- </section>
-
-
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-documentation_guide-docbook_tags-structure-block_elements.xml" />
-
- </section>
- </section> -->
-
- <section>
- <title>Dividing a Document into Multiple Files with XIncludes</title>
- <para>
- As a document grows, managing it as a single file
- becomes challenging. In addition, having multiple files
- compose a single document allows for some files to be
- reused between documents, reducing the overhead for a
- large documenatation package. Fortunately, DocBook
- supports including multiple file. To include an
- additional file into a document, refer to the following
- example:
-<screen><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="<replaceable>Included_File.xml</replaceable>" /></screen>
- When the document is rendered, the included text will
- appear as if it were inserted entirely in the main file.
- </para>
- </section>
-
+ <title>Brief Introduction to DocBook</title>
+ <para>
+ This chapter will give you a brief introduction to DocBook.
+ </para>
+ <section id="sec-Why_DocBook">
+ <title>Why DocBook?</title>
+ <para>
+ DocBook has many features which make it suitable for documentation in Fedora and other projects.
+ </para>
+ <section id="sec-DocBook_as_an_XML_Markup_Language">
+ <title>DocBook as an XML Markup Language</title>
+ <para>
+ DocBook is an implementation of <firstterm>Extensible Markup Language (XML) </firstterm>. XML gives DocBook powerful flexibility.
+ </para>
+ </section>
+ <section id="sec-Human-readable_Tags">
+ <title>Human-readable Tags</title>
+ <para>
+ DocBook tags are generally self-explaining. They are named after what they define, even though shorter terms might make more effiecient use of space. This makes it easy for writers and editors to quickly look at a document and understand how it is constructed.
+ </para>
+ </section>
+ <section id="sec-Text-based_Format_for_Easy_Revision_Control">
+ <title>Text-based Format for Easy Revision Control</title>
+ <para>
+ Version control provides two critical features for collaborative documentation work: concurrent editing and history. The text-based format of DocBook makes it well-suited to being managed by a version control system.
+ </para>
+ </section>
+ <section id="sec-Separation_Between_Content_and_Style">
+ <title>Separation Between Content and Style</title>
+ <para>
+ The DocBook standard separates a document's content and its formatting. The writer uses XML tags to structure the elements of document, and the formatting can be changed independently later. A change to the formatting of an element does not require changing every instance of that element.
+ </para>
+ </section>
+ <section id="sec-Output_in_a_Variety_of_Formats">
+ <title>Output in a Variety of Formats</title>
+ <para>
+ DocBook is a source format. The <command>publican</command> tool is used to generate rendered documents in several different formats. publican can generate HTML, PDF, and epub formats from the same source file.
+ </para>
+ </section>
+ </section>
+ <section id="sec-Parts_of_a_DocBook_File">
+ <title>Parts of a DocBook File</title>
+ <section id="sec-Entities">
+ <title>Entities</title>
+ <para>
+ Entities are like variables. They allow for one change to be reflected many times in a document. Entities are usually defined early in the document using the following syntax:
+ </para>
+ <screen><!ENTITY ENTITYNAME "value"></screen>
+ <para>
+ Entities are then referred to in the document source with <literal>&</literal><replaceable>ENTITYNAME</replaceable><literal>;</literal>. The most common use of entities are for phrases like the current version of a product or the product name.
+ </para>
+ <warning>
+ <para>
+ Entities do not appear in the PO files for a document, and are therefore untranslateable. Only use an entity for wording that does not require translation ("Fedora", for example)
+ </para>
+ </warning>
+ </section>
+ </section>
+
+<!-- <section>
+ <title>Common DocBook Tags</title>
+ <para>In this section, we'll look at the most common DocBook XML tags
+ as accepted by <command>publican print_known</command>.
+ We will also describe and use them inline, so the effect of
+ each tag can be demonstrated. More detailed information can be found at
+ <ulink url="http://www.docbook.org">http://www.docbook.org</ulink> .
+ </para>
+
+ <section id="sect-documentation_guide-docbook_tags-structure">
+ <title>Structure Tags</title>
+ <para>DocBook publications are structured in outline form.</para>
+
+ <section id="sect-documentation_guide-docbook_tags-structure-id_attr">
+ <title>Identify your content: The <code>id</code> Attribute</title>
+ <para>All structure tags should have an <code>id</code> attribute. Uniquely identifying
+ a chapter or section allows it to be linked to, avoids unfortunate page breaks, and makes
+ your code more readable. Convention is to first state the type of element,
+ then describe the element relative to the whole document.
+ </para>
+ <example>
+ <title>A generic <code>id</code> attribute in action</title>
+ <para>id="sect-book_name-chapter_name-section_name-subsection"</para>
+ </example>
+ </section>
+
+ <section id="sect-documentation_guide-docbook_tags-structure-basic_outline">
+ <title>Basic Docbook Structure</title>
+ <para>visual guide below</para>
+ </section>
+
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-documentation_guide-docbook_tags-structure-block_elements.xml" />
+
+ </section>
+ </section> -->
+
+ <section id="sec-Dividing_a_Document_into_Multiple_Files_with_XIncludes">
+ <title>Dividing a Document into Multiple Files with XIncludes</title>
+ <para>
+ As a document grows, managing it as a single file becomes challenging. In addition, having multiple files compose a single document allows for some files to be reused between documents, reducing the overhead for a large documenatation package. Fortunately, DocBook supports including multiple file. To include an additional file into a document, refer to the following example:
+ </para>
+ <screen><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="<replaceable>Included_File.xml</replaceable>" /></screen>
+ <para>
+ When the document is rendered, the included text will appear as if it were inserted entirely in the main file.
+ </para>
+ </section>
</chapter>
<!--
More information about the docs-commits
mailing list