Index: phpdoc/howto/howto.ent diff -u phpdoc/howto/howto.ent:1.2 phpdoc/howto/howto.ent:1.3 --- phpdoc/howto/howto.ent:1.2 Sat Sep 8 16:08:22 2001 +++ phpdoc/howto/howto.ent Sat Sep 8 16:50:26 2001 @@ -12,8 +12,13 @@ + + + + + Index: phpdoc/howto/howto.xml diff -u phpdoc/howto/howto.xml:1.3 phpdoc/howto/howto.xml:1.4 --- phpdoc/howto/howto.xml:1.3 Sat Sep 8 16:08:22 2001 +++ phpdoc/howto/howto.xml Sat Sep 8 16:50:26 2001 @@ -193,11 +193,6 @@ - A DTD reference for DocBook can be found here. - - - In addition to the above tools, you will need your favorite text editor and a working CVS installation. Although it is possible to use a simple text editor @@ -212,8 +207,8 @@ You will also need autoconf to - build the phpdoc GNU configure script. Many - distributions come with autoconf already installed. The latest + build the phpdoc GNU configure script. Many + distributions come with autoconf already installed. The latest copy can be found at: @@ -221,14 +216,22 @@ + + + + If you have information about other good XML editors and/or tools + not mentioned here, please send it to the maintainer, + &email.phpdoc;. + + Obtaining the Tools To simplify the installation process of the tools necessary to - write PHP documentation, I have chosen to detail how to download - and install the source RPMs from a sourceware mirror. You will + write PHP documentation, we have chosen to detail how to download + and install the source RPMs from a sourceware mirror. You will need a working copy of RPM installed on the machine you wish to install these tools on. @@ -236,7 +239,7 @@ These tools are all seperate packages and can be downloaded and installed directly from the author's websites if you choose to do - so. You do not have to use these source RPMs, but installing from + so. You do not have to use these source RPMs, but installing from the author's seperate packages is out of the scope of this HOWTO. @@ -274,18 +277,17 @@ - These packages are updated from time to time. Please make sure - you download the latest version available from the above sites + These packages are updated from time to time. Please make sure + you download the latest version available from the above sites. - Installing the Tools - Installing the tools is simple. If you downloaded all of the + Installing the tools is simple. If you downloaded all of the above files into a separate directory by themselves, simply issue the folowing command: @@ -313,7 +315,7 @@ - That's it. You should now have necessary tools installed to edit + That's it. You should now have necessary tools installed to edit and verify your PHP documentation contributions. @@ -323,8 +325,53 @@ + + + + File Overview + + There are many files used to produce the several output + formats, and to store the many text and information needed + to generate the files. These are the most important ones, + you should know about: + + + manual.xml + + + The main file for the documentation. It is supposed + to be only a "glue" between the other parts, containing + only part titles and entity references to chapters. + + + + + chapters.ent + + + Contains entity definitions for all chapters and + appendices. Entities for the XML files are generated + by configure, so there is no need to edit the file. + + + + + global.ent + + + Global internal text entities for all the XML + files. This is where all the external links, + emial addresses, and "macros" are stored. + + + + + + + + - + Using CVS @@ -658,8 +705,6 @@ - - @@ -813,6 +858,71 @@ + + + + Writing XML documents + + + DocBook for Native Speakers of HTML + + 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. + + + Although there are few 1:1 mappings between HTML and DocBook + tags, here is a little list that should at least make life easier + for the HTML proficient: +

+ Tags in HTML vs. DocBook + + + + HTML tag + DocBook tag + + + + + DL + VariableList + + + OL + OrderedList + + + UL + ItemizedList + + + +
+ + + + + DocBook reference + + General information and documentation for DocBook can be found at + &url.docbook-ref;. + + + Element-by-element DTD reference: + &url.docbook-dtdref;. + + + Get Going With DocBook, Notes for Hackers: + &url.docbook-intro;. + + + + + @@ -832,6 +942,12 @@ Basic Commands + If you are using PSGML, it can help you a lot finding out + what tags you can use where. By pressing + C-c C-e + C-x is Emacs's way + of saying you should press Control and the + x key. @@ -843,6 +959,46 @@ + + @@ -906,7 +1062,124 @@ +