PHP Documentation - [HEADSUP] New development branch created

Author

[HEADSUP] New development branch created

Hannes Magnusson

2007-09-28, 8:01 am

Hi all

We have a new development branch in town, REF_STRUCT_DEV.
The goal of this branch is to create a new reference navigation
structure and new OO doc skeleton.

I've committed initial changes to the manual.xml.in,
scripts/file-entities.php.in, XMLreader and the Reflection extension
using a new reference structure and OO doc model.

As a result of this change we have a lot of room for whole bunch of

stuff.
This essentially screams for more documentation writers to participate
in the project as we now have a lot of opportunities for writers.
To name a few:
- Possibility to add "basic usage of this extension" pages (PDO/SCA/SDO....)
- Possibility to add FAQ/tutorials for each extension
- Possibility to add articles for each extension
- Possibility to cut long and complex documents (header(), mail()...)
into simple manual pages linking to "further examples and howtos"
within the extension.

I'll be working more on this over the w

end and will change the
cronjob on http://docs.php.net to build (from this branch) every
6hours so you can see the results of all this.

This is a fairly major change (yet relatively simple one) so I would
like to ask all of you to throw in your two cents, after browsing
through docs.php.net (the XMLReader and (the new) Reflection docs
especially), about all this.

Don't be afraid to continue committing.
This branch does not affect your current checkouts so you can continue
to commit as you've always done. I can take care of all the merging -
as long as you don't commit major changes to the OO documentation :)

Note to translators: You should *NOT* sync your translations to the new branch.

-Hannes

Hannes Magnusson

2007-09-28, 7:02 pm

On 9/28/07, Hannes Magnusson <hannes.magnusson@gmail.com> wrote:
> Hi all
>
> We have a new development branch in town, REF_STRUCT_DEV.
> The goal of this branch is to create a new reference navigation
> structure and new OO doc skeleton.

Note: These changes are fully Docbook-XSL compatible.
Although PhD deals with these changes a bit better than Docbook-XSL we
don't need to wait for the PhD-render to be "finished" to deploy these
changes.

> cronjob on http://docs.php.net to build (from this branch) every
> 6hours so you can see the results of all this.

docs.php.net has been update; http://docs.php.net/manual/en/funcref.php
Things to pay attention to: XMLReader, Reflection and the navigation.

-Hannes

M. Sokolewicz

2007-09-28, 7:02 pm

Hannes Magnusson wrote:
> On 9/28/07, Hannes Magnusson <hannes.magnusson@gmail.com> wrote:
>
> Note: These changes are fully Docbook-XSL compatible.
> Although PhD deals with these changes a bit better than Docbook-XSL we
> don't need to wait for the PhD-render to be "finished" to deploy these
> changes.
>
>
>
> docs.php.net has been update; http://docs.php.net/manual/en/funcref.php
> Things to pay attention to: XMLReader, Reflection and the navigation.
>
> -Hannes

Personally I'm ok with the way it's structured, but I find the looks of
it horrible right now, though I'm sure we'll be able to tweak that
later. The whole idea of showing it this way looks and sounds great to
me. Good job on this one Hannes!

- Tul

Edward Z. Yang

2007-09-29, 4:01 am

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hannes Magnusson wrote:
> docs.php.net has been update; http://docs.php.net/manual/en/funcref.php
> Things to pay attention to: XMLReader, Reflection and the navigation.

Wow, this looks fantastic!

Quick notes from looking at:
http://docs.php.net/manual/en/class...ionfunction.php

- - The ReflectionFunction sub-pages don't expand on the side until you
navigate to a sub-page: not good
- - The method declarations are a bit wordy. Can we try to reduce them to
// defining class ... declarations?
- - I'm not sold on the idea of deep nesting the extension categories,
maybe this will change

If I have time this w

end, I'll fiddle around with the DOM extension
manual pages.

- --
Edward Z. Yang GnuPG: 0x869C48DA
HTML Purifier <http://htmlpurifier.org> Anti-XSS Filter
[[ 3FA8 E9A9 7385 B691 A6FC B3CB A933 BE7D 869C 48DA ]]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFG/bg7qTO+fYacSNoRAkC3AJsFF8X75wGwIM3/5O1lg1i5fB3eIQCcCXW9
A46bK91KpmqZfA25HmvSxsw=
=6Fry
-----END PGP SIGNATURE-----

Hannes Magnusson

2007-09-29, 7:01 pm

On 9/28/07, M. Sokolewicz <tularis@php.net> wrote:
> Hannes Magnusson wrote:
>
> Personally I'm ok with the way it's structured, but I find the looks of
> it horrible right now, though I'm sure we'll be able to tweak that

The looks of what? The reference structure, the class reference page,
the class definition or..?

-Hannes

M. Sokolewicz

2007-09-29, 7:01 pm

Hannes Magnusson wrote:
> On 9/28/07, M. Sokolewicz <tularis@php.net> wrote:
>
> The looks of what? The reference structure, the class reference page,
> the class definition or..?
>
> -Hannes

I meant the way the class definition was dumped right there at the top
of the page without any actual content describing it or even saying what
it actually is. Basically the way Edward showed it in his response would
make it look better IMO. I actually just noticed it has since been
updated and looks far better now!

I'm not a big fan of the huge number of "blue blocks" for each single
paragraph, just white looks far better imo. But that might be just me.

- Tul

Hannes Magnusson

2007-10-01, 7:05 pm

On 9/28/07, Hannes Magnusson <hannes.magnusson@gmail.com> wrote:
> cronjob on http://docs.php.net to build (from this branch) every

This is no longer true.
docs.php.net is now running the 'official' HEAD branch as it will be
used under the phd RC testing as an official mirror.

In the meantime, thanks to Sean, builds from this branch are available
at http://livedocs.phpdoc.info/manual/en/

-Hannes

Sponsored Links