Skip to content

[WIP] Update setup script #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: master
Choose a base branch
from
Open
126 changes: 0 additions & 126 deletions README

This file was deleted.

142 changes: 142 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Read Me

## Read this first

This directory contains source files and a setup for converting
PHP's XML documentation into presentation formats like HTML and
RTF. You should not have to bother with this unless you are
writing documentation yourself, or if you simply are curious
about how the XML stuff works.

If you just want to read the documentation, look at: http://www.php.net/docs.php

## How to write PHPDoc files

If you are interested in information about how to
set up the tools needed, how to work with Git and
DocBook on Linux or Windows, or what conventions you
should follow when writing phpdoc files, please refer
to the PHP Documentation HOWTO.

You can read the HOWTO online at http://doc.php.net/tutorial/

If you are already working with the phpdoc module,
then you can find its XML source in the howto directory
of the module, and build it yourself with:

```bash
phd -d .manual.xml
```

However, PhD is a separate project which can be read about here: http://wiki.php.net/doc/phd

## Quick Reference

### Source checkout

a. Fork the repository of the language you want to contribute to on [GitHub](https://github.com/phpdoctest)
b. Check out the source

```bash
git checkout git://github.com:[your github-username]/[language you want to contribute to].git
git remote add upstream https://github.com/phpdoctest/[language you want to contribute to].git
```

c. Check out the doc-base repository with the different tools

```bash
git checkout https://github.com/phpdoctest/doc-base.git
```

That will leave you with a folder ```[language you want to contribute to]```
which contains the source-files for the documentation and a folder ```doc-base```
that contains the different tools and resources used in all languages.

### Edits

a. Bring everything up to date and create a new branch

```
cd [language you want to contribute to]
git fetch upstream
git checkout -b [branchname] upstream/master
```

b. Make the change. Use spaces not tabs. Be sure to carefully watch your whitespace!
c. Look at your unified diff, make sure it looks right and that whitespace changes aren't mixed in:

```bash
git diff path/to/file.xml
```

d. Make sure no errors are present, so at the command line in your phpdoc source directory run:

```bash
cd ..
php doc-base/configure.php
```

Always ```php configure.php``` before commit!

e. Commit your changes

```
git add path/to/file.xml
git commit
git push origin branchname
```

f. Open a PullRequest on GitHub for your changes to be merged directly into the main repository.


Read the HOWTO for more information. After reading the HOWTO, email the phpdoc
mailing list (phpdoc@lists.php.net) with questions and concerns.

### new functions

a) Copy an existing xml file or use a skeleton from the HOWTO.
Rename and place it into the appropriate directory.

b) Edit. Be sure no leftover text exists. No tabs either.

c) Now test locally before commit by first running
(php configure.php)

d) git add add path/to/yourfile.xml

e) git commit

Note that the version numbers are taken care of elsewhere (don't worry
about them)

### some popular tags and entities

<filename> filenames
<constant> constants
<varname> variables
<parameter> a function's parameter/argument
<function> functions, this links to function pages or bolds if
already on the function's page. it also adds ().

<literal> teletype/mono-space font <tt>
<emphasis> italics
<example> see HOWTO, includes many other tags.
<link> internal manual links
<link linkend="language.variables">variables</link>

<link> external links via global.ent
<link xlink:href="&spec.cookies;">mmm cookies</link>

<type> types, this links to the given types manual
page: <type>object</type> -> php.net/types.object


&return.success; see: language-snippets.ent
&true; <constant>TRUE</constant>
&false; <constant>FALSE</constant>
&php.ini; <filename>php.ini</filename>

Be sure to check out globals.ent and language-snippets.ent for
more information for entities and urls.

---------------------------------------------------------------------------
Empty file added TODO-GitTransfer
Empty file.
27 changes: 14 additions & 13 deletions configure.php
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
| Hannes Magnusson <bjori@php.net> |
| Gwynne Raskind <gwynne@php.net> |
+----------------------------------------------------------------------+

$Id$
*/

Expand All @@ -31,7 +31,7 @@
function usage() // {{{
{
global $acd;

echo <<<HELPCHUNK
configure.php configures this package to adapt to many kinds of systems, and PhD
builds too.
Expand All @@ -47,7 +47,7 @@ function usage() // {{{
--srcdir=DIR Find the sources in DIR [configure dir or `.']
--basedir Doc-base directory
[{$acd['BASEDIR']}]
--rootdir Root directory of SVN Doc checkouts
--rootdir Root directory of GIT Doc checkouts
[{$acd['ROOTDIR']}]

Package-specific:
Expand All @@ -66,7 +66,7 @@ function usage() // {{{
--with-php=PATH Path to php CLI executable [detect]
--with-lang=LANG Language to build [{$acd['LANG']}]
--with-partial=my-xml-id Root ID to build (e.g. <book xml:id="MY-ID">) [{$acd['PARTIAL']}]
--disable-broken-file-listing Do not ignore translated files in
--disable-broken-file-listing Do not ignore translated files in
broken-files.txt
--redirect-stderr-to-stdout Redirect STDERR to STDOUT. Use STDOUT as the
standard output for XML errors [{$acd['STDERR_TO_STDOUT']}]
Expand Down Expand Up @@ -97,7 +97,7 @@ function is_windows() {
function checking($for) // {{{
{
global $ac;

if ($ac['quiet'] != 'yes') {
echo "Checking {$for}... ";
flush();
Expand All @@ -107,7 +107,7 @@ function checking($for) // {{{
function checkerror($msg) // {{{
{
global $ac;

if ($ac['quiet'] != 'yes') {
echo "\n";
}
Expand All @@ -118,7 +118,7 @@ function checkerror($msg) // {{{
function checkvalue($v) // {{{
{
global $ac;

if ($ac['quiet'] != 'yes') {
echo "{$v}\n";
}
Expand Down Expand Up @@ -315,7 +315,7 @@ function print_xml_errors($details = true) {
} else {
continue;
}

$overridden_settings[] = strtoupper($o);
switch ($o) {
case 'h':
Expand Down Expand Up @@ -399,7 +399,7 @@ function print_xml_errors($details = true) {
case 'basedir':
$ac['basedir'] = $v;
break;

case 'output':
$ac['OUTPUT_FILENAME'] = $v;
break;
Expand All @@ -414,7 +414,7 @@ function print_xml_errors($details = true) {
case 'stderr-to-stdout':
$ac['STDERR_TO_STDOUT'] = $v;
break;

case '':
break;

Expand Down Expand Up @@ -485,6 +485,8 @@ function print_xml_errors($details = true) {
if (file_exists("{$LANGDIR}/trunk")) {
$LANGDIR .= '/trunk';
}

echo $LANGDIR;
if (!file_exists($LANGDIR) || !is_readable($LANGDIR)) {
checkerror("No language directory found.");
}
Expand Down Expand Up @@ -674,7 +676,7 @@ function print_xml_errors($details = true) {
echo "done.\n";
echo "Partial manual saved to {$filename}. To build it, run 'phd -d {$filename}'\n";
exit(0);
} // }}}
} // }}}

$mxml = $ac["OUTPUT_FILENAME"];
if ($dom->validate()) {
Expand Down Expand Up @@ -720,7 +722,7 @@ function print_xml_errors($details = true) {
echo "\nThe document didn't validate, ";

// Allow the .manual.xml file to be created, even if it is not valid.
if ($ac['FORCE_DOM_SAVE'] == 'yes') {
if ($ac['FORCE_DOM_SAVE'] == 'yes') {
printf("writing %s anyway, and ", basename($ac["OUTPUT_FILENAME"]));
if ($ac["SEGFAULT_SPEED"] == "yes") {
$t = $dom->doctype;
Expand Down Expand Up @@ -755,4 +757,3 @@ function print_xml_errors($details = true) {
errors_are_bad(1); // Tell the shell that this script finished with an error.
}
?>

Loading