cvs: phpdoc /howto docbook.xml
| From: | Philip Olson | Date: | Mon, 07 Jan 2008 01:27:06 +0000 |
| Subject: | cvs: phpdoc /howto docbook.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-998@lists.php.net to get a copy of this message | ||
philip Mon Jan 7 01:27:06 2008 UTC
Modified files:
/phpdoc/howto docbook.xml
Log:
Some restructuring, rewriting, and shortening, of this HOWTO text
http://cvs.php.net/viewvc.cgi/phpdoc/howto/docbook.xml?r1=1.9&r2=1.10&diff_format=u
Index: phpdoc/howto/docbook.xml
diff -u phpdoc/howto/docbook.xml:1.9 phpdoc/howto/docbook.xml:1.10
--- phpdoc/howto/docbook.xml:1.9 Sat Dec 29 19:17:47 2007
+++ phpdoc/howto/docbook.xml Mon Jan 7 01:27:06 2008
@@ -7,77 +7,61 @@
<title>What is DocBook?</title>
<para>
- Quote from the introduction part of
- <link xlink:href="&url.docbook;">DocBook: The Definitive
Guide</link>:
+ First, don't be worried about learning another language or syntax
+ because DocBook is fairly straight forward and most contributors
+ simply cut-n-paste existing files, modify the content, then commit.
+ It's just plain text.
</para>
<para>
- DocBook is a very popular set of tags for describing books,
- articles, and other prose documents, particularly technical
- documentation. DocBook is defined using the native DTD
- syntax of SGML and XML. Like HTML, DocBook is an example
- of a markup language defined in SGML/XML.
+ What is DocBook? The following is a quote from
+ <link xlink:href="&url.docbook;">DocBook: The Definitive
Guide</link>:
</para>
<para>
- Simply this means, that writing a DocBook file is no more,
- than writing a text file, using some simple "tags" where
- they are needed. An opening tag is a < bracket followed
- by the tag's name, optionally some arguments, and a >
- bracket (eg. <para> for paragraphs). A closing tag
- is a < bracket followed by a / sign, the tag name and
- a closing > bracket (eg. </para> for paragraphs).
- The best way of studying what tags to use is to look into
- the manual files, or the collected samples in the
- <link linkend="chapter-skeletons">Documentation Skeletons</link>
- section of this HOWTO. You can also download a full copy
- of the DocBook book mentioned above, so you can search for
- appropriate tags to use yourself.
+ <emphasis>
+ DocBook is a very popular set of tags for describing books,
+ articles, and other prose documents, particularly technical
+ documentation. DocBook is defined using the native DTD
+ syntax of SGML and XML. Like HTML, DocBook is an example
+ of a markup language defined in SGML/XML.
+ </emphasis>
</para>
<para>
- We use DocBook because it is so easy to generate several
- output formats of our documents (HTML, PDF, Microsoft
- HTML Help, RTF, etc.), and is a world standard way of
- storing structured technical information.
- </para>
-
- <para>
- You don't need to know all tags of DocBook to contribute
- to our work. If you are a translator, you need not translate
- any tags or invent others, so you will only be interested
- in the content between the opening and closing tags.
+ Simply this means that writing a DocBook file is no more than writing a text
+ file and using a few simple "tags" when needed. Like HTML, an opening tag is
+ a < bracket followed by the tag's name, optionally some arguments, and then
+ the > bracket (e.g. <para> for paragraphs). A closing tag is a <
+ bracket followed by a / sign, the tag name, then the closing > bracket
+ (e.g. </para> for paragraphs). For example uses, have a look at an existing
+ file within the PHP manual sources, or use the <link
linkend="chapter-skeletons">
+ documentation skeletons</link>.
</para>
- </sect1>
-
- <sect1 xml:id="docbook-and-html">
- <title>DocBook for Native Speakers of HTML</title>
<para>
- As you have seen above, DocBook is similar in file
- structure to HTML. Although if you are used to HTML,
- DocBook will probably seem pretty tag-verbose to you.
- DocBook also uses logical tags, it has no (or at least
- very few) layout-specific tags like HTML is full of.
- The idea with DocBook is to tell as much as you can
- about the information while writing it, so that software
- can do more things with it. In DocBook you use tags
- to mark the <emphasis>meaning</emphasis> of parts not
- the presentation.
+ As described above, DocBook uses a similar structure to HTML with the main
+ difference being DocBook uses tags to define the <emphasis>meaning</emphasis>
+ whereas HTML often times defines the look and layout. So the idea behind
+ DocBook is to define as much as possible about the information so that build
+ and rendering software will intelligently output the text into many formats.
</para>
<para>
- We use DocBook, because it eases the generation of the several
- formats of the documentation, and acts as a central "meta format"
- for all the things we would like to express in the documentation.
+ We use DocBook because it makes it easy to generate several formats of our
+ documents (HTML, PDF, Microsoft HTML Help (CHM), RTF, etc.), and DocBook is
+ the standard way for storing structured technical information.
</para>
- <para>
- You cannot just invent tags in DocBook. There is a standard
- set of tags you can use. If you are working on a translation,
- please do not translate tags, as they need to stay as they
- were written in the English files to work properly.
- </para>
+ <note>
+ <title>DocBook version upgrade history</title>
+ <para>
+ On January 2, 2007 we upgraded from DocBook 4.1.2 to 4.5 and then
+ to DocBook 5 at around June 20, 2007. These upgrades included changes
+ to most files in the phpdoc CVS repository.
+ </para>
+ </note>
+
</sect1>
<sect1 xml:id="docbook-refs">