com web/doc: Improve questions order in FAQ: tutorial/faq.md

Commit: 62d17412a491e55af703c81c66205e6a9c98c9d4 Author: Sobak <msobaczewski@gmail.com> Mon, 16 Jun 2014 15:46:33 +0200 Parents: bd62c82b29e7e0a48891787841a55808cae0ca30 Branches: master Link: http://git.php.net/?p=web/doc.git;a=commitdiff;h=62d17412a491e55af703c81c66205e6a9c98c9d4 Log: Improve questions order in FAQ Changed paths: M tutorial/faq.md Diff: diff --git a/tutorial/faq..md b/tutorial/faq.md index 8531ada..e34eced 100644 --- a/tutorial/faq.md +++ b/tutorial/faq.md @@ -1,25 +1,5 @@ # Frequently Asked Questions -## 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. Markup looks as follows: -``` -<!ENTITY spec.google "http://www.google.com/"> -``` -Then you can use this syntax in documentation: -``` -<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 use svn merge -rHEAD:PREV filename.xml, then commit your changes. - ## I'm about to document a new PHP extension. How should I start? Change your working directory to phpdoc/doc-base/scripts/docgen/ and execute following command: $ php docgen.php -e simplexml -o outdir. It creates the skeletons that you edit then commit. @@ -35,6 +15,29 @@ 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. +## Is there an online editor? +Yes, just go to https://edit.php.net + +## How often is the documentation built? +Weekly, but there is special mirror - https://doc.php.net - where documentation is build every six hours. + +## 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. + +## 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 an external link to the documentation? +All external links are added to doc-base/entities/global.ent. Markup looks as follows: +``` +<!ENTITY spec.google "http://www.google.com/"> +``` +Then you can use this syntax in documentation: +``` +<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. + ## In the changelog, which order do the PHP versions go? Newest PHP versions go above the older ones. @@ -62,16 +65,6 @@ to signify the default value. Example syntax: <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, also do not commit them. -Examples: entities/file-entities.ent and en/reference/foo/entities.bar.xml - -## Is there an online editor? -Yes, just go to https://edit.php.net - -## How often is the documentation built? -Weekly, but there is special mirror - https://doc.php.net - where documentation is build every six hours. - ## 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. @@ -88,6 +81,13 @@ phd --docbook doc-base/.manual.xml --package PHP --format php php doc-base/scripts/check-missing-docs.php -d output/index.sqlite ``` +## I made a change to a file but want to revert this change, how? +To merge a file to the previous state use svn merge -rHEAD:PREV filename.xml, then commit your changes. + +## Do I need to edit these entities* files? +No, these are auto-generated by the configure process, also do not commit them. +Examples: entities/file-entities.ent and en/reference/foo/entities..bar.xml + ## What .subversion/config settings should I have set? ``` *.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL