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

Port useful articles as apendices

Browse Source
This commit is contained in:
Sobak
2014-06-20 11:10:13 +02:00
parent 6df86aca73
commit 1ff56ef680
4 changed files with 223 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
tutorial/intro.md
View File

@ -27,6 +27,9 @@ This guide uses some terminology that you have to know. Don't worry, it's easy:
## Appendices
- [FAQ](faq.php)
- [PHP Manual builds](builds.php)
- [Why whitespace is important in phpdoc](whitespace.php)
- [User Note Editing Guidelines](user-notes.php)
- [Setting up Documentation environment](local-setup.php)
## Feedback
Feedback is most certainly welcome on this document. Without your submissions and input, this document wouldn't exist.

147
tutorial/local-setup.md Normal file
View File

@ -0,0 +1,147 @@
# Setting up Documentation environment
This appendix describes how to check out, build and view the PHP documentation locally.
Viewing results as a php.net mirror isn't a simple process, but it can be done.
The following is one route, and it assumes:
- PHP 5.3+ is available
- A web server, specifically (in this example) Apache
- The rsync tool is available
- A basic level of shell/terminal usage, or know that shell commands follow a `$` below
- A desire to build and display the documentation locally
- Your PHP Documentation path will be: `/tmp/svn/doc-en` (change this no doubt)
- Your local mirror path will be: `/home/sites/myphpnet/` (change this no doubt)
- Your local hostname will be: `http://mydocs.site/` (change this no doubt)
- You are using Linux or a Mac (@todo Make this guide Windows friendly)
If you're interested in simply setting up a local PHP mirror (and NOT build the documentation) then
simply follow the php.net [mirroring guidelines](http://php.net/mirroring) and ignore this document.
## Checkout the php documentation from SVN
Assumptions: This assumes using /tmp as the root directory, and checkout of the English language.
Adjust accordingly.
### Option A: Traditional
```
$ mkdir /tmp/svn
$ cd /tmp/svn
$ svn co https://svn.php.net/repository/phpdoc/modules/doc-en doc-en
$ cd /tmp/svn/doc-en
```
### Option B: Automated
```
$ cd /tmp
$ wget https://svn.php.net/repository/phpdoc/doc-base/trunk/scripts/create-phpdoc-setup.php
$ php create-phpdoc-setup.php -h
$ php create-phpdoc-setup.php -b /tmp/svn -l en
$ cd /tmp/svn/doc-en
```
## Validate the PHP Documentation XML
```
$ cd /tmp/svn/doc-en
$ php doc-base/configure.php
```
## Build the documentation
We use PhD to build the documentation. It takes the source that configure.php generates, and builds
and formats the PHP documentation. PhD offers several formats including HTML (multiple or single page),
PDF, Man, Epub, and others, including PHP which is what we use at php.net.
### Install PhD
#### Option A: Traditional
Requirements: PEAR, and an SSL enabled PHP version greater than 5.3.0.
```
$ pear install phpdocs/PhD
$ pear install phpdocs/PhD_Generic phpdocs/PhD_PHP
$ phd --help
```
#### Option B: Automated
The create-phpdoc-setup.php installs PhD.
### Use PhD to build the documentation
```
$ cd /tmp/svn/doc-en
$ php doc-base/configure.php
$ phd --docbook /tmp/svn/doc-en/doc-base/.manual.xml --package PHP --format php --output mydocs
$ cd /tmp/svn/doc-en/mydocs/php-web/
$ ls
```
Note: This builds the php.net version of the documentation, but does not contain
the files and includes used to run php.net. In other words, files like the php.net
headers and footers are not built by PhD and are instead stored in a separate git
module (web-php).
Alternative: The XHTML format is simple and does not require mirroring the php.net
website. The following builds manual pages as plain HTML files:
```
$ cd /tmp/svn/doc-en
$ phd --docbook /tmp/svn/doc-en/doc-base/.manual.xml --package PHP --format xhtml --output mydocs
$ cd /tmp/svn/doc-en/mydocs/php-chunked-xhtml/
$ open function.strlen.html
```
## Set up a local php.net mirror
### Download (rsync) the php.net files
```
$ rsync -avzC --timeout=600 --delete --delete-after --exclude='manual/**' --exclude='distributions/**' --exclude='extra/**' --exclude='backend/notes/**' rsync.php.net::phpweb /home/sites/myphpnet/
```
### Symlink (or move) the generated PHP documentation to your local php.net sources
```
$ ln -s /tmp/svn/doc-en/mydocs/php-web /home/sites/myphpnet/manual/en
```
### Configure Apache
The official PHP [mirroring documentation](http://php.net/mirroring) contains
a detailed example for doing this, but here's a simpler example. Open the Apache
configuration file (e.g., `apache.conf`, `httpd.conf`, `apache/conf.d/virtualhosts/myphp.site`, ...)
and add the virtual host
```
<VirtualHost *>
<Directory /home/sites/myphpnet>
Options -Indexes -MultiViews
</Directory>
ServerName myphp.site
DocumentRoot /home/sites/myphpnet/
# Set directory index
DirectoryIndex index.php index.html
# Handle errors with local error handler script
ErrorDocument 401 /error.php
ErrorDocument 403 /error.php
ErrorDocument 404 /error.php
# Add types not specified by Apache by default
AddType application/octet-stream .chm .bz2 .tgz .msi
AddType application/x-pilot .prc .pdb
# Set mirror's preferred language here
SetEnv MIRROR_LANGUAGE "en"
RemoveHandler var
# Turn spelling support off (which would break URL shortcuts)
<IfModule mod_speling.c>
CheckSpelling Off
</IfModule>
</VirtualHost>
```
Now, adjust /etc/hosts by adding the following:
```
127.0.0.1 myphp.site
```
and restart Apache
```
$ sudo apachectl restart
```
## View the new site
Open [http://myphp.site/manual/en/](http://myphp.site/manual/en/) in your browser.

36
tutorial/user-notes.md Normal file
View File

@ -0,0 +1,36 @@
# User Note Editing Guidelines
These are some guidelines to follow when editing user notes in the manual.
To begin editing user notes in the manual, you must have SVN commit access to the manual, and you must either:
- Subscribe to the php-notes mailing list or newsgroup as described at Mailing Lists, Newsgroups and SVN Modules.
As a user submits a new user note, it will appear as a message on the mailing list with links in the footer of
the email that enable you to delete, edit, or reject that particular note.
- Log on to the server at http://master.php.net/manage/user-notes.php using your SVN user ID and password.
The user notes administration interface enables you to search for user notes that match particular strings
and edit or change the status of particular notes directly through the Web interface.
The thing that seems to confuse the most people is the difference between *rejecting* and *deleting* a note.
Basically, they both remove the note from the manual, but *rejecting* sends the user an email about the rejection
with links to support links and other information. Here are some guidelines of when to use each. You can also view
the exact text of the rejection email [here](http://git.php.net/?p=web/master.git;a=blob;f=manage/user-notes.php;hb=HEAD).
- If the note is asking for help (support request, *Does this work...?*, etc.) or if the person is reporting a bug,
*reject* the note. The email will show them the proper place to report such issues.
- If the note contains useful information appropriate for the manual proper, you may incorporate the information
into the manual and then *delete* the note.
- If the note is in the wrong place, incorrect, a giant block of silly, unnecessary code, poorly written, an answer
to another person's question, or just overall confusing, *delete* it. If it was an answer to a question, hunt down
that note and *reject* it.
- If the note is in a language other than English, *delete* the note.
- If the note submitter's email address is obviously bogus, don't *reject* the note, just *delete* it.
Rejecting the note just gives the mail server more work trying to send an email to a non-existent address,
which doesn't help anything.
If for some reason you need to add to a note, first ask yourself if it's worth it. Make sure you're not answering
a user's question; if you are, then the note doesn't belong there (see above). If you're clarifying a point, see
if it is appropriate to add the clarification to the manual proper; if it is, add it and *delete* the note (see above). If you still feel that adding your addition to the note will be the best option, then go ahead and add it. Usually, editors add their note in a "Editor's Note" block at the top. Unless you are correcting a minor error, make it obvious that you edited the note.
If you have some free time and commit access to phpdoc, try going through some of the manual pages and adding some of
the better notes into the documentation proper. Be sure to *delete* these notes after they're implemented.
If you are in doubt about what to do with a note, you may ask for help on the `php-notes` mailing list (or `php-doc`,
if what you're doing involves the documentation proper).

37
tutorial/whitespace.md Normal file
View File

@ -0,0 +1,37 @@
# Why we care about whitespace
I just wanted to post a little reminder about why we care so much about whitespace.
Over the years this topic has come up in many forms, usually via a whitespace unfriendly
commit that is immediately followed by a fellow team members complaint. And soon after,
a fix is made. There are reasons we as a group (especially all past and present editors)
have been strict and anal about this topic and here's why:
## Consistent look to the documentation
All the documentation ends up looking the same within all editors. The indention here is one
space, no tabs, and only PHP code itself is four spaces as per our [coding standards](http://pear.php.net/manual/en/standards.php).
This is a beautiful and consistent feature of the PHP manual sources.
## Pretty diffs
Peer review is critical to the success of any Open Source project, including the PHP Manual.
Fellow members of the team follow and read the commits so a diff should focus on changed content
and not mix in whitespace manipulations. If something doesn't fit or look right, our eyes focus on it...
this wastes time. Translators also rely on pretty diffs.
## Diff === Artistic Masterpiece
Each diff can be seen as a piece of art. Look it over... is this something you might send your lover?
Professor? Potential employer? Remember that every commit we make goes on record forever and represents
the author. Making them pretty and useful means we will be pretty and useful, both individually and as a group.
## A Diff should be perfect
Sometimes we want to quickly commit something and if needed update it again later. This is no good and
instead we should wait until later before making the commit. There is no need to spam the mailing list
with *"I didn't have time and was going to fix it later"* commits… there is no rush, the manual has existed
for 10 years without the information and can wait another hour/day... simply save the file and attend to it later.
The perfect diff meets all of the above descriptions.
# How to create pretty whitespace
Unified diffs make this easy. Before any commit is made, the author should look over a diff of the
edited file(s). This allows said author to find errors (like typos) as well as accidental whitespace
changes. After making another change, check it again. Once the diff is as intended then commit it
(after make test of course!) and move on.
I hope this helps explain why we are so strict about whitespace.