[documentation-guide] some restructuring, added a few elements to the demo
Pete Travis
immanetize at fedoraproject.org
Wed Nov 23 06:17:43 UTC 2011
commit 8b824441714a5ee09838afb6df5ce92d489b3e07
Author: Pete Travis <me at petetravis.com>
Date: Thu Nov 10 22:23:05 2011 -0700
some restructuring, added a few elements to the demo
en-US/docbook-demonstration.xml | 373 ++-------------------------------------
en-US/docbook.xml | 40 ++++-
2 files changed, 57 insertions(+), 356 deletions(-)
---
diff --git a/en-US/docbook-demonstration.xml b/en-US/docbook-demonstration.xml
index c4868da..0568ab0 100644
--- a/en-US/docbook-demonstration.xml
+++ b/en-US/docbook-demonstration.xml
@@ -3,359 +3,24 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "documentation-guide.ent">
%BOOK_ENTITIES;
]>
-<chapter id="chap-documentation_guide-docbook_tags">
- <title>A visual guide to 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>
- <screen>
- <sgmltag><!-- This is a comment. Visible in source, not publication. --></sgmltag>
- <sgmltag><book></sgmltag>
- <sgmltag> <chapter></sgmltag>
- <sgmltag> <chapter></sgmltag>
- <sgmltag> <section></sgmltag>
- <sgmltag> <section></sgmltag>
- <sgmltag> <section></sgmltag><sgmltag><!-- Sections can be nested! --></sgmltag>
- </screen>
-
-
- </section>
+<programlisting>
+<![CDATA[
+<!-- This is a comment. Visible in source, not publication. -->
+<book>
+ <part>
+ <chapter>
+ <title>Chapters need titles</title>
+ <section>
+ <title>Sections need titles too</title>
+ <part>Content goes here</part>
+ <section>
+ <title>This section is nested</title>
+ <part>This content needs its own section</part>
+ </section>
</section>
-
-</chapter>
-<!--
+ </chapter>
+ </part>
+</book>
+]]>
+</programlisting>
- <section id="sect-documentation_guide-docbook_tags-structure-chapter">
- <title>Splitting it up: <sgmltag><chapter></sgmltag></title>
- <para>Smaller divisions of a book are contained in a<sgmltag><chapter></sgmltag>.
- Each <sgmltag><chapter></sgmltag> should have a <sgmltag><title></sgmltag>
- and contain several <sgmltag><sections></sgmltag></para>
- </section>
- <section id="sect-documentation_guide-docbook_tags-structure-section">
- <title>Useful pieces: <sgmltag><section></sgmltag></title>
- <para> The <sgmltag><section></sgmltag> is where we begin to show our content.
- Most other tags will be contained in a <sgmltag><section></sgmltag>.</para>
- <section id="sect-documentation_guide-docbook_tags-structure-section-nesting">
- <title>Nesting <sgmltag><section></sgmltag> elements</title>
- <para><sgmltag><section></sgmltag> elements can be nested as much as needed.
- Grouping related content in a <sgmltag><section></sgmltag> allows it to be moved or edited atomically.
- </para>
- </section>
- </section>
-
-
- </section>
-
- <section id="sect-documentation_guide-docbook_tags-block_formatting"></section>
--->
-
-
-<!--
-!!!structure!!!
-::index::
-!depricated indexterm
-!inline index secondary
-!inline index see
-!inline index seealso
-!inline index tertiary
-::appendix::
-!block appendix
-!depricated appendixinfo
-
-::asides::
-!block aside abstract
-!block subset answer
-
-!block example
-!block asides note
-
-::bibliography::
-!block subset bibliodiv
-!block subset biblioentry
-!block subset bibliography
-
-
-!dependent block area
-!dependent block areaset
-!dependent block areaspec
-!inline confused accel
-
-::outline form::
-!structure root article
-!depricated articleinfo
-!used - book
-!depricated? bookinfo
-!used - chapter
-!depricated? - chapterinfo
-!block structure simpara
-!root structure part
-!root structure partintro
-!structure title
-!used section
-!inline structure subtitle
-!block para formalpara
-!root structure preface
-
-::table::
-!block dependent columns colspec
-
-!block dependent table entry
-!block tables table
-!block tables depricated tbody
-!block dependent table td
-!block tables depricated tr
-!block table tgroup
-!block table depricated thead
-!depricated informaltable
-
-::lists::
-!inline lists seg
-!inline lists seglistitem
-!inline lists segmentedlist
-!inline lists segtitle
-!inline lists simplelist
-!inline lists variablelist
-!inline formatting sgmltag
-!inline address shortaffil
-!inline lists varlistentry
-!block lists itemizedlist
-!block dependent lists listitem
-!inline lists member
-
-::questions and answers::
-!block dependent qanda qandaentry
-!block block dependent qanda qandaset
-!block dependent qanda question
-
-
-
-!block directions procedure
-!inline formatting phrase
-
-
-
-
-
-!inline special group
-!block root index
-!block lists orderedlist
-!block? directions <pre> screen
-!block formatting para
-!block aside warning
-!block tables row
-
-!suppr special xi:fallback
-!special suppr xi:include
-!suppressed structure ~comment
-
-
-!!!vocabulary!!!
-!inline avoid? abbrev
-!inline acronym
-!inline application
-!inline arg
-!block blockquote
-!inline formatting emphasis
-!inline formatting literal
-!block formatting literallayout
-!inline important
-!inline role-attribute? hardware
-!inline foreignphrase
-!inline filename
-!depricated interface
-!inline coding interfacename
-!depricated isbn
-!inline directions keycap
-!inline directions keycombo
-!inline dependent directions menuchoice
-!inline directions mousebutton
-!inline directions step
-!inline directions substeps
-!inline directions stepalternatives
-!inline formatting remark
-!inline formatting replaceable
-!inline directions/coding package
-!inline directions option
-!inline formatting systemitem
-!inline formatting term
-!inline trademark
-!inline coding? type
-!inline depricated ulink
-!block structure uri
-!inline directions userinput
-!inline wordasword
-
-
-!!!citations references embeds !!!
-!inline dependent citerefentry
-!inline citetitle
-!block images figure
-!inline citations productname
-!inline citations productnumber
-!inline citations programlisting
-!inline citations programlistingco
-!inline citations refentry
-!depricated refentryinfo
-!inline citations refentrytitle
-!supressed citations reference
-!supressed citations refmeta
-!inline/block citations refname
-!block citations refnamediv
-!inline citations refpurpose
-!inline citations refsection
-!block dependent image imagedata
-!block dependent image imageobject
-!block dependent image inlinemediaobject
-!inline firstterm
-!block special footnote
-!block special footnote footnoteref
-!block dependent images avoid! mediaobject
-!inline structure xref
-!block dependent images textobject
-!inline citations/bib issuenum
-!inline dependent citations manvolnum
-
-
-
-
-
-!!!meta!!!!
-inline descriptive primary
-!inline/block affiliation
-!block descriptive colophon
-!inline/block descriptive contrib
-!inline/block descriptive copyright
-!depricated corpauthor
-!inline/block descriptive edition
-!inline/block descriptive editor
-!inline descriptive keyword
-!inline descriptive keywordset
-!block descriptive container legalnotice
-!inline descriptive othercredit
-!inline descriptive pubdate
-!inline/descriptive publisher
-!inline/descriptive publishername
-!depricated pubsnumber
-!block.inline descriptive revdescription
-!block/inline descriptive revhistory
-!block/inline descriptive revision
-!block/inline descriptive revnumber
-!inline descriptive year
-!inline subset(copyright) descriptive holder
-!inline/block/supressed descriptive subject
-!inline// descriptive subjectset
-!inline// descriptive subjectterm
-!inline descriptive author
-!inline descriptive authorgroup
-
-
-
-
-!!!contact!!!
-!block address
-!inline city
-!inline dependent address country
-!depricated coutry
-!inline date
-!inline dependent address email
-!inline address firstname
-!inline address pob
-!inline address postcode
-!inline address orgdiv
-!inline address state
-!inline address orgname
-!inline address phone
-!inline address othername
-!inline dependent address fax
-!inline address honorific
-!inline address jobtitle
-!inline address surname
-!inline address street
-
-
-
-
-
-!!!coding!!!
-!inline coding classname
-!inline coding cmdsynopsis
-!inline coding code
-!inline coding command
-!inline coding computeroutput
-!inline gui guibutton
-!inline gui guilabel
-!inline gui guimenu
-!inline gui guimenuitem
-!inline gui guisubmenu
-!inline coding envar
-!coding exceptionname
-!inline coding function
-!inline coding methodname
-!inline coding/directions prompt
-!inline coding/whatever property
-!inline coding/directins attr=class parameter
-!inline coding/directions varname
-
-
-!inline structure callout
-!inline structure calloutlist
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
--->
\ No newline at end of file
diff --git a/en-US/docbook.xml b/en-US/docbook.xml
index 3b1f489..60b8098 100644
--- a/en-US/docbook.xml
+++ b/en-US/docbook.xml
@@ -3,6 +3,7 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "documentation-guide.ent">
%BOOK_ENTITIES;
]>
+
<chapter id="chap-documentation_guide-docbook">
<title>Brief Introduction to DocBook</title>
<para>
@@ -36,14 +37,49 @@
<title>Parts of a DocBook File</title>
<para/>
</section>
+
<section>
<title>Common DocBook Tags</title>
- <para/>
- </section>
+ <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>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="docbook-demonstration.xml" />
+ </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/>
</section>
+
<section>
<title>Entities: With Great Power Comes Great Responsibility</title>
<para/>
More information about the docs-commits
mailing list