cvs: phpdoc /howto docbook.xml

From: 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 &lt; bracket followed - by the tag's name, optionally some arguments, and a &gt; - bracket (eg. &lt;para&gt; for paragraphs). A closing tag - is a &lt; bracket followed by a / sign, the tag name and - a closing &gt; bracket (eg. &lt;/para&gt; 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 &lt; bracket followed by the tag's name, optionally some arguments, and then + the &gt; bracket (e.g. &lt;para&gt; for paragraphs). A closing tag is a &lt; + bracket followed by a / sign, the tag name, then the closing &gt; bracket + (e.g. &lt;/para&gt; 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">

« previous php.doc.cvs (#998) next »