cvs: phpdoc /howto README cvs.xml docbook.xml editors.xml framework.xml generating.xml howto.ent howto.xml preface.xml tools.xml working.xml

From:	Hojtsy Gabor	Date:	Sun, 21 Oct 2001 14:17:00 +0000
Subject:	cvs: phpdoc /howto README cvs.xml docbook.xml editors.xml framework.xml generating.xml howto.ent howto.xml preface.xml tools.xml working.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969338140@lists.php.net to get a copy of this message

goba Sun Oct 21 10:17:00 2001 EDT Added files: /phpdoc/howto cvs.xml docbook.xml editors.xml framework.xml generating.xml preface.xml tools.xml working.xml Modified files: /phpdoc/howto howto.ent howto.xml README Log: Introducing <book> for the howto instead of <article> Now the size indicates the need of parts and other things not possible in an <article>. Also splitting up the single howto.xml to several files, similar to the "big PHP manual". Using CVS, Tools and Working sections are the biggest now. Adding new "What is DocBook" section...

Index: phpdoc/howto/howto.ent diff -u phpdoc/howto/howto.ent:1.7 phpdoc/howto/howto.ent:1.8 --- phpdoc/howto/howto.ent:1.7 Sun Oct 21 08:26:51 2001 +++ phpdoc/howto/howto.ent Sun Oct 21 10:17:00 2001 @@ -25,8 +25,9 @@ <!ENTITY url.php.howto "http://cvs.php.net/co.php/phpdoc/howto/howto.html.tar.gz">  -<!ENTITY url.docbook-dtd "http://www.oasis-open.org/docbook/"> +<!ENTITY url.docbook "http://www.docbook.org/"> <!ENTITY url.docbook-dtdref "http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html"> +<!ENTITY url.docbook-dtd "http://www.oasis-open.org/docbook/"> <!ENTITY url.docbook.appa "http://www.oasis-open.org/docbook/documentation/reference/html/appa.html"> <!ENTITY url.docbook-intro "http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html"> Index: phpdoc/howto/howto.xml diff -u phpdoc/howto/howto.xml:1.13 phpdoc/howto/howto.xml:1.14 --- phpdoc/howto/howto.xml:1.13 Sun Oct 21 08:26:52 2001 +++ phpdoc/howto/howto.xml Sun Oct 21 10:17:00 2001 @@ -1,10 +1,19 @@ <?xml version='1.0' encoding='ISO-8859-1' ?> -<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.7//EN" "../dbxml/docbookx.dtd" [ +<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.7//EN" "../dbxml/docbookx.dtd" [  - <!ENTITY % phpdoc-howto.entities SYSTEM "./howto.ent"> - %phpdoc-howto.entities; + <!ENTITY % howto.entities SYSTEM "./howto.ent"> + %howto.entities; + <!ENTITY howto.preface SYSTEM "preface.xml"> + <!ENTITY howto.framework SYSTEM "framework.xml"> + <!ENTITY howto.tools SYSTEM "tools.xml"> + <!ENTITY howto.cvs SYSTEM "cvs.xml"> + <!ENTITY howto.docbook SYSTEM "docbook.xml"> + <!ENTITY howto.working SYSTEM "working.xml"> + <!ENTITY howto.generating SYSTEM "generating.xml"> + <!ENTITY howto.editors SYSTEM "editors.xml"> + ]>  -<article id="index"> - - - - <artheader> - <author> - <firstname>Stig</firstname> - <surname>Sæther Bakken</surname> - <authorblurb> - <simpara> - (<ulink url="mailto:&email.stig;">&email.stig;</ulink>) - </simpara> - </authorblurb> - </author> - <author> - <firstname>Daniel</firstname> - <surname>Beckham</surname> - <authorblurb> - <simpara> - (<ulink url="mailto:&email.danbeck;">&email.danbeck;</ulink>) - </simpara> - </authorblurb> - </author> - <author> - <firstname>Gábor</firstname> - <surname>Hojtsy</surname> - <authorblurb> - <simpara> - (<ulink url="mailto:&email.goba;">&email.goba;</ulink>) - </simpara> - </authorblurb> - </author> - <author> - <firstname>Jirka</firstname> - <surname>Kosek</surname> - <authorblurb> - <simpara> - (<ulink url="mailto:&email.jirka;">&email.jirka;</ulink>) - </simpara> - </authorblurb> - </author> - <author> - <firstname>Jeroen</firstname> - <surname>van Wolffelaar</surname> - <authorblurb> - <simpara> - (<ulink url="mailto:&email.jeroen;">&email.jeroen;</ulink>) - </simpara> - </authorblurb> - </author> - <title>PHP Documentation HOWTO</title> - </artheader> - - - - <sect1 id="about"> - <title>About This Document</title> - - <para> - This document contains information important for the PHP - Documentation Group members. If you are interested in the - documentation of PHP, you are at the wrong place, see - <ulink url="&url.php.docs;">&url.php.docs;</ulink> for - downloadable documentation. - </para> - - <para> - Currently this HOWTO is "under construction". When this - document will be ready, you will find sections here about - generating HTML documentation from XML sources, adding - new XML files, or using XSL style sheets to process the - source files. - </para> - - <para> - The latest copy of this HOWTO can be downloaded from - the web at: <ulink url="&url.php.howto;">&url.php.howto;</ulink>. - </para> - - <sect2 id="copyright"> - <title>Copyright Information</title> - - <para> - This document is copyrighted (c) 2000, 2001 by - the PHP Documentation Group, and is distributed - under terms stated below. - </para> - - <para> - This document may be reproduced and distributed in whole or in - part, in any medium physical or electronic, as long as this - copyright notice is retained on all copies. - </para> - - <para> - All translations, derivative works, or aggregate works - incorporating this document must be covered under this copyright - notice. That is, you may not produce a derivative work from this - document and impose additional restrictions on its - distribution. Exceptions to these rules may be granted under - certain conditions; please contact the HOWTO coordinators at the - address given below. - </para> - - <para> - In short, we wish to promote dissemination of this information - through as many channels as possible. However, we do wish to - retain copyright on the HOWTO documents, and would like to be - notified of any plans to redistribute the HOWTOs. - </para> - - <para> - If you have any questions, please contact the PHP Documentation - Group at <email>&email.phpdoc;</email> - </para> - - </sect2> - - <sect2 id="disclaimer"> - <title>Disclaimer</title> +<book id="index" lang="en"> + <title>PHP Documentation HOWTO</title> - <para> - No liability for the contents of this documents can be - accepted. Use the concepts, examples and other content at your own - risk. As this is a new edition of this document, there may be - errors and inaccuracies, that may of course be damaging to your - system. Proceed with caution, and although this is highly - unlikely, the author(s) do not take any responsibility for that. - </para> + <bookinfo id="bookinfo"> + <authorgroup id="authors"> - <para> - All copyrights are held by their respective owners, - unless specifically noted otherwise. Use of a term in this - document should not be regarded as affecting the validity of any - trademark or service mark. - </para> + <author> + <firstname>Stig</firstname><surname>Sæther Bakken</surname> + </author> + + <author> + <firstname>Daniel</firstname><surname>Beckham</surname> + </author> + + <author> + <firstname>Gábor</firstname><surname>Hojtsy</surname> + </author> + + <author> + <firstname>Jirka</firstname><surname>Kosek</surname> + </author> + + <author> + <firstname>Jeroen</firstname><surname>van Wolffelaar</surname> + </author> + + </authorgroup> + + <authorgroup id="editors"> + <editor> + <firstname>Gábor</firstname><surname>Hojtsy</surname> + </editor> + </authorgroup> + + <copyright> + <year>2001</year><holder>the PHP Documentation Group</holder> + </copyright> + + <legalnotice id="copyright"> + <title>Copyright</title> + <simpara> + This manual is © Copyright 2001 by the PHP Documentation + Group. See the copyright terms of the PHP Documentation for + information about what conditions are applied to this document. + </simpara> + </legalnotice> + </bookinfo> - <para> - Naming of particular products or brands should not be seen as - endorsements. - </para> - - <para> - You are strongly recommended to take a backup of your system - before major installation and backups at regular intervals. - </para> - - </sect2> - - <sect2 id="credits"> - <title>Credits</title> - - <para> - This document is based on many files, previously hosted - in the phpdoc module at cvs.php.net, containg information - about several distinct subjects, ranging from generating - the HTML files from XML sources to starting a new translation. - This is a central place for all these things. We tried to - include the original authors in the authors list of this file. - </para> - - </sect2> - - <sect2 id="feedback"> - <title>Feedback</title> - - <para> - Feedback is most certainly welcome for this document. Without your - submissions and input, this document wouldn't exist. Please send - your additions, comments and criticisms to the following email - address: <email>&email.phpdoc;</email>. - </para> - - </sect2> - </sect1> - - + &howto.preface; - <sect1 id="getting-started"> + <part id="part-getting-started"> <title>Getting Started</title> + &howto.framework; + &howto.tools; + &howto.cvs; + &howto.docbook; + </part> + + <part id="part-working-in-phpdoc"> + <title>Working In The phpdoc Repository</title> + &howto.working; + </part> + + <part id="part-generating-output"> + <title>Generating Documentation and Validating</title> + &howto.generating; + </part> + + <part id="part-using-editors"> + <title>Using Editors</title> + &howto.editors; + </part> - <para> - The PHP documentation is written in XML using the <link - linkend="docbook">DocBook DTD</link>. If you would like - to contribute to the PHP documentation work, you need - to at least know the very basics of XML and DocBook. - </para> - - <para> - The XML files are stored on a central server, and - can be reached with a <link linkend="cvs">CVS</link> - client. There are many CVS clients out there, although - we recommend one command line tool. - </para> - - <para> - You will need more programs and tools to manipulate the - XML files and test their content for errors. What tools - you need depends on the operating system you use. Linux - or some sort of Unix is recommended, although many things - in phpdoc works on Windows. You will find more information - about the tools you need in the - <link linkend="tools-setup">tools</link> section. - </para> - - <para> - If you have problems not covered in this document, - write in to <email>&email.phpdoc;</email> and ask. - </para> - - </sect1> - - - - <sect1 id="tools-setup"> - <title>Tools and Setup Instructions</title> - - <para> - What tools you need depends on the operating system you use. - Linux or some sort of Unix is recommended, although many - things in phpdoc works on Windows. The very basic things - you need to work: - <itemizedlist> - <listitem><simpara>CVS account</simpara></listitem> - <listitem><simpara>CVS client</simpara></listitem> - <listitem><simpara>Text editor</simpara></listitem> - </itemizedlist> - The basic process is to check out (~download) the file - using the CVS client, then edit it, and finally commit - (~upload) it to the server. Of course you can find better - tools to edit XML files than a simple text editor, it - is just the absolute minimum. Some more useful tools: - <itemizedlist> - <listitem><simpara>XML [capable] editor</simpara></listitem> - <listitem><simpara>Tools to test the edited file</simpara></listitem> - </itemizedlist> - In the folowing paragraphs, you can find information about - how to obtain these tools and how to make them work for you. - </para> - - <para> - The last item in the above list (test the edited file) is - the hardest to get working, as you need a copy of the English - and your translations language files from the phpdoc tree. Also - you need to set up the DocBook files, and several other tools. - The viewable manual, and other formats such as PDF and RTF, are - created using <ulink url="&url.jade;">Jade</ulink> and - <ulink url="&url.nwalsh;">Norman Walsh's Modular DocBook - Stylesheets</ulink>. There are other tools used to produce some - other formats and files. It is recommended to set up the style - sheets and Jade to be able to test your contributions. Otherwise - you can easily cause headaches to other team members. - </para> - - <para> - <emphasis> - If you have information about other good XML editors and/or tools - not mentioned here, please send it to the maintainer: - <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>. - </emphasis> - </para> - - <sect2 id="tools-on-linux"> - <title>Tools on Linux</title> - - <para> - Although many tools are preinstalled on the majority of - the Linux systems, we collected some useful information - about how they can be obtained and installed, if your - system misses them. - </para> - - <para> - You will need your favorite text editor and a working - <link linkend="cvs">CVS</link> installation. Although - it is possible to use a simple text editor such as vi - to write the XML files, it is recommended to use an - XML/SGML editor that helps you along and makes sure your - document is proper XML conforming to the used document type - definition (DTD). A very good (and free) XML/SGML editor - is Emacs+PSGML. Both Emacs and CVS are already part of just - about every Linux distribution available. - </para> - - <para> - You will also need <ulink url="&url.autoconf;">autoconf</ulink> to - build the phpdoc GNU configure script. Many distributions come - with autoconf already installed. The latest copy can be found at: - <itemizedlist> - <listitem> - <simpara><ulink url="&url.autoconf.ftp;">&url.autoconf.ftp;</ulink></simpara> - </listitem> - </itemizedlist> - </para> - - <sect3 id="tools-on-linux-obtaining"> - <title>Obtaining the Tools</title> - - <para> - To simplify the installation process of the tools necessary to - 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 <ulink url="&url.rpm;">RPM</ulink> installed - on the machine you wish to install these tools on. - </para> - - <para> - These tools are all separate 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 - the author's separate packages is out of the scope of this HOWTO. - </para> - - <para> - The RPMs with the necessary software can be downloaded from one of - the following URLs: - </para> - - <para> - <itemizedlist> - <listitem> - <simpara> - <ulink url="&url.docbookmirror1;">&url.docbookmirror1;</ulink> - </simpara> - </listitem> - - <listitem> - <simpara> - <ulink url="&url.docbookmirror2;">&url.docbookmirror2;</ulink> - </simpara> - </listitem> - </itemizedlist> - </para> - - <para> - You will need to download the following files: - <itemizedlist> - <listitem><simpara>docbook-3.x-5.src.rpm</simpara></listitem> - <listitem><simpara>jade-1.2.x-4.src.rpm</simpara></listitem> - <listitem><simpara>jadetex-2.x-0.src.rpm</simpara></listitem> - <listitem><simpara>psgml-1.2.x-1.src.rpm</simpara></listitem> - <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem> - <listitem><simpara>stylesheets-0.10-2.src.rpm</simpara></listitem> - </itemizedlist> - </para> - - <para> - These packages are updated from time to time. Please make sure - you download the latest version available from the above sites - (the actual file names may change, so if you find newer files - than mentioned above, please report, and we can update this list). - </para> - - <note> - <para> - We currently use DocBook 3.1.7 (not the latest version) for - writing phpdoc files. This is because there are - incompatibilities between DocBook 3.x and 4.x currently not - corrected in the documentation. Probably we will update - the XML files, and move to DocBook 4.1.2 soon. - </para> - </note> - - </sect3> - - <sect3 id="tools-on-linux-installing"> - <title>Installing the Tools</title> - - <para> - Installing the tools is simple. If you downloaded all of the - above files into a separate directory by themselves, simply issue - the folowing command: - </para> - - <para> - <informalexample> - <programlisting> -$ rpm -Uvh *.rpm - </programlisting> - </informalexample> - </para> - - <para> - Or, you can issue them one by one in the following order: - <informalexample> - <programlisting> -$ rpm -Uvh docbook-3.x-5.src.rpm -$ rpm -Uvh jade-1.2.x-4.src.rpm -$ rpm -Uvh jadetex-2.x-0.src.rpm -$ rpm -Uvh psgml-1.2.x-1.src.rpm -$ rpm -Uvh sgml-common-0.1-3.src.rpm -$ rpm -Uvh stylesheets-0.10-2.src.rpm - </programlisting> - </informalexample> - </para> - - <para> - That's it. You should now have necessary tools installed to edit - and verify your PHP documentation contributions. - </para> - - </sect3> - </sect2> - - <sect2 id="tools-on-windows"> - <title>Tools on Windows</title> - - <para> - Although the phpdoc environment is based on many Unix - tools and techniques, there are ways to accomplish the - same tasks on Windows. It is not too hard to set up a - Windows working environment with CVS and the DocBook - tools, but put away your mouse as you will need the - keyboard for the majority of the tasks! :) - </para> - - <sect3 id="tools-on-windows-obtaining"> - <title>Obtaining the Tools</title> - - <para> - You need the same tools as on Linux. The very basic - thing is a CVS client. You can find one simple command - line client here at the <ulink url="&url.cvs-win;">CVSHome.org</ulink> - Win32 download pool. We do not recommend GUI tools such - as WinCVS, because they can easily screw up the repository - with files not intended to be there (eg. files with - uppercased names). The best is to use one command line - client, as this way you are in control. - </para> - - <para> - About XML editors, you are encouraged not to use WYSIWYG XML - editors, such as XML Spy, because the often friendly auto-indent, - and optimize features can make the XML files so different from - the one you started the work with, that the diff posted to our - mailing list and used by translators will be useless. Emacs - is also available for Windows if you would like to give it a try ;) - </para> - - <para> - If you want to produce something viewable, or just would - like to test the modified file before committing (recommended!), - you need some more tools. To get it running on Windows, - you'll need these tools: - - <itemizedlist> - <listitem> - <simpara> - <ulink url="&url.win.cygwin;">Cygwin (bash for windows; it's huge...)</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - <ulink url="&url.jade;">Jade (the actual parser, take the windows binary dist)</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - <ulink url="&url.nwalsh;">Norman Walsh's modular DocBook stylesheets</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - <ulink url="&url.iso.entities;">Some ISO-entity declarations</ulink> - </simpara> - </listitem> - </itemizedlist> - Note that if you use Cygwin, there is no need to download a - CVS client, as Cygwin comes with a CVS client built in. - </para> - </sect3> - - <sect3 id="tools-on-windows-installing"> - <title>Installing the Tools</title> - - <para> - You need to download and install the Cygwin tools. - Just select the "Install now!" link and run the supplied - <filename>setup.exe</filename>. It will guide you through - process of installation. These tools are port of standard - Unix tools like sed, awk, autoconf, make, perl, ... - for Windows. - </para> - - <para> - Run "Cygwin Bash Shell" command from the Programs menu - (it will be added here by the previous step). Now you get - a command line which behaves same as bash on Unix boxes. - If you never worked with bash or Unix before, note that - there are slashes (/) instead of backslashes (\) in paths. - If you want to access the <literal>foo</literal> directory - on drive <literal>c:</literal> write it as - <literal>c:/foo</literal> instead of <literal>c:\foo.</literal> - </para> - - <warning> - <simpara> - Do NOT use symlinks with Cygwin, it's buggy. (Jade doesn't - like them, and the shell doesn't handle them very well either) - </simpara> - </warning> - - <para> - Change to the dir where your phpdoc snapshot is (or where you - want to have it). Use, just like in Windows, the - <literal>cd</literal> command. In Cygwin, the - <literal>dir</literal> command is also supported. - </para> - - <para> - If you don't have your snapshot yet, execute CVS (packaged with - Cygwin). More information about CVS can be found in the - <link linkend="CVS">CVS section</link> of this document. - </para> - - <note> - <simpara> - If you decide to use another directory in one of the next - steps, you'll probably need to modify - <filename>phpdoc/configure.in</filename> manually. - We do not give any support if you are self-opinionated :) - In this situation you can specify the DSSSL location - manually by using the - <literal>--with-dsssl=C:/path/to/dsssl</literal> - option with configure. - </simpara> - </note> - - <para> - Make sure that you are in the directory where the - <literal>phpdoc</literal> dir is located. (if you type - <literal>ls</literal>, you should see - <literal>phpdoc</literal> listed). - </para> - - <para> - Type <literal>mkdir phpdoc-tools</literal>, and then unzip: - - <itemizedlist> - <listitem><simpara>Jade to <literal>phpdoc-tools/jade</literal></simpara></listitem> - <listitem><simpara>Norman Walsh's DSSSL files to <literal>phpdoc-tools/dsssl/docbook</literal></simpara></listitem> - <listitem><simpara>the ISO-entities to <literal>phpdoc-tools/iso-entities</literal></simpara></listitem> - </itemizedlist> - - XSL stylesheets are <emphasis>not necessary</emphasis> - to generate the html versions of the manual, the DSSSL style - sheets are used by default. If you think you would like - to test XSL ones, than unzip Norman Walsh's - XSL files to <literal>phpdoc-tools/xsl/docbook</literal>. See - <ulink url="&url.nwalsh.xsl;">&url.nwalsh.xsl;</ulink> - for more information and downloadable files. - </para> - - <para> - Verify that your directory structure looks like this: - <informalexample> - <programlisting> -+--phpdoc -| | -| +--CVS -| | -| +--en -| | -| +--... -| -+--phpdoc-tools - | - +--dsssl - | | - | +--docbook (with docbook.dcl etc) - | - +--iso-entities (with ISOamsa etc) - | - +--jade (with jade.exe etc) - | - +--xsl (OPTIONAL!) - | - +--docbook (etc) - </programlisting> - </informalexample> - </para> - - <para> - Now go to the <literal>phpdoc</literal> directory, and execute: - <informalexample> - <programlisting> -autoconf -./configure --with-lang=your_language_code - </programlisting> - </informalexample> - Substitute <literal>your_language_code</literal> with - a language code you checked out the files of, - and would like to work on. The - <literal>--with-lang</literal> parameter is - optional. If you don't specify it, the default is - <literal>en</literal> (English). - </para> - - <para> - If you didn't get any errors, you're ready to rock&roll. - Otherwise, you could check out the - <ulink url="&url.docbook.appa;">installation appendix</ulink> - of "DocBook: The Definitive Guide". - </para> - - </sect3> - </sect2> - - <sect2 id="tools-for-xsl"> - <title>Tools for XSL Stylesheets</title> - - <para> - In order to successfully use the XSL stylesheets - you must have some XSLT processor and the XSL - DocBook Stylesheets. This is sufficient for - generating HTML version of the documentation. - If you also want to create a version suitable - for printing, you will additionally need a - FO processor. - </para> - - <para> - This is an operating system independent section, - as most of the tools are written in the Java - language, or provide a version in Java. This means, - you can run them on virtually any operating system, - where a Java Virtual Machine is available. See the - <ulink url="&url.sunjava;">Java homepage</ulink> - for more information. - </para> - - <note> - <para> - Using XSL stylesheets to generate different formats - of the <literal>phpdoc</literal> XML files is - <emphasis>optional</emphasis> currently. This method - is not as well supported as DSSSL stylesheets, - but is a promising technology. You do not need - to setup any tools mentioned here if you would - not like to play with XSL stylesheets. - </para> - </note> - - <para> - XSLT processors: - <itemizedlist> - <listitem> - <simpara> - XT: <ulink url="&url.xsl.xt;">&url.xsl.xt;</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - Xalan: <ulink url="&url.xsl.xalan;">&url.xsl.xalan;</ulink> - </simpara> - </listitem> - </itemizedlist> - </para> - - <para> - XSL DocBook Stylesheets: <ulink url="&url.xsl.style;">&url.xsl.style;</ulink> - </para> - - <para> - FO processors: - <itemizedlist> - <listitem> - <simpara> - PassiveTeX: <ulink url="&url.xsl.passivetex;">&url.xsl.passivetex;</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - FOP: <ulink url="&url.xsl.fop;">&url.xsl.fop;</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - XEP: <ulink url="&url.xsl.xep;">&url.xsl.xep;</ulink> - </simpara> - </listitem> - </itemizedlist> - </para> - - </sect2> - </sect1> - - - - <sect1 id="phpdoc-files"> - <title>File Overview</title> - - <para> - 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: - <variablelist> - <varlistentry> - <term><filename>manual.xml</filename></term> - <listitem> - <simpara> - 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. - </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>chapters.ent</filename></term> - <listitem> - <simpara> - Contains entity definitions for all chapters and - appendices. Entities for the XML files are generated - by configure, so <emphasis>you should not edit this file</emphasis>. - </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>global.ent</filename></term> - <listitem> - <simpara> - Global internal text entities for all the XML - files. This is where all the external links, - email addresses, and "macros" are stored. - </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>your_language/language-defs.ent</filename></term> - <listitem> - <simpara> - Contains local entities used by this language. - Some common ones are the main part titles, but - you should also put entities used only by this - language's files here. - </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>your_language/language-snippets.ent</filename></term> - <listitem> - <simpara> - Longer often used XML snippets translated to this - language. Including common warnings, notes, etc. - </simpara> - </listitem> - </varlistentry> - </variablelist> - </para> - - </sect1> - - - - <sect1 id="cvs"> - <title>Working with CVS</title> - - <para> - The PHP documentation is maintained using <ulink - url="&url.cvs;">CVS</ulink> (<emphasis>Concurrent - Versions System</emphasis>). CVS allows the documentation - contributors to make changes to the different files that make up - the PHP documentation without stepping on each other's toes. - </para> - - <para> - A CVS system contains a central server, where all the files - are stored. A CVS server can host many repositories, - the name of the repository used by the PHP Documentation - people is <literal>phpdoc</literal>. To access this - server, you need a CVS client program on your system. - </para> - - <para> - When you decide to work on a file, you need to check - it out (~download the file). Then you can make modifications - on the file on your local copy. If you are ready, you - need to commit the changes (~upload the new file). The CVS - client asks for your short comment about why this commit - was neccesary. You can give here a summary about what was - changed. The CVS server stores the history of files with - these commit messages. Everybody can then see what was - modified by you, because all modifications generate a diff - posted to the phpdoc mailing list, and the history is also - viewable with a CVS client or the web interface at - <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. You can - also delete a file or add one with your CVS client, - if you see it is needed. - </para> - - <para> - This section is not intended to be a CVS tutorial, only a quick - walkthough to help you get started checking out out the - <literal>phpdoc</literal> tree and commiting your changes. - The complete CVS documentation and can be found at <ulink - url="&url.cvs;">&url.cvs;</ulink>. - </para> - - <para> - CVS tutorials can be found at: - <itemizedlist> - <listitem> - <simpara><ulink url="&url.cvstut1;">&url.cvstut1;</ulink></simpara> - </listitem> - <listitem> - <simpara><ulink url="&url.cvstut2;">&url.cvstut2;</ulink></simpara> - </listitem> - </itemizedlist> - </para> - - <para> - You can also type <literal>man cvs</literal> anytime - you would like to get help about your CVS client. This - brings up a help text called a "manpage". - </para> - - <sect2 id="cvs-account"> - <title>Obtaining a CVS Account</title> - - <para> - First, before you can actually make documentation changes, you - need write access to the <ulink url="&url.php.cvs;">cvs.php.net</ulink> - CVS repository. You can always checkout a module anonymously, - but you can not commit changes unless you have an account. - If you only would like to check files out, you can use - the read only user name and password. See - <ulink url="&url.php.anoncvs;">&url.php.anoncvs;</ulink> - for more information. - </para> - - <para> - Also note, that if you have a CVS account on our server, - you may have no write access to the <literal>phpdoc</literal> - module. The Karma system controls who have access to what - repository, so if you have a CVS account but have no Karma - to write to <literal>phpdoc</literal>, please ask for Karma - at <ulink url="mailto:&email.group.php;">&email.group.php;</ulink>. - Note, that who has Karma to write to the PHP source tree, - has Karma to <literal>phpdoc</literal> as well. - </para> - - <para> - Obtaining a CVS account at php.net isn't difficult, but you need - to do two things: - <itemizedlist> - <listitem> - <simpara> - Send mail to <ulink - url="mailto:&email.group.php;">&email.group.php;</ulink>. - Explain what you would like to do with the CVS account - (contribute to the PHP documentation). Also give a little - information and background about yourself so the developers - understand where you are coming from. - </simpara> - </listitem> - <listitem> - <simpara> - Once someone from the development team responds to your e-mail, - you will need to go to <ulink - url="&url.php.cvsaccount;">&url.php.cvsaccount;</ulink> and fill - out the formal request form. - </simpara> - </listitem> - - </itemizedlist> - </para> - - <para> - Both of the above steps and other information about CVS accounts - at cvs.php.net can be found on the same page as the request form, - <ulink url="&url.php.cvsaccount;">&url.php.cvsaccount;</ulink>. - Note that this it not an automated process. If you receive no - reponse after days, do not hesitate to post your request again. - </para> - - </sect2> - - <sect2 id="login"> - <title>CVS Login</title> - <para> - Now that you have write access to the CVS repository, let's setup - a few variables in your <filename>.cvsrc</filename> file, add a - <literal>CVSROOT</literal> environment variable and - login to the CVS repository. - </para> - - <para> - If you don't already have a <filename>.cvsrc</filename> file in - your home directory, create one now and add the following lines to - it. Note that if you use Cygwin, your home directory opens - first, when running the bash shell (it is the home/username - directory under your cygwin install directory). - <informalexample> - <programlisting> -cvs -z3 -update -d -P -checkout -P -diff -u - </programlisting> - </informalexample> - </para> - - <para> - Each time you issue commands to the CVS repository, you have to - specify the repository's cvsroot directory like this: - <informalexample> - <programlisting> -$ cvs -d :pserver:<parameter>username</parameter>@cvs.php.net:/repository checkout <parameter>phpdoc</parameter> - </programlisting> - </informalexample> - </para> - - <para> - Instead of telling <command>cvs</command> where the repository is - each time, you can set a default CVS repository in your <literal - >CVSROOT</literal> environment variable. - </para> - - <para> - For <literal>sh</literal> and <literal>bash</literal> - users add the following to your <filename>.bashrc</filename> - or <filename>.profile</filename> file. - <informalexample> - <programlisting> -CVSROOT=:pserver:<parameter>username</parameter>@cvs.php.net:/repository -export CVSROOT - </programlisting> - </informalexample> - </para> - - <para> - For <literal>csh</literal> and <literal>tcsh</literal> - users add the following to your <filename>.cshrc</filename> - or <filename>.tcshrc</filename> file. - <informalexample> - <programlisting> -setenv CVSROOT :pserver:<parameter>username</parameter>@cvs.php.net:/repository - </programlisting> - </informalexample> - </para> - - <note> - <para> - The <literal>CVSROOT</literal> environment variable - won't be set until the next time you log in. - </para> - </note> - - <para> - If you use Windows, use your regular way to add the new - environment variable, according to the Windows version - you are using (use the <command>set</command> command - on Windows 9x, or the Dialog box for setting environment - variables on Windows 2000). - </para> - - <para> - Now that you have the prep work out of they way, you will need to - login to the CVS repository. Issue the following command: - <informalexample> - <programlisting> -$ cvs login - </programlisting> - </informalexample> - </para> - - <para> - Or, if you don't have your <literal>CVSROOT</literal> - set, make sure you supply the correct <literal>cvsroot</literal>: - <informalexample> - <programlisting> -$ cvs -d :pserver:<parameter>username</parameter>@cvs.php.net:/repository login - </programlisting> - </informalexample> - </para> - - <para> - Change the <parameter>username</parameter> above to your own - CVS user name. You will be asked to supply your password. Once - you successfully login to the CVS respository, your encrypted - password is stored in the <filename>.cvspass</filename> file - in your home directory. You won't need to log back into the - same repository again unless you delete that file (or - issue a <literal>cvs logout</literal>). - </para> - - </sect2> - - <sect2 id="checkout"> - <title>Checking Out a Module</title> - - <para> - Now it's time to checkout the <parameter>phpdoc</parameter> - module. Incidently, a module is a collection of source - directories and files. Usually it's simply a directory tree in - the CVS repository. - </para> - - <para> - <command>cd</command> to a directory you wish to store the - <literal>phpdoc</literal> tree under. Wherever you decide to - put it, a <filename>phpdoc</filename> directory will be created - there. Issue the following command: - <informalexample> - <programlisting> -$ cvs checkout <parameter>phpdoc</parameter> - </programlisting> - </informalexample> - </para> - - <para> - After some status information about the checkout scrolls by, you - should have a full working copy of the <literal>phpdoc</literal> - module. - </para> - - <note> - <para> - You are not completely free to decide where this - <filename>phpdoc</filename> directory should be. See the - <link linkend="tools-setup">Tools and Setup Instructions</link> - section for more precise information about whether the - place of this <filename>phpdoc</filename> directory - is restricted on your system or not. - </para> - </note> - - </sect2> - - <sect2 id="update"> - <title>Updating the Tree</title> - - <para> - It's a good idea from time to time to update your copy of the - <parameter>phpdoc</parameter> tree so that you always have the - latest copy. Currently, changes to the tree are made daily so you - should always update your copy before making changes yourself. - </para> - - <para> - To update your copy, <command>cd</command> to the - <filename>phpdoc</filename> directory and issue the following - command: - <informalexample> - <programlisting> -$ cvs update - </programlisting> - </informalexample> - </para> - - <para> - If you only wish to update a particular file or set of files you - would like to modify, you can pass their filenames along with the - update command: - <informalexample> - <programlisting> -$ cvs update <parameter>file1</parameter> <optional><parameter>file2</parameter></optional> - </programlisting> - </informalexample> - </para> - - <para> - If the files are located beneath the top level - <filename>phpdoc</filename> directory, use the relative paths of - the filenames: - <informalexample> - <programlisting> -$ cvs update <parameter>en/functions/file1</parameter> <optional><parameter>en/chapters/file2</parameter></optional> - </programlisting> - </informalexample> - </para> - - </sect2> - - <sect2 id="status"> - <title>Checking the Status of Files</title> - - <para> - If you've made several changes to your local copy of - <literal>phpdoc</literal> and would like to see what files - have been modified, you can ask <command>cvs</command> what the - current status of the file or files is. - </para> - - <para> - To see the status of all files in the current directory, issue the - following command: - <informalexample> - <programlisting> -$ cvs status -l - </programlisting> - </informalexample> - </para> - - <para> - This will usually generate a huge list, but you can narrow down - the status information by supplying <command>cvs</command> - specific filenames to check the status of: - <informalexample> - <programlisting> -$ cvs status <parameter>file1</parameter> <optional><parameter>file2</parameter></optional> - </programlisting> - </informalexample> - </para> - - <para> - <example> - <title><command>cvs status</command> example</title> - <screen> -$ cvs status -l phpdoc/howto/howto.xml -=================================================================== -File: howto.xml Status: Locally Modified - - Working revision: 1.6 - Repository revision: 1.6 /repository/phpdoc/howto/howto.xml,v - Sticky Tag: (none) - Sticky Date: (none) - Sticky Options: (none) - </screen> - </example> - </para> - - </sect2> - - <sect2 id="commit"> - <title>Commiting Changes</title> - - <para> - Once you have made changes to a file and <emphasis>validated - your XML</emphasis>, you are ready to commit the changes - to the CVS repository. - </para> - - <para> - When commiting a file or files to the repository, it is polite to - supply a brief message of what you have changed. You do not need - to document every single line you changed, that is part of CVS' - job. However, it is helpful to see a brief summary of what has - changed from version to version without having to study the file - itself. - </para> - - <para> - To commit a file, issue the following command: - <informalexample> - <programlisting> -$ cvs commit -m 'added new blah() function' <parameter>file1</parameter> <optional><parameter>file2</parameter></optional> - </programlisting> - </informalexample> - </para> - - <para> - Sometimes it is more convinient to ommit the - <parameter>-m</parameter> parameter, as this way - CVS opens a text editor and you can type in - your comments there. If you would like to add - more comments, you can't express on one line - using <parameter>-m</parameter>, choose this way. - </para> - </sect2> - - <sect2 id="add"> - <title>Adding files</title> - - <para> - It is sometimes needed to add files to the English files - (eg. adding a new appendix), and it is initial for - translations (adding translated files). To add a file - you need to put that file to the proper place, where - you want it to be. - </para> - - <para> - To add a file, issue the following command: - <informalexample> - <programlisting> -$ cvs add <parameter>file1</parameter> <optional><parameter>file2</parameter></optional> - </programlisting> - </informalexample> - </para> - - <para> - This only shedules the file for addition. To - complete the addition of the file(s), you need - to do a commit, as described above. - </para> - - <warning> - <para> - Before adding new files, you should choose the new - file name carefully. There are some limitations to - file names, because the automatic file name -> - entity name conversion. - </para> - </warning> - </sect2> - - <sect2 id="remove"> - <title>Removing files</title> - - <para> - It is sometimes needed to remove files from the - repository. CVS stores the whole history of the - files, so deleting is not an irreversible step. - Please be careful when deleting files though. - A file may be needed for the build process, or - can store important information for other people. - </para> - - <para> - To remove a file, first remove the file from your - local copy of the CVS repository, and issue the - following command: - <informalexample> - <programlisting> -$ cvs remove <parameter>file1</parameter> <optional><parameter>file2</parameter></optional> - </programlisting> - </informalexample> - </para> - - <para> - This only shedules the file for removing. To - complete the removing of the file(s), you need - to do a commit, as described above. - </para> - - </sect2> - </sect1> - - - - <sect1 id="generating-docs"> - <title>Validating Your Changes and Generating Documentation</title> - - <para> - An important part of making contributions to the PHP documentation - is being able to validate your changes and to be able to see what - they will look like in their various forms, whether that is in - HTML, Adobe PDF, RTF or other format. - </para> - - <sect2 id="the-makefile"> - <title>The Makefile</title> - - <para> - The <filename>Makefile</filename> controls serveral aspects - of how documenation is validated and created. To generate a - <filename>Makefile</filename> from a fresh checkout, - <command>cd</command> to the <filename>phpdoc</filename> - directory and issue the following commands: - <informalexample> - <programlisting> -$ autoconf - -$ ./configure - </programlisting> - </informalexample> - This will generate a current <filename>Makefile</filename> for - your copy of the <emphasis>phpdoc</emphasis> tree. - </para> - - <para> - Note that if you are using Windows, these commands - only work in the Cygwin bash shell. - </para> - - </sect2> - - <sect2 id="validating-changes"> - <title>Validating Changes</title> - - <para> - Now that you have a Makefile, you can validate the - documenation changes you have previously made: - <informalexample> - <programlisting> -$ cd phpdoc -$ make test - </programlisting> - </informalexample> - </para> - - <para> - Which will generate output similar to this: - </para> - <para> - <screen> -touch .manual.xml -CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status -creating manual.xml -nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml - </screen> - </para> - - <para> - If you made a mistake such as forgetting to close a tag or using - an invalid tag name, <command>make test</command> will report the - error and give you the line number it found it at. - </para> - <para> - <screen> -touch .manual.xml -CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status -creating manual.xml -nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml -nsgmls:en/functions/strings.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified -make: *** [test] Error 1 - </screen> - </para> - <para> - In the above example output, the parser expected to see an end tag - for <para> at line 54 in the file - <filename>en/functions/strings.xml</filename>. - Using this information, you can go back to the file and correct - the mistake before committing your changes. - </para> - - <para> - It is important to do a test before commiting, because if you - commit files with errors, this single file will cause the automatic - build process to halt, and the manual files and downloads - wont be updated online. This can make phpdoc people angry. - </para> - </sect2> - - <sect2 id="viewing-your-changes"> - <title>Viewing Your Changes</title> - - <para> - There are several stylesheets available for generating viewable - documentation, the most useful will probably be: - <itemizedlist> - <listitem> - <para> - <literal>html</literal>, the plain html manual found at <ulink - url="&url.php.manual.plain;">&url.php.manual.plain;</ulink> - </para> - </listitem> - <listitem> - <para> - <literal>bightml</literal>, one big HTML file, only available for download at <ulink - url="&url.php.docdownload;">&url.php.docdownload;</ulink> - </para> - </listitem> - <listitem> - <para> - <literal>phpweb</literal>, the main PHP online manual found at <ulink - url="&url.php.manual;">&url.php.manual;</ulink> - </para> - </listitem> - <listitem> - <para> - <literal>pdf</literal>, a PDF version of the manual found at <ulink - url="&url.php.manual.pdf;">&url.php.manual.pdf;</ulink> - </para> - </listitem> - <listitem> - <para> - <literal>rtf</literal>, a RTF (Rich Text Format) version of the manual, - currently not available online - </para> - </listitem> - <listitem> - <para> - <literal>howto</literal>, this HOWTO document in a simple HTML format: - <ulink url="&url.php.howto;">&url.php.howto;</ulink> - </para> - </listitem> - </itemizedlist> - </para> - - <para> - To generate a viewable copy of the documenation, - <command>cd</command> to the <filename>phpdoc</filename> directory - and issue one of the following commands: - <informalexample> - <programlisting> -$ make html -$ make bightml -$ make phpweb -$ make pdf -$ make rtf - </programlisting> - </informalexample> - To make an actual copy of this HOWTO: - <informalexample> - <programlisting> -$ make howto - </programlisting> - </informalexample> - The plain text version of the PHP documentation is made - by filtering the <literal>bightml</literal> output through lynx. - </para> - - <note> - <para> - Generating viewable documentation is CPU intensive and can take a - little while to complete. E.g. generating the simple HTML - manual takes about 7m 30s on a 700MHz box. - </para> - </note> - - <para> - Where the output files are placed depends on the format you - built. HTML manuals generate in the <filename>html</filename> - subdirectory of <literal>phpdoc</literal>, similarly the - <literal>make phpweb</literal> command will place the files - in the <filename>php</filename> directory. The place for - the HOWTO HTML files is <filename>howto/html</filename>. - </para> - - <para> - If all goes well, you should have your own copy of the - documentation, including any changes you've made. - </para> - - </sect2> - - <sect2 id="using-xsl-stylesheets"> - <title>Using XSL Stylesheets</title> - - <para> - Currently using XSL stylesheets to generate output - of XML files is not as well supported as using DSSSL - style sheets. This is because XSL stylesheets are not - as customized as DSSL ones, and XSL tools are not as - widely used, and standardized. - </para> - - <para> - At this time there are no XSL specific targets in - <filename>Makefile</filename>. This is because there - are not standardized ways to invoke XSLT processors. - To use XSL stylesheets you must run the - <filename>configure</filename> script and tell it, - where your copy of XSL DocBook Stylesheets is placed. - The majority of XSLT processors require an URL instead - of a filename, so be sure to prepend - the <literal>file:///</literal> schema before path: - <informalexample> - <programlisting> -$ autoconf -$ ./configure --with-xsl=file:///path/to/docbook/xsl/styles - </programlisting> - </informalexample> - </para> - - <para> - Configure will create four files: - <filename>html.xsl</filename>, - <filename>bightml.xsl</filename>, - <filename>htmlhelp.xsl</filename>, - <filename>print.xsl</filename> among others. These files - can be used to generate the desired output. - <filename>html.xsl</filename> generates a set of small - HTML files, <filename>bightml.xsl</filename> generates - one large HTML file, <filename>htmlhelp.xsl</filename> - generates source files processable by HTML Help Workshop - and <filename>print.xsl</filename> generates a file - with FO objects suitable for further processing with - some FO processor. - </para> - - <para> - Invocation of XSLT processor is processor dependent, - for now suppose that you have a shell script called - <filename>saxon</filename> which is able to invoke the - Saxon processor. Some examples: - <informalexample> - <programlisting> -$ mkdir html -$ saxon manual.xml html.xsl -$ saxon manual.xml htmlhelp.xsl -$ saxon -o bigmanual.html manual.xml bightml.xsl -$ saxon -o manual.fo manual.xml print.xsl - </programlisting> - </informalexample> - Use the appropriate command from the examples above - to generate the desired output as described above. - If you would like to generate HTML Help output, you - must run the Microsoft HTML Help Compiler after - processing. To get a PDF from the FO file, you must - run some FO processor on the - <filename>manual.fo</filename> file. - </para> - - <note> - <para> - Generating <filename>bigmanual.html</filename> with Saxon - (using JDK 1.3) takes about two minutes on a Celeron 400 - computer. Generating FO files takes about two times more - + plus time required to run the FO processor. Generating - chunked version or HTML Help version of manual takes about - 60 minutes. - </para> - </note> - - <note> - <para> - Not all customization from DSSSL are backported to XSL, - so some things are not as pretty as in DSSSL output - <emphasis>currently</emphasis>. - </para> - </note> - </sect2> - </sect1> - - - - <sect1 id="docbook"> - <title>DocBook XML documents</title> - - <sect2> - <title>DocBook for Native Speakers of HTML</title> - <para> - 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. - </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. - </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, - plase do not translate tags, as they need to stay as they - was written in the English files to work properly. - </para> - </sect2> - - <sect2> - <title>DocBook reference</title> - <para> - For information about the DocBook DTD, look here: - <ulink url="&url.docbook-dtd;">&url.docbook-dtd;</ulink>. - </para> - <para> - There is a DTD reference for DocBook at: - <ulink url="&url.docbook-dtdref;">&url.docbook-dtdref;</ulink>. - </para> - <para> - Get Going With DocBook, Notes for Hackers: - <ulink url="&url.docbook-intro;">&url.docbook-intro;</ulink>. - </para> - </sect2> - </sect1> - - - - <sect1 id="working-with-emacs"> - <title>Working with Emacs</title> - - <para> - How to work with emacs, manual.ced, commands, etc. - </para> - - <sect2 id="emacs-configuration"> - <title>Configuration</title> - <para> - </para> - </sect2> - - <sect2 id="emacs-basic-commands"> - <title>Basic Commands</title> - <para> - If you are using PSGML, it can help you a lot finding out - what tags you can use where. By pressing - <keycombo><keysym>C-c</keysym> <keysym>C-e</keysym></keycombo> - <footnote><simpara>C-<replaceable>x</replaceable> is Emacs's way - of saying you should press <keysym>Control</keysym> and the - <keycode>x</keycode> key.</simpara></footnote> - </para> - </sect2> - - <sect2 id="emacs-working-with-sgml"> - <title>Working With SGML</title> - <para> - </para> - </sect2> - - </sect1> - - - - - - <sect1 id="working-with-vi"> - <title>Working with vi</title> - - <para> - How to work with vi, manual.ced, commands, etc. - </para> - - <sect2 id="vi-configuration"> - <title>Configuration</title> - <para> - </para> - </sect2> - - <sect2 id="vi-basic-commands"> - <title>Basic Commands</title> - <para> - </para> - </sect2> - - <sect2 id="vi-working-with-sgml"> - <title>Working With SGML</title> - <para> - </para> - </sect2> - - </sect1> - - - - <sect1 id="conventions"> - <title>Conventions</title> - - <para> - When you work on <literal>phpdoc</literal> XML files, - you should stick to these conventions, to ease the team - work in the repository. - </para> - - <para> - <orderedlist> - <listitem><simpara> - Insert ID attributes in all major section tags such - as part, chapter, sect1 etc. The HTML stylesheet will - name the HTML files after these IDs. - </simpara></listitem> - <listitem><simpara> - Function reference IDs look like this (case should - be consistent with the rest of the function naming - standards, i.e. lowercase): <literal>function.imageloadfont</literal>. - Please note that since underscores cannot be used - in IDs, they should be replaced by minus signs (-). - </simpara></listitem> - <listitem><simpara> - Function section IDs - (<literal><reference id="..."></literal>) look - like this: 'ref.category', for example: 'ref.ftp'. - </simpara></listitem> - <listitem><simpara> - The contents of examples with program listings - start on column 0 in the XML code. - </simpara></listitem> - <listitem><simpara> - All examples use the <literal><?php ... ?></literal> - form instead of <literal><? ... ?></literal>. It - can be useful to use <literal><![CDATA[ ... ]]></literal> - for examples, since it eliminates the need to change - <literal><</literal> to <literal>&lt;</literal>, etc. - </simpara></listitem> - <listitem><simpara> - Indenting, bracketing and naming conventions in - examples should adhere to the PEAR coding standards - (it's in the manual). Deprecated aliases and syntax - should not be used in examples. - </simpara></listitem> - <listitem><para> - If an example uses arguments specific to a newer version of - PHP, it is helpful to note this in the example: - <programlisting> -foo("bar", "baz"); // second argument was added in PHP 4.0.3 - </programlisting> - New arguments are denoted in the main text of the - entry using the form - <programlisting> -<![CDATA[ -<note> - <simpara> - The second parameter was added in PHP 4.0.3. - </simpara> -</note> -]]> - </programlisting> - </para></listitem> - <listitem><simpara> - The language constants true, false and null - should be written as <literal>&true;</literal>, - <literal>&false;</literal> and - <literal>&null;</literal>. - </simpara></listitem> - <listitem><simpara> - All English XML files should have a <literal></literal> comment as the first line - unless they contain an <literal><?xml</literal> tag, in which - case the revision comment should be on the second - line. Non-English files should not have this comment. - </simpara></listitem> - <listitem><simpara> - Whitespace changes in the English tree should be - prevented as much as possible: it is more important - to keep a good change-history of real changes, because - of the translations. If a whitespace change is - <emphasis>really</emphasis> needed, do it at least - in a separate commit, with a clear comment such as - 'WS fix' or 'Whitespace fix'. - </simpara></listitem> - <listitem><simpara> - Never use tabs, not even in example program - listings. XML should be indented with one - space character for each level of indentation; - example code uses four spaces (see PEAR standards). - </simpara></listitem> - <listitem><simpara> - Always use LF (Line Feed) for the only newline - character in files, this is the Unix standard. - Never use CR LF (Windows) or CR (Mac) even, when - editing Windows specific files (such as - *.bat). It eases the editing works. - </simpara></listitem> - <listitem> - <simpara> - In the docs, the types are denoted as: - <literal>boolean</literal> (<literal>bool</literal> - in prototypes), <literal>integer</literal> - (<literal>int</literal> in prototypes), - <literal>float</literal> (<emphasis>not - double!</emphasis>), <literal>array</literal>, - <literal>object</literal> (<emphasis>not class!</emphasis>), - <literal>resource</literal> and <literal>null</literal> - (all lowercase). - </simpara> - - <simpara> - In prototypes, you can also use <literal>mixed</literal> - (various types), or <literal>number</literal> (either - integer or float), or <literal>scalar</literal> (boolean, - integer, float or string). A callback is denoted as - <literal>mixed</literal> <footnote><simpara>Better - suggestions? I don't really like it this way... not - simply <literal>function</literal>, or something alike? - --Jeroen</simpara></footnote>, since it can be either - array or string. - </simpara> - - <simpara> - If a function requires no arguments, use - <literal><void/></literal> instead of - <literal><parameter>void</parameter></literal>, - since the former is the correct DocBook XML tag. - </simpara> - - <simpara> - If a function has an undefined return-value, use - the word <literal>void</literal>. - </simpara> - </listitem> - <listitem><simpara> - In a prototype, if there are multiple - really - distinct - possibilities, simply make it two! - See <literal>math.xml:min()</literal> for an example. - </simpara></listitem> - <listitem><simpara> - Aliases: in refpurpose, put: - <literal>Alias of <function>realfunc</function></literal>. - <emphasis>Do not specify a funcsynopsis, and - nothing but simply the text:</emphasis> - <literal>This function is an alias of - <function>realfunc</function></literal>. - This way, people can click to realfunc - straight from the <literal>ref.foo</literal> page. - </simpara></listitem> - </orderedlist> - </para> - </sect1> - - - - <sect1 id="what-to-document"> - <title>What to Document?</title> - - <para> - <orderedlist> - <listitem> - <simpara> - Only major functions should be documented; functions which are - deprecated variants may be mentioned, but should not be - documented as separate functions. They instead should be - referenced in the parent function as an alias. Functions which - have completely different names, however, should be documented as - separate entries, for ease of reference. The aliases.xml appendix - is the place to store aliases not documented elsewhere. - </simpara> - - <simpara> - For example <literal>mysql_db_name</literal> and - <literal>mysql_dbname</literal> will be documented as the same - function, with the latter being listed as an alias of the - former, while <literal>show_source</literal> and - <literal>highlight_file</literal> will be documented as two - different functions (one as an alias), as the names are - completely different, and one name is not likely to be found - if looking for the name of the other. - </simpara> - </listitem> - <listitem> - <simpara> - Function names should be created, and documented, in lowercase - format with an underscore separating the name components. If - there are several variants, use the one with the least amount - of components. - </simpara> - <simpara> - Good: <literal>mcrypt_enc_self_test</literal>, - <literal>mysql_list_fields</literal> - </simpara> - <simpara> - OK: <literal>mcrypt_module_get_algo_supported_key_sizes</literal> - (could be <literal>mcrypt_mod_get_algo_sup_key_sizes</literal>?), - <literal>get_html_translation_table</literal> - (could be <literal>html_get_trans_table</literal>?) - </simpara> - <simpara> - Bad: <literal>hw_GetObjectByQueryCollObj</literal>, - <literal>pg_setclientencoding</literal> - </simpara> - </listitem> - <listitem> - <simpara> - Functions which are kept only for backwards compatibility should - be listed under their current parent names, and not documented as - separate functions. Backwards compatible functions and - documentation for them should be maintained as long as the code - can be reasonably kept as part of the PHP codebase. Also see - the appendix <filename>aliases.xml</filename>. - </simpara> - </listitem> - <listitem> - <simpara> - Short code examples are much more desirable than long ones. - If a function is extremely complex, a suitable place to put - a longer example is in the chapter introduction. This example - can hold code for other functions in the same chapter. - </simpara> - </listitem> - <listitem> - <simpara> - Brevity is appreciated. Long winded descriptions of each and - every function are not appropriate for the reference sections. - Using the errata comments as guidelines, it's easier to tell when - more documentation is needed, as well as the inverse, when too - much documentation in one section has increased confusion. - </simpara> - </listitem> - </orderedlist> - </para> - </sect1> - - - - <sect1 id="doc-skeletons"> - <title>Documentation skeletons</title> - - <para> - Below are some "skeletons" to copy and paste from when adding - documentation. - </para> - <para> - <example> - <title>Function reference file in lang/functions/</title> - <programlisting> -<![CDATA[ - <reference> - <title></title> - <titleabbrev></titleabbrev> - - </reference> - -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Function reference entry</title> - <programlisting> -<![CDATA[ - <refentry id="function."> - <refnamediv> - <refname></refname> - <refpurpose></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>RETURNTYPE <function>FUNCTIONNAME</function></funcdef> - <paramdef>ARGTYPE1 <parameter>ARGNAME1</parameter></paramdef> - <paramdef>ARGTYPE2 <parameter>ARGNAME2</parameter></paramdef> - <paramdef>ARGTYPE3 - <parameter><optional>ARGNAME3</optional></parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - A simple paragraph that can not contain anything that requires - fancy layout. - </simpara> - <para> - A normal paragraph that can contain lots of stuff. For example - <example> - <title>Code examples</title> - <programlisting role="php"> -// Use CDATA is you would like to add lots of < to the code - -/* Do all indentation with spaces, not tabs, just to be sure. - * Don't try pushing the code to the right by adding spaces in - * front, this is the style sheet's job. - */ - -// a function example -function some_code($foo) -{ - /* use four spaces of indentation */ -} - -// an example of bracket usage and spacing, always use -// brackets, even when they are physically not needed -if (some_code($foo) == "foo") { - echo "foo"; -} elseif (some_code($foo) == "bar") { - echo "bar"; -} else { - echo "No foo, no bar"; -} - -// Include end of CDATA, if you started with CDATA - </programlisting> - </example> - - The text in a paragraph may continue after the example as well. - Here is how to make lists: - - <itemizedlist> - <listitem> - <simpara> - List items must contain a container element such as - simpara or para (there are plenty of others too, see the - DocBook reference for the listitem element. - </simpara> - </listitem> - - <listitem> - <simpara> - List items must contain simple paragraphs or paragraphs. - </simpara> - </listitem> - </itemizedlist> - - <itemizedlist> - <listitem> - <para> - If you plan on making sub-lists, you must use para - <orderedlist> - <listitem><simpara> first list item</simpara></listitem> - <listitem><simpara> second list item</simpara></listitem> - </orderedlist> - You can also continue an ordered list you just left off - <orderedlist> - <listitem><simpara> third list item</simpara></listitem> - <listitem><simpara> fourth list item</simpara></listitem> - </orderedlist> - </para> - </listitem> - </itemizedlist> - - </para> - <simpara> - The documentation for a function should be wrapped up with - a "See also" list like this: - </simpara> - <simpara> - See also <function>stripslashes</function> and - <function>quotemeta</function>. - </simpara> - </refsect1> - </refentry> -]]> - </programlisting> - </example> - </para> - <para> - For technical reasons, the CDATA start tag: <literal><![CDATA[</literal> - and the CDATA end tag: <literal>]]></literal> is not included - in the program code above, just the place of them are marked. - </para> - </sect1> - - - - <sect1 id="misc-notes"> - <title>Miscellaneous Notes</title> - - <para> - Misc. notes that don't need a full section. (stuff like - http://www.zend.com/phpfunc/, etc. - </para> - - </sect1> - -  - -</article> - +</book>  Index: phpdoc/howto/docbook.xml +++ phpdoc/howto/docbook.xml <?xml encoding="iso-8859-1"?> <chapter id="chapter-docbook"> <title>About the DocBook Standard</title> <sect1 id="docbook-whatis"> <title>What is DocBook?</title> <para> Quote from the introduction part of <ulink url="&url.docbook;">DocBook: The Definitive Guide</ulink>: </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. </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, optinally 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. </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. </para> </sect1> <sect1 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. </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. </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, plase do not translate tags, as they need to stay as they was written in the English files to work properly. </para> </sect1> <sect1 id="docbook-refs"> <title>DocBook reference</title> <para> For information about the DocBook DTD, look here: <ulink url="&url.docbook-dtd;">&url.docbook-dtd;</ulink>. </para> <para> There is a DTD reference for DocBook at: <ulink url="&url.docbook-dtdref;">&url.docbook-dtdref;</ulink>. </para> <para> Get Going With DocBook, Notes for Hackers: <ulink url="&url.docbook-intro;">&url.docbook-intro;</ulink>. </para> </sect1> </chapter>  Index: phpdoc/howto/editors.xml +++ phpdoc/howto/editors.xml <?xml encoding="iso-8859-1"?> <chapter id="chapter-emacs"> <title>Working with Emacs</title> <para> How to work with emacs, manual.ced, commands, etc. </para> <sect1 id="emacs-configuration"> <title>Configuration</title> <para> </para> </sect1> <sect1 id="emacs-basic-commands"> <title>Basic Commands</title> <para> If you are using PSGML, it can help you a lot finding out what tags you can use where. By pressing <keycombo><keysym>C-c</keysym> <keysym>C-e</keysym></keycombo> <footnote><simpara>C-<replaceable>x</replaceable> is Emacs's way of saying you should press <keysym>Control</keysym> and the <keycode>x</keycode> key.</simpara></footnote> </para> </sect1> <sect1 id="emacs-working-with-sgml"> <title>Working With SGML</title> <para> </para> </sect1> </chapter>  <chapter id="chapter-vi"> <title>Working with vi</title> <para> How to work with vi, manual.ced, commands, etc. </para> <sect1 id="vi-configuration"> <title>Configuration</title> <para> </para> </sect1> <sect1 id="vi-basic-commands"> <title>Basic Commands</title> <para> </para> </sect1> <sect1 id="vi-working-with-sgml"> <title>Working With SGML</title> <para> </para> </sect1> </chapter>  Index: phpdoc/howto/framework.xml +++ phpdoc/howto/framework.xml <?xml encoding="iso-8859-1"?> <chapter id="chapter-framework"> <title>The PHP Documentation Framework</title> <para> The PHP documentation is written in XML using the <link linkend="chapter-docbook">DocBook DTD</link>. If you would like to contribute to the PHP documentation work, you need to at least know the very basics of XML and DocBook. </para> <para> The XML files are stored on a central server, and can be reached with a <link linkend="chapter-cvs">CVS</link> client. There are many CVS clients out there, although we recommend one command line tool. </para> <para> You will need more programs and tools to manipulate the XML files and test their content for errors. What tools you need depends on the operating system you use. Linux or some sort of Unix is recommended, although many things in phpdoc works on Windows. You will find more information about the tools you need in the <link linkend="chapter-tools">tools</link> section. </para> <para> If you have problems not covered in this document, write in to <email>&email.phpdoc;</email> and ask. </para> </chapter>  Index: phpdoc/howto/generating.xml +++ phpdoc/howto/generating.xml <?xml encoding="iso-8859-1"?> <chapter id="chapter-makefile"> <title>The Makefile</title> <para> An important part of making contributions to the PHP documentation is being able to validate your changes and to be able to see what they will look like in their various forms, whether that is in HTML, Adobe PDF, RTF or other format. </para> <para> The <filename>Makefile</filename> controls serveral aspects of how documenation is validated and created. To generate a <filename>Makefile</filename> from a fresh checkout, <command>cd</command> to the <filename>phpdoc</filename> directory and issue the following commands: <informalexample> <programlisting> $ autoconf $ ./configure </programlisting> </informalexample> This will generate a current <filename>Makefile</filename> for your copy of the <emphasis>phpdoc</emphasis> tree. </para> <para> Note that if you are using Windows, these commands only work in the Cygwin bash shell. </para> </chapter> <chapter id="chapter-validating"> <title>Validating Changes</title> <para> Now that you have a Makefile, you can validate the documenation changes you have previously made: <informalexample> <programlisting> $ cd phpdoc $ make test </programlisting> </informalexample> </para> <para> Which will generate output similar to this: </para> <para> <screen> touch .manual.xml CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status creating manual.xml nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml </screen> </para> <para> If you made a mistake such as forgetting to close a tag or using an invalid tag name, <command>make test</command> will report the error and give you the line number it found it at. </para> <para> <screen> touch .manual.xml CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status creating manual.xml nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml nsgmls:en/functions/strings.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified make: *** [test] Error 1 </screen> </para> <para> In the above example output, the parser expected to see an end tag for <para> at line 54 in the file <filename>en/functions/strings.xml</filename>. Using this information, you can go back to the file and correct the mistake before committing your changes. </para> <para> It is important to do a test before commiting, because if you commit files with errors, this single file will cause the automatic build process to halt, and the manual files and downloads wont be updated online. This can make phpdoc people angry. </para> </chapter> <chapter id="chapter-viewing"> <title>Viewing Your Changes</title> <para> There are several stylesheets available for generating viewable documentation, the most useful will probably be: <itemizedlist> <listitem> <para> <literal>html</literal>, the plain html manual found at <ulink url="&url.php.manual.plain;">&url.php.manual.plain;</ulink> </para> </listitem> <listitem> <para> <literal>bightml</literal>, one big HTML file, only available for download at <ulink url="&url.php.docdownload;">&url.php.docdownload;</ulink> </para> </listitem> <listitem> <para> <literal>phpweb</literal>, the main PHP online manual found at <ulink url="&url.php.manual;">&url.php.manual;</ulink> </para> </listitem> <listitem> <para> <literal>pdf</literal>, a PDF version of the manual found at <ulink url="&url.php.manual.pdf;">&url.php.manual.pdf;</ulink> </para> </listitem> <listitem> <para> <literal>rtf</literal>, a RTF (Rich Text Format) version of the manual, currently not available online </para> </listitem> <listitem> <para> <literal>howto</literal>, this HOWTO document in a simple HTML format: <ulink url="&url.php.howto;">&url.php.howto;</ulink> </para> </listitem> </itemizedlist> </para> <para> To generate a viewable copy of the documenation, <command>cd</command> to the <filename>phpdoc</filename> directory and issue one of the following commands: <informalexample> <programlisting> $ make html $ make bightml $ make phpweb $ make pdf $ make rtf </programlisting> </informalexample> To make an actual copy of this HOWTO: <informalexample> <programlisting> $ make howto </programlisting> </informalexample> The plain text version of the PHP documentation is made by filtering the <literal>bightml</literal> output through lynx. </para> <note> <para> Generating viewable documentation is CPU intensive and can take a little while to complete. E.g. generating the simple HTML manual takes about 7m 30s on a 700MHz box. </para> </note> <para> Where the output files are placed depends on the format you built. HTML manuals generate in the <filename>html</filename> subdirectory of <literal>phpdoc</literal>, similarly the <literal>make phpweb</literal> command will place the files in the <filename>php</filename> directory. The place for the HOWTO HTML files is <filename>howto/html</filename>. </para> <para> If all goes well, you should have your own copy of the documentation, including any changes you've made. </para> </chapter> <chapter id="chapter-using-xsl"> <title>Using XSL Stylesheets</title> <para> Currently using XSL stylesheets to generate output of XML files is not as well supported as using DSSSL style sheets. This is because XSL stylesheets are not as customized as DSSL ones, and XSL tools are not as widely used, and standardized. </para> <para> At this time there are no XSL specific targets in <filename>Makefile</filename>. This is because there are not standardized ways to invoke XSLT processors. To use XSL stylesheets you must run the <filename>configure</filename> script and tell it, where your copy of XSL DocBook Stylesheets is placed. The majority of XSLT processors require an URL instead of a filename, so be sure to prepend the <literal>file:///</literal> schema before path: <informalexample> <programlisting> $ autoconf $ ./configure --with-xsl=file:///path/to/docbook/xsl/styles </programlisting> </informalexample> </para> <para> Configure will create four files: <filename>html.xsl</filename>, <filename>bightml.xsl</filename>, <filename>htmlhelp.xsl</filename>, <filename>print.xsl</filename> among others. These files can be used to generate the desired output. <filename>html.xsl</filename> generates a set of small HTML files, <filename>bightml.xsl</filename> generates one large HTML file, <filename>htmlhelp.xsl</filename> generates source files processable by HTML Help Workshop and <filename>print.xsl</filename> generates a file with FO objects suitable for further processing with some FO processor. </para> <para> Invocation of XSLT processor is processor dependent, for now suppose that you have a shell script called <filename>saxon</filename> which is able to invoke the Saxon processor. Some examples: <informalexample> <programlisting> $ mkdir html $ saxon manual.xml html.xsl $ saxon manual.xml htmlhelp.xsl $ saxon -o bigmanual.html manual.xml bightml.xsl $ saxon -o manual.fo manual.xml print.xsl </programlisting> </informalexample> Use the appropriate command from the examples above to generate the desired output as described above. If you would like to generate HTML Help output, you must run the Microsoft HTML Help Compiler after processing. To get a PDF from the FO file, you must run some FO processor on the <filename>manual.fo</filename> file. </para> <note> <para> Generating <filename>bigmanual.html</filename> with Saxon (using JDK 1.3) takes about two minutes on a Celeron 400 computer. Generating FO files takes about two times more + plus time required to run the FO processor. Generating chunked version or HTML Help version of manual takes about 60 minutes. </para> </note> <note> <para> Not all customization from DSSSL are backported to XSL, so some things are not as pretty as in DSSSL output <emphasis>currently</emphasis>. </para> </note> </chapter>  Index: phpdoc/howto/preface.xml +++ phpdoc/howto/preface.xml <?xml encoding="iso-8859-1"?> <preface id="preface"> <title>About This Document</title> <abstract> <para> This document contains information important for the PHP Documentation Group members. If you are interested in the documentation of PHP, you are at the wrong place, see <ulink url="&url.php.docs;">&url.php.docs;</ulink> for downloadable documentation. </para> <para> Currently this HOWTO is "under construction". When this document will be ready, you will find sections here about generating HTML documentation from XML sources, adding new XML files, or using XSL style sheets to process the source files. </para> <para> The latest copy of this HOWTO can be downloaded from the web at: <ulink url="&url.php.howto;">&url.php.howto;</ulink>. </para> </abstract> <sect1 id="disclaimer"> <title>Disclaimer</title> <para> No liability for the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility for that. </para> <para> All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. </para> <para> Naming of particular products or brands should not be seen as endorsements. </para> <para> You are strongly recommended to take a backup of your system before major installation and backups at regular intervals. </para> </sect1> <sect1 id="credits"> <title>Credits</title> <para> This document is based on many files, previously hosted in the phpdoc module at cvs.php.net, containg information about several distinct subjects, ranging from generating the HTML files from XML sources to starting a new translation. This is a central place for all these things. We tried to include the original authors in the authors list of this file. </para> </sect1> <sect1 id="feedback"> <title>Feedback</title> <para> Feedback is most certainly welcome for this document. Without your submissions and input, this document wouldn't exist. Please send your additions, comments and criticisms to the following email address: <email>&email.phpdoc;</email>. </para> </sect1> </preface>  Index: phpdoc/howto/tools.xml +++ phpdoc/howto/tools.xml <?xml encoding="iso-8859-1"?> <chapter id="chapter-tools"> <title>Tools and Setup Instructions</title> <para> What tools you need depends on the operating system you use. Linux or some sort of Unix is recommended, although many things in phpdoc works on Windows. The very basic things you need to work: <itemizedlist> <listitem><simpara>CVS account</simpara></listitem> <listitem><simpara>CVS client</simpara></listitem> <listitem><simpara>Text editor</simpara></listitem> </itemizedlist> The basic process is to check out (~download) the file using the CVS client, then edit it, and finally commit (~upload) it to the server. Of course you can find better tools to edit XML files than a simple text editor, it is just the absolute minimum. Some more useful tools: <itemizedlist> <listitem><simpara>XML [capable] editor</simpara></listitem> <listitem><simpara>Tools to test the edited file</simpara></listitem> </itemizedlist> In the folowing paragraphs, you can find information about how to obtain these tools and how to make them work for you. </para> <para> The last item in the above list (test the edited file) is the hardest to get working, as you need a copy of the English and your translations language files from the phpdoc tree. Also you need to set up the DocBook files, and several other tools. The viewable manual, and other formats such as PDF and RTF, are created using <ulink url="&url.jade;">Jade</ulink> and <ulink url="&url.nwalsh;">Norman Walsh's Modular DocBook Stylesheets</ulink>. There are other tools used to produce some other formats and files. It is recommended to set up the style sheets and Jade to be able to test your contributions. Otherwise you can easily cause headaches to other team members. </para> <para> <emphasis> If you have information about other good XML editors and/or tools not mentioned here, please send it to the maintainer: <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>. </emphasis> </para> <sect1 id="tools-on-linux"> <title>Tools on Linux</title> <para> Although many tools are preinstalled on the majority of the Linux systems, we collected some useful information about how they can be obtained and installed, if your system misses them. </para> <para> You will need your favorite text editor and a working <link linkend="chapter-cvs">CVS</link> installation. Although it is possible to use a simple text editor such as vi to write the XML files, it is recommended to use an XML/SGML editor that helps you along and makes sure your document is proper XML conforming to the used document type definition (DTD). A very good (and free) XML/SGML editor is Emacs+PSGML. Both Emacs and CVS are already part of just about every Linux distribution available. </para> <para> You will also need <ulink url="&url.autoconf;">autoconf</ulink> to build the phpdoc GNU configure script. Many distributions come with autoconf already installed. The latest copy can be found at: <itemizedlist> <listitem> <simpara><ulink url="&url.autoconf.ftp;">&url.autoconf.ftp;</ulink></simpara> </listitem> </itemizedlist> </para> <sect2 id="tools-on-linux-obtaining"> <title>Obtaining the Tools</title> <para> To simplify the installation process of the tools necessary to 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 <ulink url="&url.rpm;">RPM</ulink> installed on the machine you wish to install these tools on. </para> <para> These tools are all separate 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 the author's separate packages is out of the scope of this HOWTO. </para> <para> The RPMs with the necessary software can be downloaded from one of the following URLs: </para> <para> <itemizedlist> <listitem> <simpara> <ulink url="&url.docbookmirror1;">&url.docbookmirror1;</ulink> </simpara> </listitem> <listitem> <simpara> <ulink url="&url.docbookmirror2;">&url.docbookmirror2;</ulink> </simpara> </listitem> </itemizedlist> </para> <para> You will need to download the following files: <itemizedlist> <listitem><simpara>docbook-3.x-5.src.rpm</simpara></listitem> <listitem><simpara>jade-1.2.x-4.src.rpm</simpara></listitem> <listitem><simpara>jadetex-2.x-0.src.rpm</simpara></listitem> <listitem><simpara>psgml-1.2.x-1.src.rpm</simpara></listitem> <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem> <listitem><simpara>stylesheets-0.10-2.src.rpm</simpara></listitem> </itemizedlist> </para> <para> These packages are updated from time to time. Please make sure you download the latest version available from the above sites (the actual file names may change, so if you find newer files than mentioned above, please report, and we can update this list). </para> <note> <para> We currently use DocBook 3.1.7 (not the latest version) for writing phpdoc files. This is because there are incompatibilities between DocBook 3.x and 4.x currently not corrected in the documentation. Probably we will update the XML files, and move to DocBook 4.1.2 soon. </para> </note> </sect2> <sect2 id="tools-on-linux-installing"> <title>Installing the Tools</title> <para> Installing the tools is simple. If you downloaded all of the above files into a separate directory by themselves, simply issue the folowing command: </para> <para> <informalexample> <programlisting> $ rpm -Uvh *.rpm </programlisting> </informalexample> </para> <para> Or, you can issue them one by one in the following order: <informalexample> <programlisting> $ rpm -Uvh docbook-3.x-5.src.rpm $ rpm -Uvh jade-1.2.x-4.src.rpm $ rpm -Uvh jadetex-2.x-0.src.rpm $ rpm -Uvh psgml-1.2.x-1.src.rpm $ rpm -Uvh sgml-common-0.1-3.src.rpm $ rpm -Uvh stylesheets-0.10-2.src.rpm </programlisting> </informalexample> </para> <para> That's it. You should now have necessary tools installed to edit and verify your PHP documentation contributions. </para> </sect2> </sect1> <sect1 id="tools-on-windows"> <title>Tools on Windows</title> <para> Although the phpdoc environment is based on many Unix tools and techniques, there are ways to accomplish the same tasks on Windows. It is not too hard to set up a Windows working environment with CVS and the DocBook tools, but put away your mouse as you will need the keyboard for the majority of the tasks! :) </para> <sect2 id="tools-on-windows-obtaining"> <title>Obtaining the Tools</title> <para> You need the same tools as on Linux. The very basic thing is a CVS client. You can find one simple command line client here at the <ulink url="&url.cvs-win;">CVSHome.org</ulink> Win32 download pool. We do not recommend GUI tools such as WinCVS, because they can easily screw up the repository with files not intended to be there (eg. files with uppercased names). The best is to use one command line client, as this way you are in control. </para> <para> About XML editors, you are encouraged not to use WYSIWYG XML editors, such as XML Spy, because the often friendly auto-indent, and optimize features can make the XML files so different from the one you started the work with, that the diff posted to our mailing list and used by translators will be useless. Emacs is also available for Windows if you would like to give it a try ;) </para> <para> If you want to produce something viewable, or just would like to test the modified file before committing (recommended!), you need some more tools. To get it running on Windows, you'll need these tools: <itemizedlist> <listitem> <simpara> <ulink url="&url.win.cygwin;">Cygwin (bash for windows; it's huge...)</ulink> </simpara> </listitem> <listitem> <simpara> <ulink url="&url.jade;">Jade (the actual parser, take the windows binary dist)</ulink> </simpara> </listitem> <listitem> <simpara> <ulink url="&url.nwalsh;">Norman Walsh's modular DocBook stylesheets</ulink> </simpara> </listitem> <listitem> <simpara> <ulink url="&url.iso.entities;">Some ISO-entity declarations</ulink> </simpara> </listitem> </itemizedlist> Note that if you use Cygwin, there is no need to download a CVS client, as Cygwin comes with a CVS client built in. </para> </sect2> <sect2 id="tools-on-windows-installing"> <title>Installing the Tools</title> <para> You need to download and install the Cygwin tools. Just select the "Install now!" link and run the supplied <filename>setup.exe</filename>. It will guide you through process of installation. These tools are port of standard Unix tools like sed, awk, autoconf, make, perl, ... for Windows. </para> <para> Run "Cygwin Bash Shell" command from the Programs menu (it will be added here by the previous step). Now you get a command line which behaves same as bash on Unix boxes. If you never worked with bash or Unix before, note that there are slashes (/) instead of backslashes (\) in paths. If you want to access the <literal>foo</literal> directory on drive <literal>c:</literal> write it as <literal>c:/foo</literal> instead of <literal>c:\foo.</literal> </para> <warning> <simpara> Do NOT use symlinks with Cygwin, it's buggy. (Jade doesn't like them, and the shell doesn't handle them very well either) </simpara> </warning> <para> Change to the dir where your phpdoc snapshot is (or where you want to have it). Use, just like in Windows, the <literal>cd</literal> command. In Cygwin, the <literal>dir</literal> command is also supported. </para> <para> If you don't have your snapshot yet, execute CVS (packaged with Cygwin). More information about CVS can be found in the <link linkend="chapter-cvs">CVS section</link> of this document. </para> <note> <simpara> If you decide to use another directory in one of the next steps, you'll probably need to modify <filename>phpdoc/configure.in</filename> manually. We do not give any support if you are self-opinionated :) In this situation you can specify the DSSSL location manually by using the <literal>--with-dsssl=C:/path/to/dsssl</literal> option with configure. </simpara> </note> <para> Make sure that you are in the directory where the <literal>phpdoc</literal> dir is located. (if you type <literal>ls</literal>, you should see <literal>phpdoc</literal> listed). </para> <para> Type <literal>mkdir phpdoc-tools</literal>, and then unzip: <itemizedlist> <listitem><simpara>Jade to <literal>phpdoc-tools/jade</literal></simpara></listitem> <listitem><simpara>Norman Walsh's DSSSL files to <literal>phpdoc-tools/dsssl/docbook</literal></simpara></listitem> <listitem><simpara>the ISO-entities to <literal>phpdoc-tools/iso-entities</literal></simpara></listitem> </itemizedlist> XSL stylesheets are <emphasis>not necessary</emphasis> to generate the html versions of the manual, the DSSSL style sheets are used by default. If you think you would like to test XSL ones, than unzip Norman Walsh's XSL files to <literal>phpdoc-tools/xsl/docbook</literal>. See <ulink url="&url.nwalsh.xsl;">&url.nwalsh.xsl;</ulink> for more information and downloadable files. </para> <para> Verify that your directory structure looks like this: <informalexample> <programlisting> +--phpdoc | | | +--CVS | | | +--en | | | +--... | +--phpdoc-tools | +--dsssl | | | +--docbook (with docbook.dcl etc) | +--iso-entities (with ISOamsa etc) | +--jade (with jade.exe etc) | +--xsl (OPTIONAL!) | +--docbook (etc) </programlisting> </informalexample> </para> <para> Now go to the <literal>phpdoc</literal> directory, and execute: <informalexample> <programlisting> autoconf /configure --with-lang=your_language_code </programlisting> </informalexample> Substitute <literal>your_language_code</literal> with a language code you checked out the files of, and would like to work on. The <literal>--with-lang</literal> parameter is optional. If you don't specify it, the default is <literal>en</literal> (English). </para> <para> If you didn't get any errors, you're ready to rock&roll. Otherwise, you could check out the <ulink url="&url.docbook.appa;">installation appendix</ulink> of "DocBook: The Definitive Guide". </para> </sect2> </sect1> <sect1 id="tools-for-xsl"> <title>Tools for XSL Stylesheets</title> <para> In order to successfully use the XSL stylesheets you must have some XSLT processor and the XSL DocBook Stylesheets. This is sufficient for generating HTML version of the documentation. If you also want to create a version suitable for printing, you will additionally need a FO processor. </para> <para> This is an operating system independent section, as most of the tools are written in the Java language, or provide a version in Java. This means, you can run them on virtually any operating system, where a Java Virtual Machine is available. See the <ulink url="&url.sunjava;">Java homepage</ulink> for more information. </para> <note> <para> Using XSL stylesheets to generate different formats of the <literal>phpdoc</literal> XML files is <emphasis>optional</emphasis> currently. This method is not as well supported as DSSSL stylesheets, but is a promising technology. You do not need to setup any tools mentioned here if you would not like to play with XSL stylesheets. </para> </note> <para> XSLT processors: <itemizedlist> <listitem> <simpara> XT: <ulink url="&url.xsl.xt;">&url.xsl.xt;</ulink> </simpara> </listitem> <listitem> <simpara> Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink> </simpara> </listitem> <listitem> <simpara> Xalan: <ulink url="&url.xsl.xalan;">&url.xsl.xalan;</ulink> </simpara> </listitem> </itemizedlist> </para> <para> XSL DocBook Stylesheets: <ulink url="&url.xsl.style;">&url.xsl.style;</ulink> </para> <para> FO processors: <itemizedlist> <listitem> <simpara> PassiveTeX: <ulink url="&url.xsl.passivetex;">&url.xsl.passivetex;</ulink> </simpara> </listitem> <listitem> <simpara> FOP: <ulink url="&url.xsl.fop;">&url.xsl.fop;</ulink> </simpara> </listitem> <listitem> <simpara> XEP: <ulink url="&url.xsl.xep;">&url.xsl.xep;</ulink> </simpara> </listitem> </itemizedlist> </para> </sect1> </chapter>  Index: phpdoc/howto/working.xml +++ phpdoc/howto/working.xml <?xml encoding="iso-8859-1"?> <chapter id="chapter-files"> <title>File Overview</title> <para> 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: <variablelist> <varlistentry> <term><filename>manual.xml</filename></term> <listitem> <simpara> 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. </simpara> </listitem> </varlistentry> <varlistentry> <term><filename>chapters.ent</filename></term> <listitem> <simpara> Contains entity definitions for all chapters and appendices. Entities for the XML files are generated by configure, so <emphasis>you should not edit this file</emphasis>. </simpara> </listitem> </varlistentry> <varlistentry> <term><filename>global.ent</filename></term> <listitem> <simpara> Global internal text entities for all the XML files. This is where all the external links, email addresses, and "macros" are stored. </simpara> </listitem> </varlistentry> <varlistentry> <term><filename>your_language/language-defs.ent</filename></term> <listitem> <simpara> Contains local entities used by this language. Some common ones are the main part titles, but you should also put entities used only by this language's files here. </simpara> </listitem> </varlistentry> <varlistentry> <term><filename>your_language/language-snippets.ent</filename></term> <listitem> <simpara> Longer often used XML snippets translated to this language. Including common warnings, notes, etc. </simpara> </listitem> </varlistentry> </variablelist> </para> </chapter> <chapter id="chapter-conventions"> <title>Conventions</title> <para> When you work on <literal>phpdoc</literal> XML files, you should stick to these conventions, to ease the team work in the repository. </para> <para> <orderedlist> <listitem><simpara> Insert ID attributes in all major section tags such as part, chapter, sect1 etc. The HTML stylesheet will name the HTML files after these IDs. </simpara></listitem> <listitem><simpara> Function reference IDs look like this (case should be consistent with the rest of the function naming standards, i.e. lowercase): <literal>function.imageloadfont</literal>. Please note that since underscores cannot be used in IDs, they should be replaced by minus signs (-). </simpara></listitem> <listitem><simpara> Function section IDs (<literal><reference id="..."></literal>) look like this: 'ref.category', for example: 'ref.ftp'. </simpara></listitem> <listitem><simpara> The contents of examples with program listings start on column 0 in the XML code. </simpara></listitem> <listitem><simpara> All examples use the <literal><?php ... ?></literal> form instead of <literal><? ... ?></literal>. It can be useful to use <literal><![CDATA[ ... ]]></literal> for examples, since it eliminates the need to change <literal><</literal> to <literal>&lt;</literal>, etc. </simpara></listitem> <listitem><simpara> Indenting, bracketing and naming conventions in examples should adhere to the PEAR coding standards (it's in the manual). Deprecated aliases and syntax should not be used in examples. </simpara></listitem> <listitem><para> If an example uses arguments specific to a newer version of PHP, it is helpful to note this in the example: <programlisting> foo("bar", "baz"); // second argument was added in PHP 4.0.3 </programlisting> New arguments are denoted in the main text of the entry using the form <programlisting> <![CDATA[ <note> <simpara> The second parameter was added in PHP 4.0.3. </simpara> </note> ]]> </programlisting> </para></listitem> <listitem><simpara> The language constants true, false and null should be written as <literal>&true;</literal>, <literal>&false;</literal> and <literal>&null;</literal>. </simpara></listitem> <listitem><simpara> All English XML files should have a <literal></literal> comment as the first line unless they contain an <literal><?xml</literal> tag, in which case the revision comment should be on the second line. Non-English files should not have this comment. </simpara></listitem> <listitem><simpara> Whitespace changes in the English tree should be prevented as much as possible: it is more important to keep a good change-history of real changes, because of the translations. If a whitespace change is <emphasis>really</emphasis> needed, do it at least in a separate commit, with a clear comment such as 'WS fix' or 'Whitespace fix'. </simpara></listitem> <listitem><simpara> Never use tabs, not even in example program listings. XML should be indented with one space character for each level of indentation; example code uses four spaces (see PEAR standards). </simpara></listitem> <listitem><simpara> Always use LF (Line Feed) for the only newline character in files, this is the Unix standard. Never use CR LF (Windows) or CR (Mac) even, when editing Windows specific files (such as *.bat). It eases the editing works. </simpara></listitem> <listitem> <simpara> In the docs, the types are denoted as: <literal>boolean</literal> (<literal>bool</literal> in prototypes), <literal>integer</literal> (<literal>int</literal> in prototypes), <literal>float</literal> (<emphasis>not double!</emphasis>), <literal>array</literal>, <literal>object</literal> (<emphasis>not class!</emphasis>), <literal>resource</literal> and <literal>null</literal> (all lowercase). </simpara> <simpara> In prototypes, you can also use <literal>mixed</literal> (various types), or <literal>number</literal> (either integer or float), or <literal>scalar</literal> (boolean, integer, float or string). A callback is denoted as <literal>mixed</literal> <footnote><simpara>Better suggestions? I don't really like it this way... not simply <literal>function</literal>, or something alike? --Jeroen</simpara></footnote>, since it can be either array or string. </simpara> <simpara> If a function requires no arguments, use <literal><void/></literal> instead of <literal><parameter>void</parameter></literal>, since the former is the correct DocBook XML tag. </simpara> <simpara> If a function has an undefined return-value, use the word <literal>void</literal>. </simpara> </listitem> <listitem><simpara> In a prototype, if there are multiple - really distinct - possibilities, simply make it two! See <literal>math.xml:min()</literal> for an example. </simpara></listitem> <listitem><simpara> Aliases: in refpurpose, put: <literal>Alias of <function>realfunc</function></literal>. <emphasis>Do not specify a funcsynopsis, and nothing but simply the text:</emphasis> <literal>This function is an alias of <function>realfunc</function></literal>. This way, people can click to realfunc straight from the <literal>ref.foo</literal> page. </simpara></listitem> </orderedlist> </para> </chapter> <chapter id="chapter-what-to-document"> <title>What to Document?</title> <para> <orderedlist> <listitem> <simpara> Only major functions should be documented; functions which are deprecated variants may be mentioned, but should not be documented as separate functions. They instead should be referenced in the parent function as an alias. Functions which have completely different names, however, should be documented as separate entries, for ease of reference. The aliases.xml appendix is the place to store aliases not documented elsewhere. </simpara> <simpara> For example <literal>mysql_db_name</literal> and <literal>mysql_dbname</literal> will be documented as the same function, with the latter being listed as an alias of the former, while <literal>show_source</literal> and <literal>highlight_file</literal> will be documented as two different functions (one as an alias), as the names are completely different, and one name is not likely to be found if looking for the name of the other. </simpara> </listitem> <listitem> <simpara> Function names should be created, and documented, in lowercase format with an underscore separating the name components. If there are several variants, use the one with the least amount of components. </simpara> <simpara> Good: <literal>mcrypt_enc_self_test</literal>, <literal>mysql_list_fields</literal> </simpara> <simpara> OK: <literal>mcrypt_module_get_algo_supported_key_sizes</literal> (could be <literal>mcrypt_mod_get_algo_sup_key_sizes</literal>?), <literal>get_html_translation_table</literal> (could be <literal>html_get_trans_table</literal>?) </simpara> <simpara> Bad: <literal>hw_GetObjectByQueryCollObj</literal>, <literal>pg_setclientencoding</literal> </simpara> </listitem> <listitem> <simpara> Functions which are kept only for backwards compatibility should be listed under their current parent names, and not documented as separate functions. Backwards compatible functions and documentation for them should be maintained as long as the code can be reasonably kept as part of the PHP codebase. Also see the appendix <filename>aliases.xml</filename>. </simpara> </listitem> <listitem> <simpara> Short code examples are much more desirable than long ones. If a function is extremely complex, a suitable place to put a longer example is in the chapter introduction. This example can hold code for other functions in the same chapter. </simpara> </listitem> <listitem> <simpara> Brevity is appreciated. Long winded descriptions of each and every function are not appropriate for the reference sections. Using the errata comments as guidelines, it's easier to tell when more documentation is needed, as well as the inverse, when too much documentation in one section has increased confusion. </simpara> </listitem> </orderedlist> </para> </chapter> <chapter id="chapter-skeletons"> <title>Documentation Skeletons</title> <para> Below are some "skeletons" to copy and paste from when adding documentation. </para> <para> <example> <title>Function reference file in lang/functions/</title> <programlisting> <![CDATA[ <reference> <title></title> <titleabbrev></titleabbrev> </reference>  ]]> </programlisting> </example> </para> <para> <example> <title>Function reference entry</title> <programlisting> <![CDATA[ <refentry id="function."> <refnamediv> <refname></refname> <refpurpose></refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>RETURNTYPE <function>FUNCTIONNAME</function></funcdef> <paramdef>ARGTYPE1 <parameter>ARGNAME1</parameter></paramdef> <paramdef>ARGTYPE2 <parameter>ARGNAME2</parameter></paramdef> <paramdef>ARGTYPE3 <parameter><optional>ARGNAME3</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <simpara> A simple paragraph that can not contain anything that requires fancy layout. </simpara> <para> A normal paragraph that can contain lots of stuff. For example <example> <title>Code examples</title> <programlisting role="php"> // Use CDATA is you would like to add lots of < to the code /* Do all indentation with spaces, not tabs, just to be sure. * Don't try pushing the code to the right by adding spaces in * front, this is the style sheet's job. */ // a function example function some_code($foo) { /* use four spaces of indentation */ } // an example of bracket usage and spacing, always use // brackets, even when they are physically not needed if (some_code($foo) == "foo") { echo "foo"; } elseif (some_code($foo) == "bar") { echo "bar"; } else { echo "No foo, no bar"; } // Include end of CDATA, if you started with CDATA </programlisting> </example> The text in a paragraph may continue after the example as well. Here is how to make lists: <itemizedlist> <listitem> <simpara> List items must contain a container element such as simpara or para (there are plenty of others too, see the DocBook reference for the listitem element. </simpara> </listitem> <listitem> <simpara> List items must contain simple paragraphs or paragraphs. </simpara> </listitem> </itemizedlist> <itemizedlist> <listitem> <para> If you plan on making sub-lists, you must use para <orderedlist> <listitem><simpara> first list item</simpara></listitem> <listitem><simpara> second list item</simpara></listitem> </orderedlist> You can also continue an ordered list you just left off <orderedlist> <listitem><simpara> third list item</simpara></listitem> <listitem><simpara> fourth list item</simpara></listitem> </orderedlist> </para> </listitem> </itemizedlist> </para> <simpara> The documentation for a function should be wrapped up with a "See also" list like this: </simpara> <simpara> See also <function>stripslashes</function> and <function>quotemeta</function>. </simpara> </refsect1> </refentry> ]]> </programlisting> </example> </para> <para> For technical reasons, the CDATA start tag: <literal><![CDATA[</literal> and the CDATA end tag: <literal>]]></literal> is not included in the program code above, just the place of them are marked. </para> </chapter> <chapter id="chapter-misc"> <title>Miscellaneous Notes</title> <para> Misc. notes that don't need a full section. (stuff like http://www.zend.com/phpfunc/, etc. </para> </chapter>