goba Sat Sep 8 16:50:26 2001 EDT
Modified files:
/phpdoc/howto howto.ent howto.xml
Log:
Adding all the text from phpdoc/howto.xml, some in comments.
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.2 phpdoc/howto/howto.ent:1.3
--- phpdoc/howto/howto.ent:1.2 Sat Sep 8 16:08:22 2001
+++ phpdoc/howto/howto.ent Sat Sep 8 16:50:26 2001
@@ -12,8 +12,13 @@
<!ENTITY url.php.manual.plain "http://www.php.net/manual/html/";>
<!ENTITY url.php.manual.pdf "http://www.php.net/distributions/manual.pdf";>
<!ENTITY url.php.manual.rtf "http://www.php.net/distributions/manual.rtf";>
+
<!ENTITY url.cvs "http://www.cvshome.org/";>
<!ENTITY url.docbookdtd "http://www.oasis-open.org/docbook/";>
+<!ENTITY url.docbook-ref "http://www.ora.com/davenport/";>
+<!ENTITY url.docbook-dtdref "http://www.ora.com/homepages/dtdparse/docbook/3.0/";>
+<!ENTITY url.docbook-intro
+"http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html";>
+
<!ENTITY url.nwalsh "http://nwalsh.com/docbook/dsssl/";>
<!ENTITY url.jade "http://www.jclark.com/jade/";>
<!ENTITY url.dtdref "http://www.ora.com/homepages/dtdparse/docbook/3.0/";>
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.3 phpdoc/howto/howto.xml:1.4
--- phpdoc/howto/howto.xml:1.3 Sat Sep 8 16:08:22 2001
+++ phpdoc/howto/howto.xml Sat Sep 8 16:50:26 2001
@@ -193,11 +193,6 @@
</para>
<para>
- A DTD reference for DocBook can be found <ulink
- url="&url.dtdref;">here</ulink>.
- </para>
-
- <para>
In addition to the above tools, you will need your favorite text
editor and a working <ulink url="&url.cvs;">CVS</ulink>
installation. Although it is possible to use a simple text editor
@@ -212,8 +207,8 @@
<para>
You will also need <ulink url="&url.autoconf;">autoconf</ulink> to
- build the <emphasis>phpdoc</emphasis> GNU configure script. Many
- distributions come with autoconf already installed. The latest
+ build the <emphasis>phpdoc</emphasis> GNU configure script. Many
+ distributions come with autoconf already installed. The latest
copy can be found at:
<itemizedlist>
<listitem>
@@ -221,14 +216,22 @@
</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>
<sect2 id="obtaining-tools">
<title>Obtaining the Tools</title>
<para>
To simplify the installation process of the tools necessary to
- write PHP documentation, I have chosen to detail how to download
- and install the source RPMs from a sourceware mirror. You will
+ 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>
@@ -236,7 +239,7 @@
<para>
These tools are all seperate 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
+ so. You do not have to use these source RPMs, but installing from
the author's seperate packages is out of the scope of this HOWTO.
</para>
@@ -274,18 +277,17 @@
</para>
<para>
- These packages are updated from time to time. Please make sure
- you download the latest version available from the above sites
+ These packages are updated from time to time. Please make sure
+ you download the latest version available from the above sites.
</para>
</sect2>
-
<sect2 id="installing-tools">
<title>Installing the Tools</title>
<para>
- Installing the tools is simple. If you downloaded all of the
+ 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>
@@ -313,7 +315,7 @@
</para>
<para>
- That's it. You should now have necessary tools installed to edit
+ That's it. You should now have necessary tools installed to edit
and verify your PHP documentation contributions.
</para>
@@ -323,8 +325,53 @@
<!-- Section1: getting-started: END -->
+ <!-- Section1: files -->
+
+ <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 there is no need to edit the file.
+ </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,
+ emial addresses, and "macros" are stored.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect1>
+
+ <!-- Section1: files: END -->
- <!-- Section1: cvs -->
+ <!-- Section1: using-cvs -->
<sect1 id="using-cvs">
<title>Using CVS</title>
@@ -658,8 +705,6 @@
<!-- Section1: using-cvs: END -->
-
-
<!-- Section1: generating-docs -->
<sect1 id="generating-docs">
@@ -813,6 +858,71 @@
<!-- Section1: generating-docs: END -->
+ <!-- Section1: writing XML documents -->
+
+ <sect1 id="writing-xml">
+ <title>Writing XML documents</title>
+
+ <sect2>
+ <title>DocBook for Native Speakers of HTML</title>
+ <simpara>
+ 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.
+ </simpara>
+ <para>
+ Although there are few 1:1 mappings between HTML and DocBook
+ tags, here is a little list that should at least make life easier
+ for the HTML proficient:
+ <table>
+ <title>Tags in HTML vs. DocBook</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>HTML tag</entry>
+ <entry>DocBook tag</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><markup>DL</markup></entry>
+ <entry><sgmltag>VariableList</sgmltag></entry>
+ </row>
+ <row>
+ <entry><markup>OL</markup></entry>
+ <entry><sgmltag>OrderedList</sgmltag></entry>
+ </row>
+ <row>
+ <entry><markup>UL</markup></entry>
+ <entry><sgmltag>ItemizedList</sgmltag></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>DocBook reference</title>
+ <para>
+ General information and documentation for DocBook can be found at
+ <ulink url="&url.docbook-ref;">&url.docbook-ref;</ulink>.
+ </para>
+ <para>
+ Element-by-element DTD reference:
+ <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>
+
+ <!-- Section1: writing-xml-document: END -->
<!-- Section1: working-with-emacs -->
@@ -832,6 +942,12 @@
<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>
@@ -843,6 +959,46 @@
</sect1>
+<!--
+
+ This text was in the howto made by Stig. Maybe some Emacs
+ people can confirm this and put them to the appropriate places.
+ Entities used here are defined in global.ent!
+
+ <para>
+ A very good (and free) SGML editor is Emacs+PSGML. Emacs is
+ ported to Windows 95/NT. A few pointers:
+ <itemizedlist>
+ <listitem><simpara>
+ <ulink url="&url.emacs-src;">GNU Emacs Source</ulink></simpara></listitem>
+ <listitem><simpara>
+ <ulink url="&url.emacs-nt">GNU Emacs for Windows
+NT/95</ulink></simpara></listitem>
+ <listitem><simpara>
+ <ulink url="&url.psgml;">PSGML 1.0.1 (SGML mode for
+Emacs)</ulink></simpara></listitem>
+ </itemizedlist></para>
+
+ <para>
+ You have to add this to your <filename>~/.emacs</filename> file to
+ make sure Emacs finds the installed files:
+ <informalexample><programlisting role="emacs-lisp">
+ (add-to-list 'load-path
+ "<replaceable>PREFIX</replaceable>/share/emacs/site-lisp/psgml")
+ (autoload 'sgml-mode "psgml" "Major mode for editing SGML files." t)
+ </programlisting></informalexample>
+
+ where <replaceable>PREFIX</replaceable> is the base installation
+ directory where you installed PSGML (typically
+ <filename class="directory">/usr/local</filename>).</para>
+
+ <para>
+ For Windows users without <abbrev>NTFS</abbrev>, the
+ <filename>.emacs</filename> file is called
+ <filename>_emacs</filename>, and resides in the directory given
+ by the <envar>HOME</envar> environment variable or <filename
+class="directory">C:/</filename>.
+ </para>
+
+-->
+
<!-- Section1: working-with-emacs: END -->
@@ -906,7 +1062,124 @@
<!-- Section1: misc-notes: END -->
+ <!--
+
+ ! These paras are from the howto.xml made by Stig (this
+ ! is actually HTML). Can be useful to make the new XML
+ ! file section.
+
+ <a name="connecting.phpdoc"></a><h2>3.1. New SGML files</h2>
+
+ The main file for the documentation is <tt>manual.sgml</tt>. This
+ file uses <i>entities</i> (can be compared to a combination of #define
+ and #include in C) to include text from other files. The entities
+ that include the PHPDOC files are defined in the <i>preamble</i> of
+ <tt>manual.sgml</tt>, which is the section between the "[" character
+ on the first (DOCTYPE) line and "]>".
+
+ <p> Steps involved in connecting a new PHPDOC file:
+
+ <ol>
+ <li> Let us say you have written functions/ldap.phpdoc. You should
+ then add this to the preamble:
+ <pre>
+ <b><!entity ldapref system "functions/ldap.sgml"></b>
+ </pre>
+
+ This tells the SGML parser that when "ldapref" is referenced it
+ should read the file <tt>functions/ldap.sgml</tt>.<p> <em>Note
+ that the file name extension used here is not <tt>.phpdoc</tt>,
+ but <tt>.sgml</tt>. The Makefile handles the conversion.</em>
+ <p>
+
+ <li> Refer to the <i>ldapref</i> entity where you want to include it.
+ Keep in mind that PHPDOC documents are converted into LINUXDOC
+ sections. Internal functions should be added to the "internal
+ functions" chapter in <tt>chapters/functions.sgml</tt>. Add
+ something like this (the bold part is what to add):
+ <pre>
+ <chapt>Internal functions
+ ...
+ <b>&ldapref;</b>
+ ...
+ </pre>
+
+ <li> Then, to make sure the .phpdoc file is converted to .sgml,
+ you have to tell make about it. Add the <u>.sgml</u> file to
+ the FUNCREF variable in <tt>Makefile.in</tt>. Example (the bold
+ text is the change):
+ <pre>
+ FUNCREF=functions/oracle.sgml \
+ <b>functions/ldap.sgml \</b>
+ functions/math.sgml \
+ functions/mysql.sgml \
+ functions/pgsql.sgml \
+ functions/strings.sgml \
+ functions/adabas.sgml
+ </pre>
+
+ <li> Finally, regenerate <tt>Makefile</tt>:
+ <pre>
+ (cd .. ; ./config.status)
+ </pre>
+
+ </ol>
+
+ <a name="connecting.labels"></a><h2>3.2. Label name conventions</h2>
+
+ When making or refering to labels in the LINUXDOC files, there are
+ some conventions that should kept:
+
+ <ul>
+ <li> Internal functions have labels of the form
+ <tt>func:<i>function_name</i></tt>.
+ <li> Arguments to configure (when installing) have labels like the
+ argument names. For example, the -with-system-regex option has
+ the label <tt>with_system_regex</tt>
+ </ul>
+ <hr>
+
+ <a name="convert"></a><h1>4. Converting from SGML</h1>
+
+ <a name="convert.html"></a><h2>4.1. HTML</h2>
+
+ You convert all the SGML files to HTML by running "<tt>make html</tt>".
+ The current Makefile setup splits the chapters and appendices into
+ separate files. The main file is called <tt>manual.html</tt>, and the
+ other files are <tt>manual-<i>n</i>.html</tt>.
+
+ <p>If sgml2html shows some error messages like this:
+ <pre>
+ sgml2html -l -2 manual.sgml
+ Making manual.html from manual.sgml.
+ Problem with @@ref(id = security)!
+ Problem with @@ref(id = func:include)!
+ Problem with @@ref(id = func:pg_pconnect)!
+ Problem with @@ref(id = func:stripslashes)!
+ </pre>
+ ..it is because of references that point to labels that do not exist.
+ See <a href="#connecting.labels">label name conventions</a>.
+
+ <a name="convert.text"></a><h2>4.2. Plain text</h2>
+
+ You convert all the SGML files to plain text by running "<tt>make
+ text</tt>". The results can be seen in <tt>manual.txt</tt>.
+
+ <p> <i>Note: there seems to be a bug in the 0.99.0 sgml2txt filter
+ that messes up the section numbering in the table of contents.</i>
+
+ <a name="convert.text"></a><h2>4.3 Other formats...</h2>
+
+ SGML-Tools supports converting SGML to info, LaTeX, lyx and rtf as
+ well. PHP's documentation should be convertable to any of these
+ formats in theory, but I have not tested it good enough to document it
+ here yet.
+
+ <p><hr>
+ <i>Send feedback and questions to
+ <a href="mailto:[EMAIL PROTECTED]";>[EMAIL PROTECTED]</a></i>
+ -->
</article>
