<!DOCTYPE article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!ENTITY % global.entities SYSTEM "global.ent">
%global.entities;
<!ENTITY howto.author "&email.stig;">
<!ENTITY howto.maintainer "&email.stig;">
]>

 <article id="howto">

  <artheader>
   <author>
    <firstname>Stig</firstname>
    <surname>Sther bakken</surname>
    <authorblurb>
     <simpara>
      (<ulink url="mailto:&howto.author;">&howto.author;</ulink>)
     </simpara>
    </authorblurb>
   </author>
   <title>PHP3 Documentation HOWTO</title>
  </artheader>

  <sect1 id="aboutdocs">
   <title>About the PHP3 Documentation</title>
   <para>
    PHP3's documentation is written in SGML.  SGML is an
    ISO-standardized language for defining markup formats.  HTML is
    defined with SGML.  XXX LEFT HERE
   </para>
  </sect1>

  <sect1 id="howto-tools">
   <title>SGML Tools</title>
   <sect2>
    <title>SGML Editor</title>
    <simpara>
     Although it is possible to use a simple text editor such as vi or
     notepad to write the SGML, it is recommended to use an SGML editor
     that helps you along and makes sure your document is proper SGML
     conforming to the used document type definition (DTD).

    <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>
      <listitem><simpara>
	<ulink url="&url.emacs-nt">GNU Emacs for Windows NT/95</ulink>
      <listitem><simpara>
	<ulink url="&url.psgml;">PSGML 1.0.1 (SGML mode for Emacs)</ulink>
     </itemizedlist>

    <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>
     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>
     <emphasis>
      If you have information about SGML editors, please send it to
      the current maintainer, <ulink
      url="&howto.maintainer;">&howto.maintainer;</ulink>.
     </emphasis>

   </sect2>
   <sect2>
    <title>SGML Conversion Tools</title>

    <para>
     The PHP3 documentation is written in <ulink
      url="&url.docbook;">DocBook</ulink>, which is a widely recognized
     SGML DTD for writing technical documentation.

    <para>
     The formatting is done using <ulink url="&url.jade;">Jade</ulink>
     and <ulink url="&url.dbstyle;">The Modular DocBook
      Stylesheets</ulink>.  Pointers:
     <itemizedlist>
      <listitem><para><ulink url="&url.jade;">Jade</ulink>
      <listitem><para><ulink url="&url.dbstyle;">The Modular DocBook
	 Stylesheets</ulink>
     </itemizedlist>

   </sect2>
  </sect1>

  <sect1 id="howto-files">
   <title>File Overview</title>
   <para>
    <variablelist>

     <varlistentry id="file-manual.sgml">
      <term><filename>manual.sgml</filename></term>
      <listitem><simpara>
	The main file for the documentation.  It is supposed to be only
	"glue" between the other parts, containing only part titles and
	entity references to chapters.
     </varlistentry>

     <varlistentry id="file-chapters.ent">
      <term><filename>chapters.ent</filename></term>
      <listitem><simpara> Contains entity definitions for all chapters
	and appendices.  Entities for the main chapters have names of
	the form
	<sgmltag>chapter.<replaceable>name</replaceable></sgmltag>,
	those for the reference (functions) chapters have names of the
	form
	<sgmltag>reference.<replaceable>name</replaceable></sgmltag>,
	and appendices have names of the form
	<sgmltag>appendix.<replaceable>name</replaceable></sgmltag>.
     </varlistentry>

    </variablelist>
   </para>
  </sect1>

  <sect1 id="howto-writing">
   <title>Writing SGML documents</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>
    <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.
    <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>

   <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>
     Element-by-element DTD reference:
     <ulink url="&url.docbook-dtdref;">&url.docbook-dtdref;</ulink>.
    <para>
     Get Going With DocBook, Notes for Hackers:
     <ulink url="&url.docbook-intro;">&url.docbook-intro;</ulink>.
    <para>
    </para>
   </sect2>

   <!-- a name="phpdoc.dtd"></a><h3>2.3.1. Document structure</h3>

  </sect1>

  <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 "]&gt;".

  <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>&lt;!entity ldapref system "functions/ldap.sgml"&gt;</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>
   &lt;chapt&gt;Internal functions
   ...
  <b>&amp;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:ssb@guardian.no">ssb@guardian.no</a></i>


   -->

  </sect1>

 </article>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"howto.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->