cvs: phd /docs/phd-guide phd-guide.xml
| From: | Christian Weiske | Date: | Mon, 16 Feb 2009 20:27:07 +0000 |
| Subject: | cvs: phd /docs/phd-guide phd-guide.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-3286@lists.php.net to get a copy of this message | ||
cweiske Mon Feb 16 20:27:07 2009 UTC
Modified files:
/phd/docs/phd-guide phd-guide.xml
Log:
Integrate Slango's changes about how to render the php manual.
http://cvs.php.net/viewvc.cgi/phd/docs/phd-guide/phd-guide.xml?r1=1.4&r2=1.5&diff_format=u
Index: phd/docs/phd-guide/phd-guide.xml
diff -u phd/docs/phd-guide/phd-guide.xml:1.4 phd/docs/phd-guide/phd-guide.xml:1.5
--- phd/docs/phd-guide/phd-guide.xml:1.4 Sat Jan 31 11:32:50 2009
+++ phd/docs/phd-guide/phd-guide.xml Mon Feb 16 20:27:07 2009
@@ -55,7 +55,7 @@
$ phd --version
PhD version: 0.4.2
-Copyright (c) 2008 The PHP Documentation Group</screen>
+Copyright (c) 2008-2009 The PHP Documentation Group</screen>
<para>That's it!</para>
</section>
@@ -67,7 +67,7 @@
released yet, you can use PhD from CVS.</para>
<screen>$ cvs -d :pserver:cvsread@cvs.php.net:/repository checkout phd
-... ouput
+... output
$ pear channel-discover doc.php.net
Adding Channel "doc.php.net" succeeded
@@ -77,7 +77,7 @@
$ phd --version
PhD version: phd-from-cvs
-Copyright (c) 2008 The PHP Documentation Group</screen>
+Copyright (c) 2008-2009 The PHP Documentation Group</screen>
<para>And now you're done.</para>
</section>
@@ -87,13 +87,127 @@
<chapter>
<title>Using PhD to render documentation</title>
- <para>FIXME</para>
+ <section>
+ <title>Rendering the PHP Documentation Sources</title>
+
+ <sidebar>
+ <title>Getting the PHP Documentation Sources</title>
+
+ <para>To get the PHP documentation sources, simply check them out from
+ CVS with the following command.</para>
+
+ <screen>$ cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
+... output</screen>
+
+ <para>To prepare the documentation, <command>cd</command> to the
+ phpdoc directory, and run configure.php.</para>
+
+ <screen>$ php configure.php</screen>
+
+ <para>This process will generate a .manual.xml file in the current
+ directory, which is what we need for building the docs. Now we're
+ ready to proceed with running PhD to generate the PHP docs.</para>
+ </sidebar>
+
+ <para>To quickly become familiar with using PhD, you can download the
+ PHP documentation sources and render those.Running PhD to render the
+ docs is surprisingly simple, so we'll start with that.</para>
+
+ <screen>$ phd -d .manual.xml
+... status messages</screen>
+
+ <para>After a running for a few moments, PhD will generate PHP-web and
+ HTML output into <literal>build/en/</literal>. The HTML output includes
+ an <filename>html</filename> directory and
+ <literal>bightml.html</literal>, which is the documentation rendered as
+ one very large HTML file. The PHP-web sources are the documentation
+ prepared for use on php.net or a mirror.</para>
+
+ <para>So now that you've seen the fruits of your labor, let's take a
+ closer look at PhD and see what capabilities are available to us.</para>
+
+ <screen>$ phd --help
+PhD version: phd-from-cvs
+Copyright (c) 2008-2009 The PHP Documentation Group
+
+ -v
+ --verbose <int> Adjusts the verbosity level
+ -f <formatname>
+ --format <formatname> The build format to use
+ -t <themename>
+ --theme <themename> The theme to use
+ -I
+ --noindex Do not index before rendering but load from cache (false)
+ -d <filename>
+ --docbook <filename> The Docbook file to render from
+ -p <id[=bool]>
+ --partial <id[=bool]> The ID to render, optionally skipping its children
chunks (default to true; render children)
+ -s <id[=bool]>
+ --skip <id[=bool]> The ID to skip, optionally skipping its children chunks
(default to true; skip children)
+ -l <formats/themes>
+ --list <formats/themes> Print out the supported formats/themes (default: both)
+ -o <directory>
+ --output <directory> The output directory (default: .)
+ -L <language>
+ --lang <language> The language of the source file (used by the CHM theme).
(default: en
+ -c <bool>
+ --color <bool> Enable color output when output is to a terminal
(default: false)
+ -g <classname>
+ --highlighter <classname> Use custom source code highlighting php class
+ -V
+ --version Print the PhD version information
+ -h
+ --help This help
+
+Most options can be passed multiple times for greater affect.
+NOTE: Long options are only supported using PHP5.3</screen>
+
+ <para>As you can see, there are plenty of options to look into in PhD.
+ The most important options are those which allow you to select a format
+ and theme to output your documentation to.</para>
+
+ <screen>$ phd --list
+Supported formats:
+ xhtml
+ manpage
+ pdf
+Supported themes:
+ xhtml:
+ phpweb
+ chunkedhtml
+ bightml
+ chmsource
+ phpkdevelop
+ howto
+ pearweb
+ pearbightml
+ pearchunkedhtml
+ pearchm
+ manpage:
+ phpfunctions
+ pdf:
+ phppdf
+ phpbigpdf</screen>
+
+ <para>You can tell by the output of the <literal>--list</literal> option
+ that PhD can also be used to render the docs as a PDF file, or as Unix
+ Man Pages.</para>
+
+ <para>To select a format and theme, you must use the <literal>-f
+ [formatName]</literal> and <literal>-t [themeName]</literal> options.
+ Both options are required if one of them is used.</para>
+
+ <screen>$ phd -f manpage -t phpfunctions -d .manual.xml</screen>
+
+ <para>This command will output the documentation for PHP functions in
+ the Unix Man page format.</para>
+ </section>
</chapter>
<chapter>
<title>DocBook extensions</title>
- <para>PhD has been tailored for PHP and PEAR manual. To make writing
+ <para>PhD has been tailored for PHP and PEAR manuals. To make writing
documentation as easy as possible, some own tags have been added to the
DTD.</para>