More cleanups and organization

docs/README.md

@@ -7,15 +7,15 @@ is created by volunteers who collectively make changes every day, and
 actively translated into many languages. This guide is designed for
 people who work on the official PHP documentation.
 
-The PHP Documentation uses the [DocBook 5.2](https://tdg.docbook.org/tdg/5.2/)
-XML schema, with one change to allow the `<classsynopsis>` tag to support
-more than one `<ooclass>`, `<ooexception>`, or `<oointerface>` as the
-[DocBook 5.1](https://tdg.docbook.org/tdg/5.1/classsynopsis) schema does.
-
 The manual is built from the documentation using a tool called
 [PhD](http://doc.php.net/phd.php). The [local setup](local-setup.md)
 chapter explains how to set up a local development environment.
 
+The manual is written to the [DocBook 5.2](https://tdg.docbook.org/tdg/5.2/)
+XML schema, with one change to allow the `<classsynopsis>` tag to support
+more than one `<ooclass>`, `<ooexception>`, or `<oointerface>` as the
+[DocBook 5.1](https://tdg.docbook.org/tdg/5.1/classsynopsis) schema does.
+
 ## Glossary
 
 This guide uses some terminology that you have to know. Don't worry, it's easy:
@@ -28,26 +28,9 @@ This guide uses some terminology that you have to know. Don't worry, it's easy:
   Brazilian Portuguese differs from the rest and it's called *pt_br*
   for the Git repo and *pt-br* for the mailing list suffix.
 
-## Table of Contents
-- [Overview of the build system](overview.md)
-- [Setting up a local build environment](local-setup.md)
-- [Editing the PHP Manual](editing.md)
-- [Documentation structure](structure.md)
-- [Style guidelines](style.md)
-- [Coding standard for examples](cs-for-examples.md)
-- [Translating documentation](translating.md)
-- [Joining the team](joining.md)
-
-## Appendices
-- [FAQ](faq.md)
-- [Tools](tools.md)
-- [Frequently used tags and entities](tags-and-entities.md)
-- [User Note Editing Guidelines](user-notes.md)
-- [How the released versions are built](public-builds.md)
-
 ## Feedback
 
 You can report problems or make contributions to this guide by using the
-"Edit this page" or "Report a problem" links in the header of each page
+"Edit this page" or "Report a problem" links in the sidebar of each page
 at [the online version of this documentation](https://doc.php.net/tutorial/),
 or through [the GitHub repository](https://www.github.com/php/doc-base/).

docs/cs-for-examples.md

@@ -4,8 +4,7 @@ Examples need to be clear and simple, but should show the possibilities and
 usage of the functions used.  Only use OOP features where you would like to
 present them, use simple functions in other areas.
 
-References:  http://pear.php.net/manual/en/standards.php
-             http://www.php.net/manual/howto/
+Examples should generally conform to the [PEAR coding standards][pear-cs].
 
 ## Requirements
 
@@ -272,3 +271,5 @@ Array
   </example>
  </refsect1>
 ```
+
+[pear-cs]: http://pear.php.net/manual/en/standards.php

docs/editing.md

@@ -1,14 +1,13 @@
 # Editing manual sources
 
-## Introduction
 Before making any changes to the manual - either the English version or a
 translation, make sure you have read the [style guidelines](style.md)!
 
 ## Editing existing documentation
 Simply open the files and edit them.
 
 ## Adding new documentation
-When adding new functions or methods, there are a few options.
+When adding new functions or methods, there are a few options:
 
 ### Option A: Generating stub using `gen_stub.php`
 This is the new preferred way to generate files for new extensions, classes, functions
@@ -46,7 +45,7 @@ $ cd phpdoc
 $ php configure.php --with-lang={LANG}
 ```
 If your language is English you can omit the `with-lang` argument. When the above
-outputs something like "All good. Saving .manual.xml… done." then you know it validates.
+outputs something like `"All good. Saving .manual.xml… done."` then you know it validates.
 You can commit your changes now.
 
 ## Commit changes

docs/faq.md

@@ -2,7 +2,7 @@
 
 ## 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:
-```
+```sh
 php docgen.php -e simplexml -o outdir
 ```
 
@@ -11,7 +11,7 @@ It creates the skeletons that you edit, and then commit.
 Help is available with following command: `php docgen.php -h`.
 
 ## I created skeletons that contain a bunch of default text, should I commit it?
-No! Edit the files, to check the generated content and add more information,
+No! Edit the files, to check the generated content and add more information
 before committing. Thinking that it is okay to commit the skeleton files because
 you will soon come along and flesh them out might seem like a good idea. However,
 temporary often becomes permanent.
@@ -24,24 +24,24 @@ Use `<methodname>Class::method</methodname>`. Note that the case does not matter
 
 ## If a refentry should not emit versioning information, what should I do?
 Add the `role="noversion"` to its `<refentry>`. Example:
-```
+```xml
 <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:
-```
+```xml
 <!ENTITY url.google "http://www.google.com/">
 ```
 Then you can use this syntax in the documentation:
-```
+```xml
 Check out <link xlink:href="&url.google;">Google</link>
 ```
 Be sure the file understands the `xlink` namespace, by using `xmlns:xlink="http://www.w3.org/1999/xlink"` in the document element.
 
 ## When adding a note, should I add a title?
 Typically titles are useful for notes, but it's not required.
-```
+```xml
 <note>
  <title>Foo</title>
  <para>Note contents are here.</para>
@@ -56,8 +56,12 @@ like added parameters, are documented within the changelog section for each page
 ## 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.
-```
-<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>
+```xml
+<methodparam choice="opt">
+ <type>bool</type>
+ <parameter>httponly</parameter>
+ <initializer>false</initializer>
+</methodparam>
 ```
 
 ## I see example.outputs and example.outputs.similar entities, what's the difference?
@@ -70,7 +74,7 @@ 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):
-```
+```sh
 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

docs/local-setup.md

@@ -43,7 +43,7 @@ already exist.
 
 The web version of the documentation with `make php` and the output will
 be placed in `output/php-web`. (See the [additional local web setup
-instructions](local-web-setup) for details on how to view those.)
+instructions](local-web-setup.md) for details on how to view those.)
 
 <a name="without-docker"></a>
 ## Building without make or Docker

docs/overview.md

@@ -1,4 +1,4 @@
-# The PHP Documentation
+# Overview of the build system
 
 The PHP documentation is built from XML files and render into PHP files
 that are available on the [php.net/manual](https://php.net/manual/en) pages.

docs/public-builds.md

@@ -12,4 +12,7 @@ for help. (The process is automated and monitored, so problems are
 generally dealt with promptly.)
 
 ## CHM builds
-Right now, nobody knows when or how the CHM builds are made.
+
+The CHM versions of the manual are currently built by [Yoshinari
+Takaoka](https://github.com/mumumu) on an irregular schedule, and are
+automatically made available for distribution when they are rebuilt.

docs/structure.md

@@ -1,11 +1,10 @@
-# Manual sources structure
+# Documentation structure
 
-## Downloading the PHP Manual sources
-The PHP Manual sources are currently stored in our Git repositories.
+The PHP Manual sources are stored in Git repositories.
 
 To checkout the PHP Manual sources, follow the steps in [Setting up a documentation environment](local-setup.md)
 
-## Files structure
+## File structure
 **Note for translators:** if any of the source files don't exist in your translation, the English content will be used
 during the building process. This means that you *must not* place untranslated files in your translation tree. Otherwise,
 it will lead to a mess, confusion and may break some tools.
@@ -14,8 +13,8 @@ The structure of the manual sources is hopefully rather intuitive. The most
 complicated part is the documentation for extensions, which is also the biggest
 part of the manual as all functions are grouped into extensions.
 
-The documentation for extensions is located in `{LANG}/reference/extension_name/`.  For example,
-the calendar extension documentation exists in  `{LANG}/reference/calendar/`. There you'll find several files:
+The documentation for extensions is located in `reference/extension_name/`.  For example,
+the calendar extension documentation exists in  `reference/calendar/`. There you'll find several files:
 - *book.xml* - acts as the container for the extension and contains the preface. Other files (like examples.xml)
 are included from here.
 - *setup.xml* - includes setup, install and configuration documentation
@@ -37,9 +36,9 @@ And OO extensions (such as imagick) contain:
 Note: *classname* is the lowercased name of the class, not a literal file or directory name.
 
 There are some other important files:
-- *{LANG}/language-defs.ent* - contains local entities used by this language. Some common ones are
+- *language-defs.ent* - contains local entities used by this language. Some common ones are
   the main part titles, but you should also put entities used only by this language's files here.
-- *{LANG}/language-snippets.ent* - longer often used XML snippets translated to this language.
+- *language-snippets.ent* - longer often used XML snippets translated to this language.
   Including common warnings, notes, etc.
-- *{LANG}/translation.xml* - this file is used to store all central translation info, like a small
+- *translation.xml* - this file is used to store all central translation info, like a small
   intro text for translators and the persons list. This file is not present in the English tree.

docs/tags-and-entities.md

@@ -24,6 +24,6 @@
     &false;             <constant>FALSE</constant>
     &php.ini;           <filename>php.ini</filename>
 
-Be sure to check out [global.ent](entities/global.ent) and
-language-snippets.ent (located within each language's repo) for
-more information for entities and URLs.
+Be sure to check out `entities/global.ent` (in the `doc-base` repo) and
+`language-snippets.ent` (located within each language's repo) for more
+information for entities and URLs.

docs/toc.md

@@ -1,5 +1,7 @@
 ## Table of Contents
+- [Introduction](README.md)
 - [Overview of the build system](overview.md)
+- [Contributing to the documentation](contributing.md)
 - [Setting up a local build environment](local-setup.md)
 - [Editing the PHP Manual](editing.md)
 - [Documentation structure](structure.md)
@@ -13,4 +15,5 @@
 - [Tools](tools.md)
 - [Frequently used tags and entities](tags-and-entities.md)
 - [User Note Editing Guidelines](user-notes.md)
+- [Setting up a local web development environment](local-web-setup.md)
 - [How the released versions are built](public-builds.md)