goba Sun Sep 23 11:00:47 2001 EDT
Modified files:
/phpdoc/howto howto.ent howto.xml
Log:
Now fully incorporated the README.win32 file :))
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.4 phpdoc/howto/howto.ent:1.5
--- phpdoc/howto/howto.ent:1.4 Sun Sep 23 09:24:17 2001
+++ phpdoc/howto/howto.ent Sun Sep 23 11:00:47 2001
@@ -6,6 +6,8 @@
<!ENTITY email.danbeck "[EMAIL PROTECTED]">
<!ENTITY email.stig "[EMAIL PROTECTED]">
<!ENTITY email.goba "[EMAIL PROTECTED]">
+<!ENTITY email.jirka "[EMAIL PROTECTED]">
+<!ENTITY email.jeroen "[EMAIL PROTECTED]">
<!ENTITY email.phpdoc "[EMAIL PROTECTED]">
<!ENTITY email.group.php "[EMAIL PROTECTED]">
@@ -19,23 +21,32 @@
<!-- For DocBook section -->
<!ENTITY url.docbook-dtd "http://www.oasis-open.org/docbook/";>
<!ENTITY url.docbook-dtdref
"http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html";>
+<!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";>
<!-- For tools setup section -->
<!ENTITY url.nwalsh "http://nwalsh.com/docbook/dsssl/";>
+<!ENTITY url.nwalsh.xsl "http://nwalsh.com/docbook/xsl/";>
<!ENTITY url.jade "http://www.jclark.com/jade/";>
<!ENTITY url.autoconf "http://sources.redhat.com/autoconf/";>
<!ENTITY url.autoconf.ftp "ftp://ftp.gnu.org/gnu/autoconf/";>
<!ENTITY url.rpm "http://www.rpm.org/";>
<!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://www.a-es2.uu.nl/~jeroen/iso-entities.zip";>
<!-- For CVS section -->
<!ENTITY url.cvs "http://www.cvshome.org/";>
+<!ENTITY url.cvs-win "http://ftp.cvshome.org/win32/";>
<!ENTITY url.cvstut1 "http://www.arc.unm.edu/~rsahu/cvs.html";>
<!ENTITY url.cvstut2
"http://cellworks.washington.edu/pub/docs/cvs/tutorial/cvs_tutorial_1.html";>
<!ENTITY url.cvs.php "http://cvs.php.net";>
-<!ENTITY url.cvsaccount.php "http://www.php.net/cvs-php3.php";>
+<!ENTITY url.cvsaccount.php "http://www.php.net/cvs-php.php";>
+
+<!--
+http://www.php.net/anoncvs.php
+-->
<!-- For Misc section -->
<!ENTITY url.zend.phpfunc "http://www.zend.com/phpfunc/";>
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.5 phpdoc/howto/howto.xml:1.6
--- phpdoc/howto/howto.xml:1.5 Sun Sep 23 09:24:17 2001
+++ phpdoc/howto/howto.xml Sun Sep 23 11:00:47 2001
@@ -40,6 +40,24 @@
</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>
@@ -192,7 +210,7 @@
<!-- New Section: Tools Setup - - - - - - - - - - - - - - - - - - - -->
<sect1 id="tools-setup">
- <title>PHPdoc tools</title>
+ <title>Tools used by the PHP Documentation Group</title>
<para>
What tools you need depends on the operating system you use.
@@ -219,17 +237,26 @@
<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
- <link linkend="docbook">DocBook files</link>, 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
+ 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>
@@ -263,16 +290,8 @@
</listitem>
</itemizedlist>
</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>
- <sect3 id="obtaining-tools">
+ <sect3 id="tools-on-linux-obtaining">
<title>Obtaining the Tools</title>
<para>
@@ -330,7 +349,7 @@
</sect3>
- <sect3 id="installing-tools">
+ <sect3 id="tools-on-linux-installing">
<title>Installing the Tools</title>
<para>
@@ -367,7 +386,196 @@
</para>
</sect3>
- </sect2>
+ </sect2>
+
+ <sect2 id="tools-on-windows">
+ <title>Tools on Windows</title>
+
+ <para>
+ Although the phpdoc environment is based on many Linux
+ 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. The best is to use
+ one command line client.
+ </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
+ setup.exe. 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 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 :)
+ Currently 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 Welsh' DSSSL's 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. If you think
+ you would like to test them, than unzip Norman Walsh's
+ XSL's 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 en.
+ </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>
</sect1>
<!-- New Section: File Overview - - - - - - - - - - - - - - - - - - -->
@@ -450,6 +658,8 @@
<sect2 id="cvs-account">
<title>Obtaining a CVS Account</title>
+
+ <!-- Type 'man cvs' to get help for cvs (this is a so-called man-page) -->
<para>
First, before you can actually make documentation changes, you
