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 [2013/01/24 03:34] – added brief auto-props info 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. +
- +
-//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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools