dgv2/en_US doc-entities.xml, 1.3, 1.4 tools.xml, 1.1, 1.2 using-docbook.xml, 1.1, 1.2
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sun Jun 25 14:04:22 UTC 2006
Author: pfrields
Update of /cvs/docs/dgv2/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv3517/en_US
Modified Files:
doc-entities.xml tools.xml using-docbook.xml
Log Message:
Some backed-up work I had not yet committed. More to come shortly.
Index: doc-entities.xml
===================================================================
RCS file: /cvs/docs/dgv2/en_US/doc-entities.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- doc-entities.xml 2 Jun 2006 06:09:04 -0000 1.3
+++ doc-entities.xml 25 Jun 2006 14:04:19 -0000 1.4
@@ -41,6 +41,16 @@
<text>:ext:<replaceable>username</replaceable>@cvs.fedora.redhat.com:/cvs/docs</text>
</entity>
</group>
+ <group name="DocBook">
+ <entity name="DB">
+ <comment>Name of our markup language</comment>
+ <text>DocBook XML</text>
+ </entity>
+ <entity name="DBVER">
+ <comment>Version of markup language used by this project</comment>
+ <text>V4.4</text>
+ </entity>
+ </group>
</entities>
<!--
Index: tools.xml
===================================================================
RCS file: /cvs/docs/dgv2/en_US/tools.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tools.xml 2 Jun 2006 06:09:43 -0000 1.1
+++ tools.xml 25 Jun 2006 14:04:19 -0000 1.2
@@ -10,9 +10,14 @@
]>
-<chapter id="tools">
+<chapter id="ch-tools">
<title>Tools</title>
- <para>dummy</para>
+ <abstract>
+ <para>
+ This chapter explains how to install the common tools used in the
+ &FDP;.
+ </para>
+ </abstract>
</chapter>
<!--
Index: using-docbook.xml
===================================================================
RCS file: /cvs/docs/dgv2/en_US/using-docbook.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- using-docbook.xml 12 Jun 2006 00:22:24 -0000 1.1
+++ using-docbook.xml 25 Jun 2006 14:04:19 -0000 1.2
@@ -11,9 +11,258 @@
]>
<chapter id="ch-using-docbook">
- <title>Using DocBook XML</title>
+ <title>Using &DB;</title>
<abstract>
- <para>This chapter covers how to use DocBook XML within the parameters of
- the &FDP;.</para>
+ <para>
+ This chapter covers how to use &DB; within the parameters of the
+ &FDP;.
+ </para>
</abstract>
+ <section id="sn-xml-basics">
+ <title>&DB; Basics</title>
+ <para>
+ This section presents a few basic rules for creating &DB; files.
+ XML, the eXtensible Markup Language, is a method of marking text
+ that denotes the properties of that text to a reader. This
+ methodology works whether the reader is a human or a computer
+ program. Computer programs can use the markup to interpret the
+ text in unique ways. A markup language allows the author to
+ communicate the "sense" of a chunk of text, such as the difference
+ between the word <wordasword>file</wordasword> and an example file
+ name of <filename>file</filename>.
+ </para>
+ </section>
+ <section id="sn-db-sourcecode">
+ <title>&DB; Source Code</title>
+ <para>
+ &DB; is a particular set of XML markup tags that are useful for
+ technical documentation. &DB; is also a widely used industry
+ standard. It is well documented, freely available, and it is
+ included in the universe of &FED; software. For instructions to
+ install the tools required for using &DB;, refer to <xref
+ linkend="ch-tools"/>.
+ </para>
+ <para>
+ To create markup around text, authors and editors use special
+ <firstterm>tags</firstterm>. These tags are fully defined in the
+ &DB; documentation, but many users memorize only the handful of
+ tags that they use most often. Tagged text, or &DB; source, looks
+ like this:
+ </para>
+ <example id="ex-db-source">
+ <title>&DB; source code</title>
+ <screen><![CDATA[
+<para>
+ This paragraph contains the file name
+ <filename>foo.txt</filename>, and some other
+ information that is <emphasis>really</emphasis>
+ important.
+</para>]]></screen>
+ </example>
+ <para>
+ The &FDP; build tools use other programs to parse this source and
+ transform it into other formats. This document was created from
+ &DB; source, and was transformed into the format you are using
+ now. The &DB; source above, when transformed into HTML, looks
+ like this:
+ </para>
+ <example id="ex-db-xform-html">
+ <title>&DB; transformation to HTML</title>
+ <para>
+ This paragraph contains the file name
+ <filename>foo.txt</filename>, and some other information that is
+ <emphasis>really</emphasis> important.
+ </para>
+ </example>
+ <para>
+ The &DB; source contains no information that dictates how a
+ particular markup should look when transformed to another format.
+ For instance, &DB; does not dictate that text marked with an
+ <sgmltag>emphasis</sgmltag> tag must be italicized rather than
+ underlined. &DB; leaves this decision to the transformation
+ engine. It so happens that &FED; includes a full set of
+ transformation programs and associated rules (or
+ <firstterm>stylesheets</firstterm>) for making these decisions.
+ The &FDP; build system applies some custom rules to this
+ collection.
+ </para>
+ <para>
+ By separating the work of formatting from the work of authoring,
+ &DB; maximizes your efficiency in creating &FED; documentation.
+ </para>
+ </section>
+ <section id="sn-db-entities">
+ <title>Entities</title>
+ <para>
+ Entities allow you to refer to a piece of text, with or without
+ markup, using a name. Any piece of text that you plan to use
+ repeatedly is a good candidate for inclusion as an entity. For
+ instance, this document uses the entity <sgmltag
+ class="genentity">FDP</sgmltag> to represent the text "&FDP;."
+ This is an example of a <firstterm>general entity</firstterm>.
+ </para>
+ <para>
+ You can also use entities to refer to lists of other entity
+ information. These entities are called <firstterm>parameter
+ entities</firstterm>. An example appears in <xref
+ linkend="sn-db-header"/>.
+ </para>
+ </section>
+ <section id="sn-db-header">
+ <title>&DB; Header</title>
+ <para>
+ All &DB; files must have specific preliminary information to be
+ recognized by build tools and used for &FED; documentation. To
+ create a proper &DB; file for the &FDP;, follow these steps.
+ </para>
+ <procedure>
+ <step>
+ <para>
+ At the beginning of any &DB; file in your document, first
+ include a standard XML declaration:
+ </para>
+ <screen><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>]]></screen>
+ </step>
+ <step>
+ <para>
+ Following the XML declaration, create a
+ <sgmltag>DOCTYPE</sgmltag> declaration for your document:
+ </para>
+ <screen><![CDATA[
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.docbook.org/xml/4.4/docbookx.dtd" [
+
+<!ENTITY % FDP-ENTITIES SYSTEM "fdp-entities.ent">
+%FDP-ENTITIES;
+
+<!ENTITY % DOC-ENTITIES SYSTEM "doc-entities.ent">
+%DOC-ENTITIES;
+
+]>]]></screen>
+ <para>
+ The <sgmltag class="genentity">DOCTYPE</sgmltag> declaration
+ includes five parameters:
+ </para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>
+ the top-level element (tag pair) for this XML document
+ </para>
+ <para>
+ This will often be a high-level organizational element
+ like <sgmltag class="element">article</sgmltag>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ an indicator of whether the <firstterm>Document Type
+ Definition</firstterm> (<acronym>DTD</acronym>) is a
+ local file resource (<sgmltag
+ class="attvalue">SYSTEM</sgmltag>) or publicly available
+ through a URL (<sgmltag
+ class="attvalue">PUBLIC</sgmltag>)
+ </para>
+ <para>
+ For &DB; this indicator will always be <sgmltag
+ class="attvalue">PUBLIC</sgmltag>. The DTD is a full
+ specification for how a set of XML markup will work. The
+ DTD defines valid elements, attributes, ordering, and
+ other details.<footnote id="fn-db-dtd">
+ <para>
+ It is accurate to say that &DB; is a particular XML
+ DTD, or set of valid elements, attributes, ordering,
+ and other associated details.
+ </para>
+ </footnote>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the DTD <firstterm>formal public identifier</firstterm>
+ (<acronym>FPI</acronym>) string
+ </para>
+ <para>
+ This string should be the official identifier for &DB;
+ &DBVER;, which is <literal>"-//OASIS//DTD DocBook XML
+ V4.4//EN"</literal>.
+ </para>
+ <important>
+ <title>Avoid Typos in DTD FPI</title>
+ <para>
+ An error in the DTD FPI causes some validating tools to
+ fail. Use caution and check the DTD FPI content, or
+ copy it from a known good source.
+ </para>
+ </important>
+ </listitem>
+ <listitem>
+ <para>
+ the file location or URL for the DTD
+ </para>
+ <para>
+ There are at least two URLs valid for the &DB; &DBVER;
+ DTD:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink
+ url="http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
+ url="http://www.docbook.org/xml/4.4/docbookx.dtd"/>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <important>
+ <title>Avoid Typos in URL</title>
+ <para>
+ An error in the URL causes some validating tools to
+ fail. Use caution and check the DTD FPI content, or
+ copy it from a known good source. (Note in particular
+ the <literal>x</literal> in the file name.)
+ </para>
+ </important>
+ </listitem>
+ </orderedlist>
+ <para>
+ This declaration also includes two parameter entities,
+ <sgmltag class="paramentity">FDP-ENTITIES</sgmltag> and
+ <sgmltag class="paramentity">DOC-ENTITIES</sgmltag>. Each of
+ these parameter entities points at a local file, which
+ contains a list of additional entities. Any programs that
+ parse the &DB; source include those entities as if they were
+ declared in the same order in this document.
+ </para>
+ <para>
+ They are included in the <firstterm>internal
+ subset</firstterm> of the document. The internal subset
+ appears between the square brackets <literal>[ ]</literal>
+ after the document type declaration. Each of these entity
+ declarations is a pointer to a file with additional general
+ entity declarations that can be used in your document. You
+ need not create the contents of the <sgmltag
+ class="paramentity">FDP-ENTITIES</sgmltag>, because they are
+ provided by the &FDP; build tools. <remark role="FIXME">ADD
+ XREF HERE</remark><!-- <xref
+ linkend="sn-creating-doc-entities"/> --> discusses how to
+ create and use <sgmltag
+ class="paramentity">DOC-ENTITIES</sgmltag>.</para>
+ </step>
+ </procedure>
+ </section>
</chapter>
+
+
+<!--
+
+Local variables:
+Mode: xml
+fill-column: 72
+End:
+
+-->
More information about the Fedora-docs-commits
mailing list