VladPolskiy/php-web-doc
1
0
Fork 0
mirror of https://github.com/php/web-doc.git synced 2025-08-10 02:56:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve questions order in FAQ

Browse Source
This commit is contained in:
Sobak
2014-06-16 15:46:33 +02:00
parent bd62c82b29
commit 62d17412a4
1 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
tutorial/faq.md
View File

@ -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