commit 9d22d58cce615de19226c92d14c51183cc8e6995 Author: Robert Krátký rkratky@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>
<!--
docs-commits@lists.fedoraproject.org