goba Sun Apr 3 06:53:21 2005 EDT
Modified files:
/phpdoc/howto framework.xml howto.ent preface.xml tools.xml
Log:
howto update:
- fix some typos
- update online dochowto address
- the howto is an evolving document :)
will never be ready
- document encodings
- docbook 4.1.2 is not new anymore, so reword that part
- no need to use emacs on windows :)
- do not bother with saxon, strengthen the position of xsltproc
http://cvs.php.net/diff.php/phpdoc/howto/framework.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/howto/framework.xml
diff -u phpdoc/howto/framework.xml:1.5 phpdoc/howto/framework.xml:1.6
--- phpdoc/howto/framework.xml:1.5 Fri Apr 11 16:42:03 2003
+++ phpdoc/howto/framework.xml Sun Apr 3 06:53:20 2005
@@ -19,8 +19,8 @@
<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
+ XML files and test their content for errors. The tools
+ you need depend on the operating system you use. Linux
or some sort of Unix is recommended, although many things
in phpdoc work on Windows. You will find more information
about the tools you need in the
@@ -29,7 +29,7 @@
<para>
If you have problems not covered in this document,
- write in to <email>&email.phpdoc;</email> and ask.
+ write to <email>&email.phpdoc;</email> and ask.
</para>
</chapter>
http://cvs.php.net/diff.php/phpdoc/howto/howto.ent?r1=1.25&r2=1.26&ty=u
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.25 phpdoc/howto/howto.ent:1.26
--- phpdoc/howto/howto.ent:1.25 Tue Mar 1 12:18:50 2005
+++ phpdoc/howto/howto.ent Sun Apr 3 06:53:20 2005
@@ -30,7 +30,7 @@
<!ENTITY url.php.manual.rtf "http://www.php.net/distributions/manual.rtf";>
<!ENTITY url.php.news "http://php.net/php4news";>
<!ENTITY url.php.howto "http://php.net/get/dochowto";>
-<!ENTITY url.php.howto.online "http://php.net/manual/howto";>
+<!ENTITY url.php.howto.online "http://doc.php.net/dochowto";>
<!-- For DocBook section -->
<!ENTITY url.docbook "http://www.docbook.org/";>
http://cvs.php.net/diff.php/phpdoc/howto/preface.xml?r1=1.4&r2=1.5&ty=u
Index: phpdoc/howto/preface.xml
diff -u phpdoc/howto/preface.xml:1.4 phpdoc/howto/preface.xml:1.5
--- phpdoc/howto/preface.xml:1.4 Fri Apr 11 12:12:42 2003
+++ phpdoc/howto/preface.xml Sun Apr 3 06:53:20 2005
@@ -13,11 +13,10 @@
</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.
+ This HOWTO is an evolving document, and always "under construction".
+ It is supposed to contain sections about generating HTML documentation
+ from XML sources, adding new XML files, or using XSL style sheets to
+ process the source files.
</para>
<para>
@@ -40,10 +39,10 @@
<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.
+ risk. There may be errors and inaccuracies in this document, 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>
@@ -81,7 +80,7 @@
<title>Feedback</title>
<para>
- Feedback is most certainly welcome for this document. Without your
+ Feedback is most certainly welcome on 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>.
http://cvs.php.net/diff.php/phpdoc/howto/tools.xml?r1=1.22&r2=1.23&ty=u
Index: phpdoc/howto/tools.xml
diff -u phpdoc/howto/tools.xml:1.22 phpdoc/howto/tools.xml:1.23
--- phpdoc/howto/tools.xml:1.22 Tue Mar 1 12:26:56 2005
+++ phpdoc/howto/tools.xml Sun Apr 3 06:53:20 2005
@@ -13,11 +13,17 @@
<listitem><simpara>Command line CVS client</simpara></listitem>
<listitem><simpara>Text editor</simpara></listitem>
</itemizedlist>
- The basic process is to check out (~download) the file
+ The basic process is to check out (~download) a 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:
+ is just the absolute minimum. It is worth noting that
+ the different translation projects use different encodings,
+ so to work with those projects, you need an editor, which
+ supports these encodings. The English documentation mostly
+ uses ISO-Latin-1 (ISO-8859-1), but some files are UTF-8
+ encoded, so you are better equiped with an UTF-8 supporting
+ editor. Some more useful tools:
<itemizedlist>
<listitem><simpara>Visual CVS client</simpara></listitem>
<listitem><simpara>XML [capable] editor</simpara></listitem>
@@ -28,12 +34,11 @@
</para>
<para>
- The last item in the above list (test your modifications) is
- the hardest to get working, as you need a copy of the English
- and your translation's 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 currently created using
- <ulink url="&url.jade;">Jade</ulink> /
+ Testing your modifications is the hardest to get working, as you
+ need a copy of the English and your translation's 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
+ currently created using <ulink url="&url.jade;">Jade</ulink> /
<ulink url="&url.openjade;">OpenJade</ulink> and
<ulink url="&url.nwalsh;">Norman Walsh's Modular DocBook
Stylesheets</ulink>. There are other tools used to produce some
@@ -47,8 +52,8 @@
<para>
<emphasis>
If you have information about other good XML editors and/or tools
- not mentioned here, please send it to the phpdoc mailing list:
- <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>.
+ not mentioned here, please send your suggestion to the phpdoc mailing
+ list: <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>.
</emphasis>
</para>
@@ -147,10 +152,10 @@
<note>
<para>
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. The 4.1.2 DTD is available
- in the phpdoc folder, and style sheets needed for output
- generation are also there, so there is no need to set these up.
+ is not the very latest DocBook version, but seems to be sufficient
+ for our need. The 4.1.2 DTD is available in the phpdoc folder, and
+ style sheets needed for output generation are also there, so there
+ is no need to set these up.
</para>
</note>
@@ -222,18 +227,19 @@
thing is a CVS client. You can find one simple command
line client here at the <ulink url="&url.cvs-win;">CVSHome.org</ulink>.
Although you can use GUI tools such as WinCVS or TortoiseCVS,
- we provided instructions only for command line client in order
+ we provided instructions only for command line clients in order
to keep this HOWTO short and simple.
</para>
<para>
- About XML editors, you are encouraged not to use intelligent 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
+ You are encouraged not to use intelligent 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
+ to work with, that the diff posted to our
<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 ;)
+ Windows if you would like to give it a try, but any basic text
+ editor with Linux line ending support will suffice.
</para>
<para>
@@ -274,28 +280,28 @@
<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. To install
+ Be aware, that Cygwin is grown to be a very huge project and
+ it includes many programs (such as PostgreSQL and Apache) ported
+ to Windows, which are not needed for phpdoc. To install the
minimal set of required packages select
<literal>autoconf</literal> and <literal>make</literal>
along with components, which are selected in setup by
default. You may also want to add <literal>cvs</literal>
- to the installation list if you don't have CVS client yet.
+ to the installation list if you don't have a CVS client yet.
Do not care about dependencies - they will be selected
automatically.
</para>
</note>
<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>
+ Once installed, you will see a "Cygwin Bash Shell" command in
+ the Programs menu. Running that, 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>
@@ -454,7 +460,7 @@
not like to play with XSL stylesheets. However
we plan to use XSL in the future for documentation
generation, and XSL is already in use in the 'new
- CHM edition'.
+ CHM edition' and with Livedocs.
</para>
</note>
@@ -486,26 +492,12 @@
</para>
<para>
- XSLT processors:
- <itemizedlist>
- <listitem>
- <simpara>
- LibXSLT (also known as xsltproc, recommended;):
- <ulink url="&url.xsl.libxslt;">&url.xsl.libxslt;</ulink>,
- available as Windows binaries too at:
- <ulink url="&url.xsl.libxslt.win;">&url.xsl.libxslt.win;</ulink>,
- and also included in current cygwin setups.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink>
- (not supported by the build system)
- </simpara>
- </listitem>
- </itemizedlist>
+ The build system only supports <ulink
url="&url.xsl.libxslt;">LibXSLT</ulink>
+ (also known as xsltproc), available as Windows binaries too at:
+ <ulink url="&url.xsl.libxslt.win;">&url.xsl.libxslt.win;</ulink>,
+ and also included in current Cygwin setups, if selected for installation.
</para>
-
+
<note>
<para>
As we tested, other XSLT processors, like XT and MSXML cannot handle
