doc:howto:faq
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
| doc:howto:faq [2009/03/31 19:03] – added %% to disable wiki markup where appropriate (%%--%%) philip | doc:howto:faq [2013/01/24 03:35] – :( philip | ||
|---|---|---|---|
| Line 3: | Line 3: | ||
| //If a < | //If a < | ||
| * Add the **role=" | * Add the **role=" | ||
| - | * Example: %%< | + | * Example: %%< |
| //How do I add a link to a method?// | //How do I add a link to a method?// | ||
| * Use %%< | * Use %%< | ||
| * Note that the case does not matter when adding a link. | * 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/ | ||
| + | * Add the link there (to global.ent) | ||
| + | * The global.ent markup might look like: %%< | ||
| + | * Add the link to the documentation (foo.xml) | ||
| + | * The markup might look like: %%<link xlink: | ||
| + | * Be sure the file understands the namespace with %%xmlns: | ||
| + | |||
| + | //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 " | ||
| //I'm about to document a new PHP extension... how should I start?// | //I'm about to document a new PHP extension... how should I start?// | ||
| - | * Use phpdoc/ | + | * Use the script found within |
| * Example: $ php docgen.php -h | * Example: $ php docgen.php -h | ||
| - | * It creates the skeletons then each file should | + | |
| + | | ||
| + | |||
| + | //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/ | ||
| + | * So, add the book to the appropriate reference location there. Open file for examples. | ||
| + | * Or, configure.php is failing... the error should | ||
| //I want to contribute to the PHP Manual, how?// | //I want to contribute to the PHP Manual, how?// | ||
| * First, read the [[doc: | * First, read the [[doc: | ||
| - | * Check out the sources: $ cvs -d :pserver:cvsread@cvs.php.net:/ | + | * Check out the sources: $ svn checkout http://svn.php.net/ |
| - | * For a translation, | + | * For a translation, |
| * ... | * ... | ||
| Line 35: | Line 58: | ||
| //In the changelog, which order do the PHP versions go?// | //In the changelog, which order do the PHP versions go?// | ||
| * Newest PHP versions go above the older ones | * 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: %%< | ||
| + | |||
| + | //How do I add markup for a configure option?// | ||
| + | * Example: %%< | ||
| + | |||
| + | //When adding a < | ||
| + | * Typically titles are useful for notes, but it's not required. | ||
| + | * Syntax: %%< | ||
| + | |||
| + | //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/ | ||
| + | * 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?// | //Why does everyone care so much about whitespace?// | ||
| Line 40: | Line 79: | ||
| * XML is one space, PHP example code is four, and max width is ~78 characters | * XML is one space, PHP example code is four, and max width is ~78 characters | ||
| * Exceptions: < | * Exceptions: < | ||
| + | |||
| + | //A parameter is optional, how is it documented?// | ||
| + | * Like normal, except methodparam receives the choice=" | ||
| + | * Example: %%< | ||
| + | |||
| + | //Do I need to edit these entities* files?// | ||
| + | * No, these are auto-generated by the configure process | ||
| + | * Examples: entities/ | ||
| + | * Also, do not commit them | ||
| // How do I create a patch? // | // How do I create a patch? // | ||
| - | * In the command-line, | + | * In the command-line, |
| - | * cd / | + | * cd / |
| - | * To diff the entire repository: **cvs diff -u** | + | * To diff the entire repository: **svn diff** |
| - | * To diff a single file: **cvs diff -u foo.xml** | + | * To diff a single file: **svn diff foo.xml** |
| - | * Consider piping the diff to a file, so: **cvs diff -u foo.xml > mypatch.txt** | + | * Consider piping the diff to a file, so: **svn diff foo.xml > mypatch.txt** |
| // How do I apply a patch? // | // How do I apply a patch? // | ||
| Line 52: | Line 100: | ||
| * Go to the directory with the files to be patched | * Go to the directory with the files to be patched | ||
| * And run this command: **patch -p0 < apatch.txt** | * 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:// | ||
| + | |||
| + | // How often is the documentation built? // | ||
| + | * Weekly on mirrors, several times daily on the doc server | ||
| + | * For specifics, see the [[doc: | ||
| + | |||
| + | // 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/ | ||
| + | * 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? | ||
| + | |||
| + | Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed): | ||
| + | <code shell> | ||
| + | php doc-base/ | ||
| + | phd --docbook doc-base/ | ||
| + | php doc-base/ | ||
| + | </ | ||
| + | Undocumented documentation (skeletons exist, but only prototypes and basic information) can be found here: http:// | ||
| + | |||
| + | // What .subversion/ | ||
| + | |||
| + | < | ||
| + | *.xml = svn: | ||
| + | </ | ||
doc/howto/faq.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1