On Wed, Nov 5, 2008 at 16:54, Christopher Jones <[EMAIL PROTECTED]> wrote: > > > Hannes Magnusson wrote: >> If anyone is interested I can write up an step-by-step-by-step >> (American tutorial style) >> guide/tutorial/article/whateveryouwanttocallit on how to write such >> things, > > Yes please do. (For Linux). At the moment I'm putting user comments on > OCI8 manual pages.
This post sparked a little discussion on #php.doc about restructuring our dochowto[1] and potentially move it into the actual documentations including copy&pasteable skeletons of all possible things, but since I doubt anyone has the time to do that the next couple of days then here is something to get you started at least. The first thing you'll need is our documentation build system: $ pear channel-discover doc.php.net $ pear install doc.php.net/phd-beta To make sure it is working correctly, type: $ phd -V Next up is getting the documentation sources: $ cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc Then make sure everything validates and builds correctly before we start: $ cd phpdoc $ php configure.php $ phd -d .manual.xml -t chunkedhtml The configure.php script will validate the documentations and warn you have the build is broken, if everything is fine it will create ".manual.xml" file (~32mb) which the "phd" command reads and produces several thousands of html files and places them into the html/ directory. I recommend you open couple of files in your browser just to make sure everything is fine. Note: You will have to run the configure.php after all your changes to validate them. Now to create an "quick" article I recommend you open up en/reference/xml/encoding.xml, and maybe even en/reference/sdo/examples.xml if you intend on writing a lot of examples, in your favourite editor. As you can see the structure is very simple, and almost like html. For paragraphs you use <para> and for emphasis you use <emphasis>. 95% of other tags you'll just copy&paste from other documents (examples, tables come to mind). The root element (be it <article> or <chapter>, depending on the semantically relevance of your entry) must declare couple of xml namespaces (which you'll copy&paste from any other document) and an xml:id attribute. This attribute will be used as the filename for this page so choose it wisely (no caps please). To create a link to "internal" pages use <link linkend="the.xml.id.of.the.entry.you.want.to.link.to">Link text</link>, or <xref linkend="the.id.." /> if you want to use the entries title. To create link to "external" pages use <link xlink:href="&url.descriptive.entity.name;">link text</a> and place &url.descriptive.entity.name; into entities/global.ent. After writing an article then place the XML file (lowercased) into en/reference/oci8/thefilename.xml and add "&reference.oci8.thefilename;" into book.xml (in the same folder) "at the bottom". OCI8 already has couple of "articles" (for some reason using <chapter> though) which you may want to use as a reference when writing a new one. We have some "magic" to simplify linking to functions and methods, <function>function_name</function> will automatically write out an link to that function for instance, so in theory the only thing you really need to know is docbook<para> == html<p> and <emphasis>==<em>, <literal>==<i>, and how to link to pages and functions (see above). For a full Docbook element reference see[2]. Note: PhD doesn't support'em all, and there is absolutely no need. You will never use more then a handful of these tags anyway. To validate and render your article (remember to add that magic entity, &reference.oci8.thefilename; into book.xml): $ cd ~/phpdoc $ php configure.php # In case errors are thrown, fix them and run again $ phd -d .manual.xml -t chunkedhtml # Creates html/ And then open html/thefilename.html in your favourite browser. If everything looks fine write a couple of words to phpdoc@lists.php.net linking to the new file. Sorry if this reads a bit funny, I have massive problems describing these kind of things to people, but if you have specific questions I am sure we can answer them in more readable manners :) -Hannes [1] http://php.net/dochowto [2] http://www.docbook.org/tdg5/en/html/pt02.html
