cvs: phpdoc /howto tools.xml

goba Fri Apr 11 16:47:10 2003 EDT Modified files: /phpdoc/howto tools.xml Log: Updating tools information: - removing unneeded docbook package - [I am still not sure, whether sgml-common is needed, I have set up my tools from sources] - adding more info on openjade - actualizing XSL part a little bit - fixing some typos Index: phpdoc/howto/tools.xml diff -u phpdoc/howto/tools.xml:1.16 phpdoc/howto/tools.xml:1.17 --- phpdoc/howto/tools.xml:1.16 Fri Mar 14 07:49:10 2003 +++ phpdoc/howto/tools.xml Fri Apr 11 16:47:10 2003 @@ -6,11 +6,11 @@ <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 + things in phpdoc work 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>Command line CVS client</simpara></listitem> <listitem><simpara>Text editor</simpara></listitem> </itemizedlist> The basic process is to check out (~download) the file @@ -19,32 +19,35 @@ tools to edit XML files than a simple text editor, it is just the absolute minimum. Some more useful tools: <itemizedlist> + <listitem><simpara>Visual CVS client</simpara></listitem> <listitem><simpara>XML [capable] editor</simpara></listitem> - <listitem><simpara>Tools to test the edited file</simpara></listitem> + <listitem><simpara>Tools to test your modifications</simpara></listitem> </itemizedlist> In the following 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 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 translations language files. Also you need to set up + 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 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 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. You'll also - need a command line PHP installed to work with the test system. + 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 + other formats and files. It is recommended to set up 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. You'll also need a command line PHP installed + to work with the test system. </para> <para> <emphasis> If you have information about other good XML editors and/or tools - not mentioned here, please send it to the maintainer: + not mentioned here, please send it to the phpdoc mailing list: <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>. </emphasis> </para> @@ -68,7 +71,8 @@ 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. + about every Linux distribution available. Read on for more + information on tools and editors. </para> <para> @@ -122,12 +126,13 @@ </para> <para> - You will need to download the following files: + You will need to download the following files. Note, that you won't + need jadetex if you are not going to generate PDF files, and there + is no need to set up psgml if you are not using Emacs for editing. <itemizedlist> - <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> + <listitem><simpara>jade-1.2.x-y.src.rpm</simpara></listitem> + <listitem><simpara>jadetex-2.x-y.src.rpm</simpara></listitem> + <listitem><simpara>psgml-1.2.x-y.src.rpm</simpara></listitem> <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem> </itemizedlist> </para> @@ -143,10 +148,9 @@ <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. So 3.x docbook files are - not acceptable. The 4.1.2 DTD is available in the phpdoc - directory, and style sheets needed for output generation are - also there. + 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. </para> </note> @@ -177,7 +181,6 @@ Or, you can issue them one by one in the following order: <informalexample> <programlisting> -$ 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 @@ -190,6 +193,11 @@ That's it. You should now have necessary tools installed to edit and verify your PHP documentation contributions. </para> + + <para> + If you choose the OpenJade route, download opensp and openjade. + Compile and install opensp first, and then openjade. + </para> </sect2> </sect1> @@ -221,8 +229,8 @@ </para> <para> - About XML editors, you are encouraged not to use WYSIWYG XML - editors, such as XML Spy, because the often friendly auto-indent, + 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 <link linkend="chapter-maillist">mailing lists</link> and used @@ -273,7 +281,7 @@ 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 + and depend 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> @@ -419,8 +427,9 @@ 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. However - we plan to use XSL in the future for HTML - generation, and possibly PDF generation. + we plan to use XSL in the future for documentation + generation, and XSL is already in use in the 'new + CHM edition'. </para> </note> @@ -444,7 +453,7 @@ <simpara> <literal>make fo</literal> to generate a FO file (Formatting Objects file, which will be used by the FO processor to generate - e.g. pdf-files) + PDF files for example) </simpara> </listitem> </itemizedlist> @@ -466,6 +475,7 @@ <listitem> <simpara> Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink> + (not supported by the build system) </simpara> </listitem> </itemizedlist>