doc:howto:faq

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Last revisionBoth sides next revision
doc:howto:faq [2009/10/07 17:48] – added 'revert' faq philipdoc:howto:faq [2014/06/20 12:24] – replaced with a new guide sobak
Line 1: Line 1:
-===== Questions related to writing documentation ===== +This page has been removed, in favor of [[http://doc.php.net/tutorial/faq.php|new guide]]
- +
-//If a <refentry> should not emit versioning information, what should I do?// +
-  * Add the **role="noversion"** to its <refentry> +
-  * Example: %%<refentry xml:id="reserved.variables.argc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion//">%% +
- +
-//How do I add a link to a method?// +
-  * Use %%<methodname>Class::Method</methodname>%% +
-  * Note that the case does not matter when adding a link. +
- +
-//I made a change to a file but want to revert this change, how?// +
-  * To merge a file to the previous state: svn merge -rHEAD:PREV filename.xml +
-  * Then, to commit it: svn commit filename.xml -m "reverted previous commit" +
- +
-//I'm about to document a new PHP extension... how should I start?// +
-  * Use the script found within phpdoc/doc-base/scripts/docgen/* +
-  * Example: $ php docgen.php -h +
-  * Example: $ php docgen.php -e simplexml -o outdir +
-  * It creates the skeletons that you edit then commit +
- +
-//I created skeletons that contain a bunch of default text, should I commit it?// +
-  * No, edit the files before commit.  +
-  * Reason 1: Translators +
-  * Reason 2: Temporary often becomes permanent, and bogus text is not good +
- +
-//I documented an extension but it's not building. Why?// +
-  * Likely because it has not yet been added to doc-base/manual.xml.in +
-  * So, add the book to the appropriate reference location there. Open file for examples. +
-  * Or, configure.php is failing... the error should help +
- +
-//I want to contribute to the PHP Manual, how?// +
-  * First, read the [[doc:HOWTO]] +
-  * Check out the sources: $ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en +
-  * For a translation, change the checkout to phpdoc/modules/doc-{lang} where {lang} is the language code +
-  * ... +
- +
-//How do I build and/or test the manual locally?// +
-  * Use phpdoc/configure.php to validate and then [[doc:phd]] to build +
-  * To validate en: **$ php configure.php** +
-  * To validate fr: **$ php configure.php %%--with-lang=fr%%** (Change fr to your given language code) +
-  * To build: **$ phd -d .manual.xml** +
-  * Note: Building is not required, all you must do is check the diff and be sure it validates +
- +
-//Running configure.php ends up Segfaulting, what is up?// +
-  * There are bugs with certain versions of libxml that cause this, so hacks exist to get around it +
-  * To execute the hack, pass in: **$ php configure.php %%--disable-segfault-error%%** +
-  * Note: This disables some error checking and beautification but raw errors will be shown +
-  * Note: Usually the problem is a major XML syntax issue +
- +
-//In the changelog, which order do the PHP versions go?// +
-  * Newest PHP versions go above the older ones +
- +
-//A feature became available in PHP X.Y.Z, how do I document that?// +
-  * Version information for functions is stored inside **versions.xml** within each extension: phpdoc/en/extname/version.xml +
-  * Changes to functions, like added parameters, are documented within changelogs for each page +
-  * Example Text: Feature X has been available since PHP X.Y.Z +
-  * TODO: Research other ways, and the best way, to write this text (including dealing with code examples) +
- +
-//Why does everyone care so much about whitespace?// +
-  * See the following article: [[doc:articles:whitespace]] +
-  * XML is one space, PHP example code is four, and max width is ~78 characters +
-  * Exceptions: <refpurpose> is on one line, ... +
- +
-//A parameter is optional, how is it documented?// +
-  * Like normal, except methodparam receives the choice="opt" attribute, and the <initializer> tag is used to signify the default value. +
-  * Example: %%<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>%% +
- +
-//Do I need to edit these entities* files?// +
-  * No, these are auto-generated by the configure process +
-  * Examples: entities/file-entities.ent and en/reference/foo/entities.bar.xml +
-  * Also, do not commit them +
- +
-// How do I create a patch? // +
-  * In the command-line, go to the SVN directory: +
-  * cd /path/to/phpdoc/svn +
-  * To diff the entire repository: **svn diff** +
-  * To diff a single file: **svn diff foo.xml** +
-  * Consider piping the diff to a file, so: **svn diff foo.xml > mypatch.txt** +
- +
-// How do I apply a patch? // +
-  * Assuming the file with the patch is named apatch.txt +
-  * Go to the directory with the files to be patched +
-  * And run this command: **patch -p0 < apatch.txt** +
- +
-// Is there an online editor? // +
-  * Yes and No.  +
-  * Yes one exists in SVN and is being worked on. +
-  * No it's not yet in use. +
-  * Demo: http://doc.php.net/editor/+
doc/howto/faq.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools