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
doc:howto:faq [2013/01/24 03:35] – WS philipdoc:howto:faq [2017/09/22 13:28] (current) – external edit 127.0.0.1
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. +
- +
-//How do I add an external link to the documentation?// +
-  * All external links are added to doc-base/entities/global.ent +
-  * Add the link there (to global.ent) +
-  * The global.ent markup might look like: %%<!ENTITY spec.google "http://www.google.com/">%% +
-  * Add the link to the documentation (foo.xml) +
-  * The markup might look like: %%<link xlink:href="&spec.google;">google spec</link>%% +
-  * Be sure the file understands the namespace with %%xmlns:xlink="http://www.w3.org/1999/xlink"%% in the root element +
- +
-//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 +
- +
-//In the changelog, a change happened in two PHP versions. How do I enter this?// +
-  * Multiple versions are separated by a comma, with the lesser version first. Example: %%<entry>5.2.11, 5.3.1</entry>%% +
- +
-//How do I add markup for a configure option?// +
-  * Example: %%<option role="configure">--enable-debug</option>%% +
- +
-//When adding a <note>, should I add a <title>?// +
-  * Typically titles are useful for notes, but it's not required. +
-  * Syntax: %%<note><title>foo</title><para>note contents</para></note>%% +
- +
-//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: https://edit.php.net/ +
- +
-// How often is the documentation built? // +
-  * Weekly on mirrors, several times daily on the doc server +
-  * For specifics, see the [[doc:builds|doc builds]] article +
- +
-// I see example.outputs and example.outputs.similar entities, what's the difference? // +
-  * The example.outputs.similar entity is used when the output may differ between executions or machines +
-  * The example.outputs entity output will always, under all conditions, be the same +
- +
-// I need to add a piece of text to three or more pages, how? // +
-  * Add the snippet to en/language-snippets.ent as an entity +
-  * Link to the entity within the desired pages +
-  * This is done so translators can update one version of this text +
- +
-// How do I find missing documentation? Or undocumented (proto only) documentation? // +
- +
-Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed): +
-<code shell> +
-php doc-base/configure.php +
-phd --docbook doc-base/.manual.xml --package PHP --format php +
-php doc-base/scripts/check-missing-docs.php -d output/index.sqlite +
-</code> +
-Undocumented documentation (skeletons exist, but only prototypes and basic information) can be found here: http://doc.php.net/php/undoc_functions.php +
- +
-// What .subversion/config settings should I have set? +
- +
-<code> +
-*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL +
-</code>+
doc/howto/faq.1358998515.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools