goba Wed Jul 17 11:55:01 2002 EDT
Modified files:
/phpdoc/howto cvs.xml docbook.xml framework.xml generating.xml
howto.ent howto.html.tar.gz howto.xml tools.xml
working.xml
Log:
General summer update ;)
o Info about new structure (reference dir instead of function dir)
Updated examples to reflect the new structure
o Info about new modules (phpdoc-LANGCODE), also affected
translation info, and many other stuff
o Info about new mailing lists (doc-LANGCODE)
o Updated info about revcheck, autogeneration, tools setup, CVS,
docbook version numbers, docbook tools
o Corrected several typos and misleading text
o Generally many improvements, as I have read the whole howto from
begining to end, and corrected errors where I felt I need to
Index: phpdoc/howto/cvs.xml
diff -u phpdoc/howto/cvs.xml:1.4 phpdoc/howto/cvs.xml:1.5
--- phpdoc/howto/cvs.xml:1.4 Wed Dec 12 15:50:38 2001
+++ phpdoc/howto/cvs.xml Wed Jul 17 11:55:01 2002
@@ -14,9 +14,11 @@
<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.
+ the name of the main repository used by the PHP Documentation
+ people is <literal>phpdoc</literal>. There are other
+ repositories used for translations, each named after the
+ language code of the translation (eg. <literal>phpdoc-de</literal>).
+ To access this server, you need a CVS client program on your system.
</para>
<para>
@@ -29,8 +31,8 @@
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 <link linkend="chapter-maillist">mailing
- list</link>, and the history is also viewable with a CVS
+ posted to one of the <link linkend="chapter-maillist">mailing
+ lists</link>, 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,
@@ -40,9 +42,9 @@
<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>.
+ <literal>phpdoc</literal> and translations tree and commiting
+ your changes. The complete CVS documentation and can be found
+ at <ulink url="&url.cvs;">&url.cvs;</ulink>.
</para>
<para>
@@ -60,7 +62,8 @@
<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".
+ brings up a help text called a "manpage". <literal>cvs
+ --help</literal> can also help you.
</para>
<sect1 id="cvs-account">
@@ -80,10 +83,10 @@
<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>.
+ and/or to your translations module. The Karma system controls
+ who have access to what repository, so if you have a CVS account
+ but have no Karma to write, 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>
@@ -110,7 +113,6 @@
out the formal request form.
</simpara>
</listitem>
-
</itemizedlist>
</para>
@@ -191,15 +193,17 @@
<note>
<para>
The <literal>CVSROOT</literal> environment variable
- won't be set until the next time you log in.
+ won't be set until the next time you log in. Also don't
+ forget to change the <parameter>username</parameter>
+ part to your CVS user name.
</para>
</note>
<para>
- If you use Windows, use your regular way to add the new
+ If you have 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
+ on Windows 9x, or the dialog box for setting environment
variables on Windows 2000).
</para>
@@ -230,7 +234,9 @@
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>).
+ issue a <literal>cvs logout</literal>). You can work for months
+ without logging in again, as this file will remain there with
+ the same content, leaving you logged in.
</para>
</sect1>
@@ -240,7 +246,7 @@
<para>
Now it's time to checkout the <parameter>phpdoc</parameter>
- module. Incidently, a module is a collection of source
+ module first. Incidently, a module is a collection of source
directories and files. Usually it's simply a directory tree in
the CVS repository.
</para>
@@ -274,6 +280,33 @@
</para>
</note>
+ <para>
+ If you would like to work with a translation group, checking
+ out the <filename>phpdoc</filename> module is not enough (though
+ required), as it only contains the files needed for building the
+ manual, and the English version of the source files. There are
+ other modules for translations, named after the language
+ code of the translation, with the pattern:
+ <literal>phpdoc-LANGCODE</literal>. LANGCODE is most of the time
+ a two letter code, but there can be exceptions. So if you would
+ like to work for the Italian translation group, you need to check
+ out the <filename>phpdoc-it</filename> module too. The place where
+ you should check out this module is strictly defined. You should
+ check out any translation's module under the <filename>phpdoc</filename>
+ directory you have created above with your previous checkout.
+ So change the directory to the phpdoc diretory and issue a
+ <informalexample>
+ <programlisting>
+$ cvs checkout <parameter>phpdoc-it</parameter>
+ </programlisting>
+ </informalexample>
+ command. Substitute the "it" part with your langauge code. You can
+ check out any number of translations as you need, and you need not
+ check out any translation if you would not like to work with it. To
+ work with the English files, no translation module needs to be checked
+ out.
+ </para>
+
</sect1>
<sect1 id="cvs-update">
@@ -281,7 +314,7 @@
<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
+ <filename>phpdoc</filename> 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>
@@ -296,6 +329,15 @@
</programlisting>
</informalexample>
</para>
+
+ <note>
+ <para>
+ If you have also checked out any translation modules, those
+ will also be updated with the command shown above, so there
+ is no need to separately update your checked out translation
+ modules.
+ </para>
+ </note>
<para>
If you only wish to update a particular file or set of files you
@@ -393,7 +435,7 @@
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>
+$ cvs commit -m 'added explanation of the new ..blah.. feature'
+<parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
</programlisting>
</informalexample>
</para>
@@ -406,6 +448,21 @@
more comments, you can't express on one line
using <parameter>-m</parameter>, choose this way.
</para>
+
+ <note>
+ <para>
+ Please check twice, that you commit changes in the human langague
+ the file is written in. The <filename>phpdoc</filename> module itself
+ only contains English files, so do not commit any files in other
+ languages, unless others agreed on the <link linkend="chapter-maillist">mailing
+ list</link>. The translation modules should not contain manual
+ content XML files with only English text in them, as this makes
+ translations harder to maintain, so do not commit any English only
+ files to translation trees. If you are not sure you won't make a
+ mistake with committing, please ask on the appropriate
+ <link linkend="chapter-maillist">mailing list</link>.
+ </para>
+ </note>
</sect1>
<sect1 id="cvs-add">
@@ -457,7 +514,7 @@
</para>
<para>
- To remove a file, first remove the file from your
+ To remove a file, first delete the file from your
local copy of the CVS repository, and issue the
following command:
<informalexample>
Index: phpdoc/howto/docbook.xml
diff -u phpdoc/howto/docbook.xml:1.4 phpdoc/howto/docbook.xml:1.5
--- phpdoc/howto/docbook.xml:1.4 Tue Feb 26 13:21:02 2002
+++ phpdoc/howto/docbook.xml Wed Jul 17 11:55:01 2002
@@ -5,10 +5,12 @@
<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
@@ -16,6 +18,7 @@
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
@@ -31,12 +34,14 @@
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
@@ -47,6 +52,7 @@
<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,
@@ -55,13 +61,17 @@
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.
+ can do more things with it. In DocBook you use tags
+ to mark the <emphasis>meaning</emphasis> of parts not
+ the presentation.
</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,
@@ -83,6 +93,17 @@
<para>
Get Going With DocBook, Notes for Hackers:
<ulink url="&url.docbook-intro;">&url.docbook-intro;</ulink>.
+ </para>
+ <para>
+ You can also find more information and downloads of style
+ sheets and other tools for DocBook in the DocBook Open
+ Repository at: <ulink url="&url.docbook.sf;">&url.docbook.sf;</ulink>.
+ </para>
+ <para>
+ You can also read the book <ulink url="&url.docbook;">DocBook:
+ The Definitive Guide</ulink> online, or buy it at a bookstore,
+ but be warned, that the first edition of the book (currently
+ the only printed edition available) contains outdated information.
</para>
</sect1>
</chapter>
Index: phpdoc/howto/framework.xml
diff -u phpdoc/howto/framework.xml:1.3 phpdoc/howto/framework.xml:1.4
--- phpdoc/howto/framework.xml:1.3 Wed Dec 12 15:50:40 2001
+++ phpdoc/howto/framework.xml Wed Jul 17 11:55:01 2002
@@ -6,7 +6,7 @@
<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 contribute to the PHP documentation project, you need
to at least know the very basics of XML and DocBook.
</para>
Index: phpdoc/howto/generating.xml
diff -u phpdoc/howto/generating.xml:1.10 phpdoc/howto/generating.xml:1.11
--- phpdoc/howto/generating.xml:1.10 Thu Dec 27 10:48:08 2001
+++ phpdoc/howto/generating.xml Wed Jul 17 11:55:01 2002
@@ -86,7 +86,7 @@
<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.
+ error and give you the line number it found the error at.
</para>
<para>
<screen>
@@ -94,14 +94,14 @@
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
+nsgmls:en/chpaters/intro.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>.
+ <filename>en/chapters/intro.xml</filename>.
Using this information, you can go back to the file and correct
the mistake before committing your changes.
</para>
@@ -236,6 +236,22 @@
</informalexample>
</para>
+ <note>
+ <para>
+ The above <literal>--with-xsl=file:///path/to/docbook/xsl/styles</literal>
+ form won't work with cygwin, because it tries to check for the existance
+ of the style sheet, and cygwin cannot interpret this kind of file path.
+ So there is a temporary
+<literal>--with-mxsl=file:///path/to/docbook/xsl/styles</literal>
+ method to use under cygwin, as long as we are unable to find the common
+ right method. Please also note, that the file path values generated
+ into <filename>entities/file-entities.ent</filename> by configure will
+ also be problematic with current XSLT tools, so you need to convert them
+ to use this <filename>file:///absolute/path/filename.xml</filename> form
+ before running any XSLT processors... After going through all these your
+ XSLT tool will be able to generate the output correctly under cygwin.
+ </para>
+ </note>
+
<para>
Configure will create four files:
<filename>html.xsl</filename>,
@@ -252,6 +268,14 @@
some FO processor.
</para>
+ <note>
+ <para>
+ The <filename>htmlhelp.xsl</filename> is currently not too
+ useful alone, as it's used by the new CHM build system which
+ is not available in CVS right now.
+ </para>
+ </note>
+
<para>
Invocation of XSLT processor is processor dependent,
for now suppose that you have a shell script called
@@ -268,11 +292,8 @@
</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.
+ To get a PDF from the FO file, you must run some FO
+ processor on the <filename>manual.fo</filename> file.
</para>
<note>
@@ -288,9 +309,10 @@
<note>
<para>
- Not all customization from DSSSL are backported to XSL,
+ Not all customization from DSSSL are ported to XSL,
so some things are not as pretty as in DSSSL output
- <emphasis>currently</emphasis>.
+ <emphasis>currently</emphasis>, but development is
+ underway to migrate the system to use XSL only.
</para>
</note>
</chapter>
@@ -317,9 +339,9 @@
it is modified in a one day period. The build process
takes hours for only one language, so not all languages
can be built in one day. During the generation, a
- <filename>build.log</filename> is saved with build
+ <filename>build.log.gz</filename> is saved with build
information. See the <link linkend="translation-practical">section
- for translators</link> about the <filename>build.log</filename>
+ for translators</link> about the <filename>build.log.gz</filename>
file. If there were some errors in the build process,
you can find the errors loged in this file.
</para>
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.15 phpdoc/howto/howto.ent:1.16
--- phpdoc/howto/howto.ent:1.15 Fri Jun 28 06:42:32 2002
+++ phpdoc/howto/howto.ent Wed Jul 17 11:55:01 2002
@@ -36,6 +36,7 @@
<!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";>
+<!ENTITY url.docbook.sf "http://docbook.sourceforge.net/";>
<!-- For tools setup section -->
<!ENTITY url.nwalsh "http://nwalsh.com/docbook/dsssl/";>
@@ -47,7 +48,7 @@
<!ENTITY url.docbookmirror1
"ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/SRPMS/";>
<!ENTITY url.docbookmirror2
"ftp://sourceware.cygnus.com/pub/docbook-tools/docware/SRPMS/";>
<!ENTITY url.win.cygwin "http://www.cygwin.com/";>
-<!ENTITY url.iso.entities "http://jeroen.a-eskwadraat.nl/sw/php/iso-entities.zip";>
+<!ENTITY url.openjade "http://openjade.sourceforge.net/";>
<!-- For CVS section -->
<!ENTITY url.cvs "http://www.cvshome.org/";>
@@ -69,7 +70,7 @@
<!-- For Working section -->
<!ENTITY url.langcodes "http://www.unicode.org/unicode/onlinedat/languages.html";>
-<!ENTITY url.buildlog.de "http://www.php.net/manual/de/build.log.gz";>
+<!ENTITY url.buildlog.de "http://www.php.net/de/blog";>
<!ENTITY url.listarchive "http://marc.theaimsgroup.com/?l=phpdoc";>
<!ENTITY url.listnews "news://news.php.net/php.doc";>
<!ENTITY url.listnewshttp "http://news.php.net/group.php?group=php.doc";>
@@ -78,7 +79,7 @@
<!ENTITY url.maillists "http://www.php.net/mailing-lists.php";>
<!ENTITY url.status "http://toye.php.net/~rasmus/status.php";>
<!ENTITY url.status.hu "http://toye.php.net/~rasmus/status.php?l=hu";>
-<!ENTITY url.revcheck.it "http://www.php.net/manual/it/revcheck.html.gz";>
+<!ENTITY url.revcheck.it "http://www.php.net/it/rev";>
<!-- For Misc section -->
<!ENTITY url.rtfs "http://www.fooassociates.com/rtfs/";>
Index: phpdoc/howto/howto.html.tar.gz
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.29 phpdoc/howto/howto.xml:1.30
--- phpdoc/howto/howto.xml:1.29 Thu Mar 21 13:28:23 2002
+++ phpdoc/howto/howto.xml Wed Jul 17 11:55:01 2002
@@ -18,19 +18,13 @@
<!-- TODO
- DocBook links:
- http://www.caldera.de/~eric/crash-course/HTML/index.html
- http://www.docbook.org/
- http://docbook.sourceforge.net/
- http://openjade.sourceforge.net/
-
Document new behaviour
Sections need to be added:
Documentation of the new CHM format generation
How to add a new section/funcref/anything to the docs
Work on Emacs and vi sections
- Partical advice for manual writers
+ Practical advice for manual writers
Separate conventions to parts, eg.
- larger sections (eg. function explanations)
- type, function and other tags,
@@ -51,11 +45,6 @@
- jade test sample to make sure jade works
- description for SGML_CATALOG_FILES environment variable
(http://docbook.sourceforge.net/projects/dsssl/doc/install.html)
- - link to http://docbook.sourceforge.net/
-
- [From Mark Kronsbein:]
- - Add list of cygwin-packages needed for building if someone does
- not want to install the whole cygwin stuff.
-->
Index: phpdoc/howto/tools.xml
diff -u phpdoc/howto/tools.xml:1.9 phpdoc/howto/tools.xml:1.10
--- phpdoc/howto/tools.xml:1.9 Fri May 31 17:07:11 2002
+++ phpdoc/howto/tools.xml Wed Jul 17 11:55:01 2002
@@ -29,15 +29,16 @@
<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.
+ and your translations language files. 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, or stop the automatic
+ generation of the manual files.
</para>
<para>
@@ -53,7 +54,7 @@
<para>
Although many tools are preinstalled on the majority of
- the Linux systems, we collected some useful information
+ Linux systems, we collected some useful information
about how they can be obtained and installed, if your
system misses them.
</para>
@@ -123,7 +124,7 @@
<para>
You will need to download the following files:
<itemizedlist>
- <listitem><simpara>docbook-3.x-5.src.rpm</simpara></listitem>
+ <listitem><simpara>docbook-4.x.src.rpm [see note below]</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>
@@ -141,14 +142,19 @@
<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.
+ We currently use DocBook 4.1.2 for writing phpdoc files, which
+ enables us to document OO based stuff (currently not used), and
+ we use many new structural elements. So 3.x docbook files are
+ not acceptable. The 4.1.2 DTD is available in the phpdoc
+ directory, but style sheets needed for output generation are
+ not there.
</para>
</note>
-
+
+ <para>
+ You may also consider using <ulink url="&url.openjade;">OpenJade</ulink>
+ a well maintained and extended version of Jade.
+ </para>
</sect2>
<sect2 id="tools-on-linux-installing">
@@ -172,7 +178,7 @@
Or, you can issue them one by one in the following order:
<informalexample>
<programlisting>
-$ rpm -Uvh docbook-3.x-5.src.rpm
+$ rpm -Uvh docbook-4.x.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
@@ -221,7 +227,7 @@
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
- <link linkend="chapter-maillist">mailing list</link> and used
+ <link linkend="chapter-maillist">mailing lists</link> and used
by translators will be useless. Emacs is also available for
Windows if you would like to give it a try ;)
</para>
@@ -235,12 +241,13 @@
<itemizedlist>
<listitem>
<simpara>
- <ulink url="&url.win.cygwin;">Cygwin (bash for windows; it's huge...)</ulink>
+ <ulink url="&url.win.cygwin;">Cygwin (linux tools for windows; it's
+huge...)</ulink>
</simpara>
</listitem>
<listitem>
<simpara>
- <ulink url="&url.jade;">Jade (the actual parser, take the windows binary
dist)</ulink>
+ <ulink url="&url.jade;">Jade (the actual parser, take the windows binary
+dist)</ulink> or
+ <ulink url="&url.openjade;">OpenJade</ulink>
</simpara>
</listitem>
<listitem>
@@ -248,11 +255,6 @@
<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.
@@ -266,11 +268,24 @@
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
+ the process of installation. These tools are port of standard
Unix tools like sed, awk, autoconf, make, perl, ...
for Windows.
</para>
+ <note>
+ <para>
+ Be aware, that cygwin is grown to be a very huge project and
+ it includes many programs (such as postgres and apache) ported
+ to Windows, which are not needed for phpdoc. We are unable to
+ give you a list of needed components from cygwin (which you should
+ download and install), because the basic tools are interconnected,
+ and depends on each other. If you manage to find the smallest
+ needed installation, do not hesitate to contact us, and send the
+ solution to us.
+ </para>
+ </note>
+
<para>
Run "Cygwin Bash Shell" command from the Programs menu
(it will be added here by the previous step). Now you get
@@ -284,8 +299,8 @@
<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)
+ 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>
@@ -328,7 +343,6 @@
<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>
@@ -344,13 +358,16 @@
You also need a working copy of PHP 4.x to build the manual.
On Windows, you should put a <filename>php.bat</filename>
file to the <filename>phpdoc-tools</filename> directory, with
- a PHP calling line. You may use the recommended php.ini file
- as the default settings for PHP scripts differ from the ones
- required by phpdoc PHP scripts. Something like this works
- (modify this according to your PHP setup directory):
+ a PHP calling line. You may use the recommended
+ <filename>php.ini</filename> file as the default settings
+ for PHP scripts differ from the ones required by phpdoc
+ PHP scripts. The recommended <filename>php.ini</filename>
+ file can be found in <filename>phpdoc/scripts</filename>.
+ Something like this works (modify this according to your
+ PHP setup directory):
<informalexample>
<programlisting>
- @"E:\Program Files\PHP\php.exe" %1 %2 %3 %4 %5 %6 %7 %8 %9
+ @"C:\Program Files\PHP\php.exe" %1 %2 %3 %4 %5 %6 %7 %8 %9
</programlisting>
</informalexample>
</para>
@@ -365,23 +382,21 @@
| |
| +--en
| |
-| +--...
+| \--...
|
-+--phpdoc-tools
+\--phpdoc-tools
|
+--dsssl
| |
- | +--docbook (with docbook.dcl etc)
- |
- +--iso-entities (with ISOamsa etc)
+ | \--docbook (with docbook.dcl etc)
|
+--jade (with jade.exe etc)
|
+--xsl (OPTIONAL!)
| |
- | +--docbook (etc)
+ | \--docbook (etc)
|
- +--php.bat
+ \--php.bat
</programlisting>
</informalexample>
</para>
@@ -395,15 +410,14 @@
</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).
+ 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.
+ 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". If you think that the problem
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.20 phpdoc/howto/working.xml:1.21
--- phpdoc/howto/working.xml:1.20 Wed Jun 19 02:28:35 2002
+++ phpdoc/howto/working.xml Wed Jul 17 11:55:01 2002
@@ -22,12 +22,12 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>entities/chapters.ent</filename></term>
+ <term><filename>entities/file-entities.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>.
+ Contains entity definitions for all files. Entities for the
+ XML files are generated by configure, so
+ <emphasis>you should not edit this file</emphasis>.
</simpara>
</listitem>
</varlistentry>
@@ -141,11 +141,13 @@
with a role attribute set to "php". Never add any
other programlisting or PHP output with such
a role. It is reserved for PHP source code only.
- This role is used to detect PHP code and highlight.
+ This role is used to detect PHP code and highlight it.
</simpara></listitem>
<listitem><simpara>
The contents of examples with programlistings
- start on column 0 in the XML code.
+ start on column 0 in the XML code. <!-- Indenting,
+ bracketing and naming conventions in examples should
+ adhere to the PEAR coding standards. -->
</simpara></listitem>
<listitem><simpara>
All examples use the <literal><?php ... ?></literal>
@@ -156,10 +158,7 @@
Examples look much better, and easily manageable.
</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.
+ 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
@@ -183,7 +182,9 @@
The language constants true, false and null
should be written as <literal>&true;</literal>,
<literal>&false;</literal> and
- <literal>&null;</literal>.
+ <literal>&null;</literal>. There are other
+ shortcuts, such as <literal>&php.ini;</literal>.
+ These are stored in <filename>global.ent</filename>.
</simpara></listitem>
<listitem><simpara>
All English XML files should have a <literal><!--
@@ -204,7 +205,7 @@
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) -->.
+ example code uses four spaces.
</simpara></listitem>
<listitem><simpara>
Always use LF (Line Feed) for the only newline
@@ -240,7 +241,7 @@
<simpara>
Do not use <literal>mixed</literal>, if the return
- value is of a certain (not boolen) type, and FALSE
+ value is of a certain (not boolean) type, and FALSE
only on error. Provide the primary return type as
the return type of the function, and write down in
the explanation, that it returns FALSE on error.
@@ -264,7 +265,8 @@
<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.
+ See <literal>en/reference/math/functions/min.xml</literal>
+ for an example.
</simpara></listitem>
<listitem><simpara>
Aliases: in refpurpose, put:
@@ -273,7 +275,7 @@
nothing but simply the text:</emphasis>
<literal>This function is an alias of
<function>realfunc</function></literal>.
- This way, people can click to realfunc
+ This way, people can go to realfunc
straight from the <literal>ref.foo</literal> page.
</simpara></listitem>
</orderedlist>
@@ -384,7 +386,7 @@
</para>
<para>
<example>
- <title>Function reference file in lang/functions/</title>
+ <title>Function reference file in lang/reference/EXTNAME/functions</title>
<programlisting>
<![CDATA[
<reference>
@@ -403,7 +405,7 @@
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
-sgml-default-dtd-file:"../../manual.ced"
+sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
@@ -533,9 +535,16 @@
<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. Use these
+ in the listing above, just the place of them are marked. Use these
tags to be able to write clearer example codes.
</para>
+ <para>
+ For parts we have no skeleton here, please look at existing files in the
+ <filename>phpdoc</filename> CVS module. If you are not sure a specific file
+ is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc
+ mailing list</link>. If you have any suggestions for more skeletons do not
+ hesitate.
+ </para>
</chapter>
<chapter id="chapter-translation">
@@ -557,10 +566,10 @@
<itemizedlist>
<listitem>
<simpara>
- Consult the <link linkend="chapter-maillist">mailing
+ Consult the <link linkend="chapter-maillist">phpdoc mailing
list</link> to see if the translation is already in progress.
If it is, disregard the following and coordinate with the
- other translators on the list.
+ other translators on the translation mailing list.
</simpara>
</listitem>
<listitem>
@@ -571,19 +580,28 @@
</listitem>
<listitem>
<simpara>
- Create a sudirectory with the appropriate language
- code, or ask for help about how you can do this on the
- list. Appropriate languages codes can be found at
- <ulink url="&url.langcodes;">&url.langcodes;</ulink>.
- See the CVS chapter about <link linkend="cvs-add">how
- to add a file or directory</link>.
+ After you have received your CVS account, ask
+ <ulink url="mailto:&email.group.php;";>&email.group.php;</ulink>
+ to create a new <literal>phpdoc-LANGCODE</literal> CVS
+ module, and a new <literal>doc-LANGCODE</literal> mailing
+ list for the new translation.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Check out the <filename>phpdoc</filename> and the
+ <literal>phpdoc-LANGCODE</literal> modules as
+ described in the <link linkend="chapter-cvs">CVS chapter</link>
+ of this howto.
</simpara>
</listitem>
<listitem>
<simpara>
Copy <filename>en/language-defs.ent</filename> and
<filename>en/language-snippets.ent</filename> to the
- new directory and translate the contents of them.
+ new <literal>phpdoc-LANGCODE</literal> modules root directory
+ (visible as <literal>phpdoc/LANGCODE</literal> in your file
+ system) and translate the contents of them.
</simpara>
</listitem>
<listitem>
@@ -609,7 +627,7 @@
<simpara>
Can you set up and translate the whole manual
yourself? If not, can you set up a team to
- work on the language?
+ work on the language (recommended!)?
</simpara>
</listitem>
<listitem>
@@ -630,7 +648,7 @@
<para>
If you see that a manual for your language is set
up, and you would like to join the group, please
- ask on the <link linkend="chapter-maillist">mailing
+ ask on the appropriate <link linkend="chapter-maillist">mailing
list</link> about who is responsible to manage that
translation.
</para>
@@ -658,6 +676,13 @@
</listitem>
<listitem>
<simpara>
+ Do not commit translated files into the English tree.
+ Double check your files before committing, to be sure
+ that you are committing to the right place.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
Use a system to coordinate with the translators
in your language. Currently we have two systems
used paralelly, the Translators files and the
@@ -673,7 +698,7 @@
that should be corrected, please correct the
found errors yourself. If you are not sure,
whether you found an error or not, please ask
- on the <link linkend="chapter-maillist">mailing
+ on the phpdoc <link linkend="chapter-maillist">mailing
list</link>.
</simpara>
</listitem>
@@ -696,7 +721,7 @@
only cause errors. Similarly do not translate any
tags (eg. <computeroutput>) to your language.
The contents of comments (eg. the bottom of every
- file) are not to be translated.
+ file) are also not to be translated.
</simpara>
</listitem>
<listitem>
@@ -749,10 +774,13 @@
the work is needed to update the already translated
ones, to get in sync with the content of the English
files. To follow the modifications in the English
- tree, you should subscribe to the
+ tree, you should subscribe to the phpdoc
<link linkend="chapter-maillist">mailing list</link>,
or read the archives. If you never update your files,
- the translations can get useless.
+ the translations can get useless. You should also subscribe
+ to your languages mailing list (if it's not English),
+ to get CVS commit messages and participate in language
+ specific discussions.
</para>
<para>
Updating a foreign language file can get difficult,
@@ -767,10 +795,9 @@
<title>The Translators Files</title>
<para>
- Nearly all translations are currently using a
- <filename>Translators</filename> file just in the
- root of their translation's tree. This file
- can contain the names, email addresses, and CVS
+ Some translations are using a <filename>Translators</filename>
+ file in the root of their translation's tree for revision tracking.
+ This file can contain the names, email addresses, and CVS
user names of the contributors of this translation,
and the list of files translated.
</para>
@@ -809,8 +836,8 @@
number yet, a status (eg. working).
</para>
<para>
- When it is time to update a file (eg. bookinfo.xml jumped to
- 1.20 as time passed), you can ask for a diff between 1.16 and
+ When it is time to update a file (eg. the English bookinfo.xml jumped
+ to 1.20 as time passed), you can ask for a diff between 1.16 and
1.20, and you'll see what modifications you need to port to
the translated file. You can ask for diffs by using the diff
CVS command, or using the web interface at <ulink url="&url.php.cvs;">
@@ -823,6 +850,14 @@
numbers stored in the <filename>Translators</filename> as
you update files in your language's tree.
</para>
+ <note>
+ <para>
+ This system is hard to maintain with the current <filename>phpdoc</filename>
+ layout, as tracking the revisions of more then 4000 files in one text file
+ can be very hard. Consider using the revison comment method described below,
+ where you only need to work on one file if you make updates in your language.
+ </para>
+ </note>
</sect2>
<sect2 id="translation-revcheck-comments">
@@ -835,7 +870,7 @@
languages use the Revision comments and Translators files
paralelly, some use only one of these. It is better to
decide, and not to use two systems, as things can get
- messy this way.
+ very messy this way.
</para>
<para>
Instead of storing all responsibilities in a central file,
@@ -855,15 +890,18 @@
add some other status information in the case it is needed
(eg. "partial" for incomplete translations). This revision
comment system is basically about storing the information in
- the XML files, and not in a central place.
+ the XML files, and not in a central place. This is extremely
+ convinient now, as there are more then 4000 files in the
+ English tree.
</para>
<para>
Currently all the three information is needed. Maintainer
is intended to be a CVS user name, or some nickname without
a space, status can be anything without a space. Note, that
- this header is not updated by CVS (as
- <literal>$Revision</literal> is updated automatically). This
- is only updated when you edit the contents of the comment.
+ this header is not updated by CVS (in contrast with
+ <literal>$Revision</literal>, which is updated automatically).
+ This is only updated when you edit the contents of the comment
+ yourself.
</para>
<para>
You may see this as a good thing, but using these comments,
@@ -894,9 +932,9 @@
<para>
As this system gets popular in many translation groups,
the automatic build process also generates a
- <filename>revcheck.html</filename> at the end of the
- build process for that language. It is available online
- in the languages manual directory, as
+ <filename>revcheck.html.gz</filename> at the beginning
+ of the build process for that language. It is available
+ online in the languages manual directory, as
<filename>build.log.gz</filename> is also there.
See the Italian translation's file online:
<ulink url="&url.revcheck.it;">&url.revcheck.it;</ulink>.
@@ -955,7 +993,8 @@
the <filename>revcheck.html</filename> file. All translators
are linked to from the individual files they are assigned
to, and there is a nice table showing the state of files for
- all the translators.
+ all the translators. Assingning ready files may be needed if
+ a time consuming update is in progress on that file.
</para>
<para>
@@ -965,7 +1004,10 @@
versions. The editor parameter of a <person> is also used
in the grouping of translators on the CHM index page. These
are optional, but are vital for every translation where the
- readers use the CHM format (all translations ;).
+ readers use the CHM format (all translations ;). Note that these
+ are not used for current CHM manual generation, but will be
+ important for the "next generation" CHMs, which are currently
+ under heavy testing and development.
</para>
<para>
@@ -974,7 +1016,8 @@
and <literal>revision</literal>. Date is assumed to be the date
when the work was started, revision is the checked out revision
of the English file used to start the work (denoted as
- CO-Revision in the generated table).
+ CO-Revision in the generated table). There is currently no
+ fixed format for the <literal>date</literal> parameter.
</para>
<para>
@@ -989,7 +1032,7 @@
</programlisting>
The credits comment can contain a comma separated list. These
comments only affect the display of the translators table in
- <filename>revcheck.html</filename>.
+ <filename>revcheck.html.gz</filename>.
</para>
</sect2>
@@ -1007,7 +1050,7 @@
Visiting this page, you need to wait for some time to generate,
as it builds a whole table of file and dates information about
all translations. If you would like to restrict the table to only
- one translation, you can provide the <literal>?l=langcode</literal>
+ one translation, you can provide the <literal>?l=LANGCODE</literal>
URL parameter, so to view the Hungarian status, visit:
<ulink url="&url.status.hu;">&url.status.hu;</ulink>.
</para>
@@ -1026,24 +1069,36 @@
</chapter>
<chapter id="chapter-maillist">
- <title>The phpdoc, php-doc-chm and php-notes Mailing Lists</title>
+ <title>The phpdoc, php-doc-chm, php-notes and Other Mailing Lists</title>
<para>
- The XML content of <literal>phpdoc</literal> files is
- updated from day to day, and on busy days from hour to
- hour. To follow the updates in the English tree and
- any other language's tree and also participate in
- the discussions, it is highly recommended that you
- subscribe to the <email>&email.phpdoc;</email> mailing
+ The XML content of documentation files is updated from day
+ to day, and on busy days from hour to hour. To follow the
+ updates in the English tree and participate in general discussions
+ related to the PHP documentation, it is highly recommended that
+ you subscribe to the <email>&email.phpdoc;</email> mailing
list. You can subscribe by sending a blank mail to
<ulink url="&url.docsubscribe;">&url.docsubscribe;</ulink>.
Similarly you can unsubscribe by sending a blank mail to
<ulink url="&url.docunsubscribe;">&url.docunsubscribe;</ulink>.
There is a web interface for these tasks at <ulink
- url="&url.maillists;">&url.maillists;</ulink>.
+ url="&url.maillists;">&url.maillists;</ulink>
</para>
<para>
- Currently this list receives messages from the following senders:
+ There are also separate mailing lists for translation groups,
+ where native language discussions may go on and where language
+ specific CVS commits are posted to. These mailing lists are
+ named in the form of <literal>doc-LANGCODE</literal> where
+ LANGCODE is the same language code used in the CVS module name.
+ You can subscribe to / unsubscribe from these mailing lists
+ the same way as above explained, substituting
+ <literal>phpdoc</literal> in the email adreesses with your list
+ name. A sample list name is <literal>doc-zh</literal> for the
+ Simplified Chineese list.
+ </para>
+ <para>
+ Currently these lists (including the main phpdoc list) receive
+ messages from the following senders:
<itemizedlist>
<listitem>
<simpara>
@@ -1054,71 +1109,76 @@
<listitem>
<simpara>
The CVS server: diffs about every small modification
- in the English or any languages XML files, or other
- support files placed in the <literal>phpdoc</literal>
- repository.
+ in the corresponding module's XML files. This means that
+ the phpdoc list receives the English file modification commits
+ and other support file's modifications, while other lists
+ only receive the language specific commits.
</simpara>
</listitem>
<listitem>
<simpara>
- The PHP bug tracking system: bug follow ups classified
- as "Documentation Problem" in the bug system.
+ Other senders: the posting to list is not restricted,
+ so people not on the list can also post messages. This
+ way we got reports and suggestions by plain mails
+ on the list.
</simpara>
</listitem>
<listitem>
<simpara>
- Other senders: the posting to list is not restricted,
- so people not on the list can also post messages. This
- way we got bug reports and suggestions by plain mails
- on the list.
+ The PHP bug tracking system: bug follow ups classified
+ as "Documentation Problem" are posted to the phpdoc
+ list.
</simpara>
</listitem>
<listitem>
<simpara>
SPAM: this is not a common piece of mail, thanks to
- our SPAM protection system.
+ our SPAM protection system. :)
</simpara>
</listitem>
</itemizedlist>
- This long list of mail types can be scaring for someone,
- who can't process the many mails posted to the list. For
- this reason the team is thinking about separating the list
- to language specific list, so commits in the foreign
- languages trees won't posted to the main list. Although
- this is just a plan now.
+ As there are many posters to the lists including some automatic
+ postings (bugs, cvs commits) you should only subscribe to those
+ lists in which you are interested in. We recommend that if you
+ only work on the English version, you only subscribe to the
+ <literal>phpdoc</literal> list. If you are also a member of a
+ translation group, then you should subscribe to the translation's
+ mailing list too, after subscribing to <literal>phpdoc</literal>.
+ Reading the main mailing list's mails at least enables you to
+ know what is going on in the English tree, what needs to be
+ updated, and what is changed in the build system.
</para>
<para>
- If you can't handle the load of this mailing list in
- your mailbox, you can read the messages three ways:
+ You should be able to handle the traffic of the mailing lists
+ you are subscribed to, but just in case you need to go for a long
+ summer break, and you need to unsubscribe, there are other methods
+ to read the messages after you come back:
<itemizedlist>
<listitem>
<simpara>
- On the web, in the archives at
+ Read the messages on the web, in the archives at
<ulink url="&url.listarchive;">&url.listarchive;</ulink>
+ (this only works for the main phpdoc list!).
</simpara>
</listitem>
<listitem>
<simpara>
- With a news reader at
- <ulink url="&url.listnews;">&url.listnews;</ulink>
+ Download the messages with a news reader at
+ <ulink url="&url.listnews;">&url.listnews;</ulink>.
</simpara>
</listitem>
<listitem>
<simpara>
- On the web, with the experimental news interface at
- <ulink url="&url.listnewshttp;">&url.listnewshttp;</ulink>
+ Read the messages on the web, with the experimental news interface at
+ <ulink url="&url.listnewshttp;">&url.listnewshttp;</ulink>.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
- You can also set up some filter on incoming mail messages,
- so you get the most important things, and can participate
- in the discussions while do not need to read big diff
- messages. To ease the filtering the commit messages coming
- from the CVS server, that are larger then 8kb, are put
- into attachements. You can always see the commit message
- and file list in the body, but the diff is in an
+ The commit messages coming from the CVS server, that are larger
+ then 8kb, are put into attachements. You can always see the
+ commit message and file list in the body, but the diff is in an
attachement.
</para>
<para>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
