[DOC-WEB] [web-doc] master: minor updates to tutorial

1 view

Skip to first unread message

Peter Cowburn

unread,

Jul 29, 2021, 9:07:17 AM7/29/21

to doc...@lists.php.net

Author: Peter Cowburn (salathe)
Date: 2021-07-29T14:07:01+01:00

Commit: https://github.com/php/web-doc/commit/74ecb5ba7fc6e0a9eda9bffa0246dfb0de607560
Raw diff: https://github.com/php/web-doc/commit/74ecb5ba7fc6e0a9eda9bffa0246dfb0de607560.diff

minor updates to tutorial

Changed paths:
M tutorial/editing.md
M tutorial/faq.md
M tutorial/intro.md
M tutorial/joining.md
M tutorial/local-setup.md
M tutorial/structure.md
M tutorial/translating.md
M tutorial/user-notes.md

Diff:

diff --git a/tutorial/editing.md b/tutorial/editing.md
index 8163809..745f28d 100644
--- a/tutorial/editing.md
+++ b/tutorial/editing.md
@@ -1,8 +1,8 @@
# Editing manual sources

## Introduction
-Before making any changes to the manual - either English version ore
-translation, make sure you read [style guidelines](style.php)!
+Before making any changes to the manual - either the English version or a
+translation, make sure you have read the [style guidelines](style.php)!

## Editing existing documentation
Simply open the files and edit them.
@@ -18,8 +18,8 @@ repository and uses reflection to generate documentation (DocBook) files.
### Option B: Copy skeleton files
This involves copying the skeleton files into the correct location:
```
-cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml #for new methods
-cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml #for new functions
+cp doc-base/RFC/skeletons/method.xml classname/methodname.xml #for new methods
+cp doc-base/RFC/skeletons/function.xml functions/functionname.xml #for new functions
```

Note: *classname*, *methodname* and *functionname* are lowercased names of the
@@ -46,6 +46,7 @@ You can commit your changes now.

## Commit changes
If you have the appropriate [commit karma][karma], you can commit your modified files.
+Otherwise, create a Pull Request to have your changes reviewed by the team.

## Viewing changes online
Documentation is built every night, at around 23:00 CST, then synced out to the
diff --git a/tutorial/faq.md b/tutorial/faq.md
index ae7b2ab..41acd8b 100644
--- a/tutorial/faq.md
+++ b/tutorial/faq.md
@@ -23,7 +23,8 @@ Note: This disables some error checking and beautification but raw errors will b
Note: Usually the problem is a major XML syntax issue.

## Is there an online editor?
-Yes, just go to [edit.php.net][editor]. Our wiki contains an [overview of the editor and how to use it][editor-tutorial].
+There used to be at [edit.php.net][editor]. Our wiki contains an [overview of the editor and how to use it][editor-tutorial].
+Nowadays, changes should be done via GitHub.

## 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.
@@ -90,10 +91,5 @@ mirror, make sure that you removed `broken-language.txt` from the root of your t
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
-```
-
[editor]: https://edit.php.net
[editor-tutorial]: https://wiki.php.net/doc/editor
diff --git a/tutorial/intro.md b/tutorial/intro.md
index 4c676ce..dc43f19 100644
--- a/tutorial/intro.md
+++ b/tutorial/intro.md
@@ -9,7 +9,7 @@ This guide uses some terminology that you have to know. Don't worry, it's easy:
- **translator** - person who translates the English manual into another language
- **{LANG}** - replace it with your two-letter country code, (e.g. when referring
to a mailinglist, `doc-{LANG}@lists.php.net`). Note: Brazilian Portuguese differs
- from the rest and it's called *pt_BR* for the SVN module and *pt-br* for the
+ from the rest and it's called *pt_br* for the Git repo and *pt-br* for the
mailing list suffix.

## Table of Contents
@@ -24,7 +24,7 @@ This guide uses some terminology that you have to know. Don't worry, it's easy:
- [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)
+- [Setting up a documentation environment](local-setup.php)

## Feedback
Feedback is most certainly welcome on this document. Without your submissions and input, this document wouldn't exist.
diff --git a/tutorial/joining.md b/tutorial/joining.md
index 1555eed..778c87f 100644
--- a/tutorial/joining.md
+++ b/tutorial/joining.md
@@ -5,8 +5,7 @@ It can be summarized as:
## Write to a mailing list
Because official communication is done there, you should write to the proper list.
Say "Hi" and what you're interested in doing. You may feel more comfortable lurking
-for a while, or reading the archives, or hanging out in IRC (#php.doc on Efnet)
-for a while, but ultimately let the list know who you are.
+for a while, or reading the archives, but ultimately let the list know who you are.

### For authors
You should send your message to the `php...@lists.php.net` mailing list.
@@ -14,19 +13,24 @@ You should send your message to the `php...@lists.php.net` mailing list.
### For translators
You should send your message to the appropriate `doc-{LANG}@lists.php.net` mailing list.

+## Informal discussion
+
+The mailing lists above are the primary communication forum. However for more
+realtime and/or informal chat, some doc authors hang out in "Room 11" on
+Stackoverflow Chat: https://chat.stackoverflow.com/rooms/11/php
+
## Create a doc patch or three
This step is required to show us that you are a real human, you want to do
some work and in general know how to do this.

-The simplest way to get started is by using the [Online Documentation Editor][editor].
-which allows you to login via your Facebook/Twitter/Google account and edit the documentation.
-Your patches will be then reviewed and accepted by someone with SVN access.
+The simplest way to get started is by using GitHub, to create and send Pull Requests
+to [php/doc-en][doc-en] or php/doc-{LANG} for translations.

-Our wiki contains an [overview of the editor and how to use it][editor-tutorial].
+Your Pull Requests will be then reviewed and accepted by someone with Git commit access.

-## Obtaining SVN access
+## Obtaining Git commit access
If you plan to contribute to the manual regularly, and want to do this more efficiently,
-you probably would like to use SVN directly. This requires a PHP.net account.
+you probably would like to be able to push to Git directly. This requires a PHP.net account.

To request one, please fill in [this form][request-account].

@@ -36,5 +40,4 @@ Basically, tell us what you have done, to prove that you really need this accoun
The next chapter will explain how to get the manual sources and how are they [structured](structure.php).

[request-account]: http://php.net/git-php.php
-[editor]: https://edit.php.net
-[editor-tutorial]: https://wiki.php.net/doc/editor
+[doc-en]: https://github.com/php/doc-en
diff --git a/tutorial/local-setup.md b/tutorial/local-setup.md
index d0ccb5b..d8089dd 100644
--- a/tutorial/local-setup.md
+++ b/tutorial/local-setup.md
@@ -1,4 +1,4 @@
-# Setting up Documentation environment
+# Setting up a 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.
diff --git a/tutorial/structure.md b/tutorial/structure.md
index ef38dfa..b3e567b 100644
--- a/tutorial/structure.md
+++ b/tutorial/structure.md
@@ -1,42 +1,9 @@
# Manual sources structure

-## Downloading the PHP Documentation Source
-The PHP Manual sources are currently stored in our Git repository.
-You don't need Git access to checkout (download) the files, but you do need it
-if you want to send your changes to our server.
+## Downloading the PHP Manual sources
+The PHP Manual sources are currently stored in our Git repositories.

-This tutorial assumes that you have basic terminal and Subversion knowledge, although
-don't worry if you've never used Subversion as only basic commands are used, and our
-setup is simple (e.g., no branches).
-
-To checkout the documentation source, use a modified version of the following command
-where you change `{LANG}` to a desired language, such as `en` for only English:
-
-```
-git clone https://github.com/php/doc-{LANG}.git phpdoc-{LANG}
-```
-
-This command creates a directory named `phpdoc-{LANG}` because the source is
-the first 'git clone' argument, and the second argument defines the directory name
-that stores the checked out directories and files (this name can be anything you wish).
-This directory will contain a directory with the sources of your chosen language,
-named *{LANG}*, and also *doc-base* folder, which is home to some helpful tools.
-The "en" language will always be present, as explained below.
-
-The documentation source is stored under "en". To only edit the source files, and
-not a translation, use:
-
-```
-git clone https://github.com/php/doc-en.git phpdoc-en
-```
-
-For example, to translate the manual into French, use "doc-fr" instead of "doc-en":
-
-```
-git clone https://github.com/php/doc-fr.git phpdoc-fr
-```
-
-For additional information about language codes and available translations, see `http://doc.php.net/revcheck.php`.
+To checkout the PHP Manual sources, follow the steps in [Setting up a documentation environment](local-setup.php)

## Files structure
**Note for translators:** if any of the source files don't exist in your translation, the English content will be used
@@ -45,10 +12,10 @@ it will lead to a mess, confusion and may break some tools.

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 manual as all functions are grouped into extensions.
+part of the manual as all functions are grouped into extensions.

-The documentation for extensions is located in `/phpdoc/{LANG}/reference/extension_name/`. For example,
-the calendar extension documentation exists in `/phpdoc/{LANG}/reference/calendar/`. There you'll find several files:
+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:
- *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
@@ -56,6 +23,7 @@ are included from here.
- *configure.xml* - usually this information is in setup.xml, but if the file exists it is magically
included into setup.xml
- *examples.xml* - various examples
+- *versions.xml* - contains version information for the extension
- *foo.xml* - example, foo can be anything specific to a topic. Just be sure to include via book.xml.

A procedural extension (like calendar) also has:
@@ -64,11 +32,11 @@ A procedural extension (like calendar) also has:

And OO extensions (such as imagick) contain:
- *classname.xml* - container for the methods defined by the class, contains also basic info about it
-- *classname/* - folder with one XML per method that the class declares
+- *classname/* - folder with one XML file per method that the class declares

Note: *classname* is the lowercased name of the class, not a literal file or directory name.

-There are some other important files, not related with extensions.
+There are some other important files:
- *{LANG}/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.
diff --git a/tutorial/translating.md b/tutorial/translating.md
index 923e4fc..b8bad20 100644
--- a/tutorial/translating.md
+++ b/tutorial/translating.md
@@ -6,58 +6,49 @@ You will also have to follow other steps from the [editing manual sources](editi
Translating documentation into other languages might look like a complicated
process, but in fact, it's rather simple.

-Every file in SVN has a *revision number*. It is basically the current version of
-the specified file. We use revisions to check if a file is synchronized with its
+Every file in Git has a *commit hash*. It is basically the current version of
+the specified file. We use commit hashes to check if a file is synchronized with its
English counterpart: to find out if the translation is up-to-date. That's why every
file in your translation requires an EN-Revision comment with the following syntax:
```
-
+
```
-The most important part of this comment is the revision number of the English file
+The most important part of this comment is the commit hash of the English file
that this translated file is based on. Let's see examples:

## Translating new file
Say you want to translate the documentation of the `in_array()` function, which
-doesn't exist in your language yet. Open the file `phpdoc/en/reference/array/in-array.xml`
-and copy the revision number. The English file's header might look like this:
-```
-<?xml version="1.0" encoding="utf-8"?>
-
-```
+doesn't exist in your language yet. Get the commit hash by changing into the `en` directory and executing the command `git log -n1 --pretty=format:%H -- reference/array/functions/in-array.xml`

-So our revision number is `310394`. Let's see how your translated file header
-should look like if we assume that your SVN username is *johnsmith*:
+For this example, let's say our commit hash is `68a9c82e06906a5c00e0199307d87dd3739f719b`. Let's see how your translated file header
+should look like if we assume that your PHP.net username is *johnsmith*:
```
<?xml version="1.0" encoding="utf-8"?>
-
-
+
```

-`$Revision$` is an SVN keyword, which will be replaced with the number of current
-revision when you commit your changes. The revision number that you have copied
-from the English file was created this way.
-
The rule is simple: if your revision number is equal to the revision number of
the English file you've translated, then your translation is up-to-date.
Otherwise, it needs to be synced.

## Updating translation of existing file
Let's assume that you want to update the translation of `password_needs_rehash()`.
-There are two simple ways to see which files require updating and what has to be
-changed to sync with English version: using [Online Editor](https://edit.php.net)
-or [doc.php.net tools](http://doc.php.net). The second way is described below.
+One way to see which files require updating, and what has to be
+changed to sync with the English version, is to use the [doc.php.net tools](http://doc.php.net).

Choose your language from the right sidebar and then use the "Outdated files" tool.
Filter files by directory or username (username used here comes from the `Mantainer`
variable in the header comment described above). Let's assume that the tool marked
`password-needs-rehash.xml` as outdated. Click on the filename and you will see
*diff* - list of changes between two versions of file: your version (current
-number in EN-Revision in your translation) and newest version in the English source
-tree. The example below should what the diff might look like:
+commit hash in EN-Revision in your translation) and newest version in the English source
+tree. The example below shows what the diff might look like:

```
---- phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2013/06/21 12:24:55 330609
-+++ phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2014/03/24 20:23:27 333093
+diff --git a/reference/password/functions/password-needs-rehash.xml b/reference/password/functions/password-needs-rehash.xml
+index 984eb2dc5c..860758a4a4 100644
+--- a/reference/password/functions/password-needs-rehash.xml
++++ b/reference/password/functions/password-needs-rehash.xml
@@ -12,8 +12,8 @@
<methodsynopsis>
<type>boolean</type><methodname>password_needs_rehash</methodname>
@@ -71,30 +62,25 @@ tree. The example below should what the diff might look like:
This function checks to see if the supplied hash implements the algorithm
```

-The first two lines indicate the compared revisions. The first was taken from the
-EN-Revision number and the second is the current version of this file in English.
-
As you can see, there is a difference between two lines. The `types` for the
parameters `options` and `algo` in the synopsis had been changed from `string`,
to `integer` and `array` respectively. You have to perform these changes in your
translation to make it up-to-date. Open `phpdoc/{LANG}/reference/password/functions/password-needs-rehash.xml`
and change those lines to match the English version.

-Then update the EN-Revision number in the header comment. You can also add your
+Then update the EN-Revision commit hash in the header comment. You can also add your
credits using the CREDITS tag. Your file header might look like this initially:
```
<?xml version="1.0" encoding="utf-8"?>
-
-
+
```
-and after changes it should looke like this:
+and after changes it should look like this:
```
<?xml version="1.0" encoding="utf-8"?>
-
-
+

```
-The new EN-Revision number came from the diff shown above. If you want to add
+The new EN-Revision commit hash came from the doc tools page. If you want to add
yourself to a CREDITS tag that already exists, separate
usernames with a comma, i.e.: ``.

diff --git a/tutorial/user-notes.md b/tutorial/user-notes.md
index 1c71bb8..bd2cb8d 100644
--- a/tutorial/user-notes.md
+++ b/tutorial/user-notes.md
@@ -1,11 +1,11 @@
# 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:
+To begin editing user notes in the manual, you must have a PHP.net account, and you must either:
- Subscribe to the `php-notes` mailing list or newsgroup. 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 https://main.php.net/manage/user-notes.php using your SVN user ID and password.
+- Log on to the server at https://main.php.net/manage/user-notes.php using your PHP.net account username 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.

@@ -34,5 +34,5 @@ add their note in a "Editor's Note" block at the top. Unless you are correcting
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 you are in doubt about what to do with a note, you may ask for help on the `php-notes` mailing list (or `phpdoc`,
if what you're doing involves the documentation proper).

--
Documentation Website Mailing List (http://doc.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

Reply all

Reply to author

Forward

0 new messages