Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969379447 php.internals:40828
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain brandonsavage.net from 72.14.220.153 cause and error)
Message-ID: <124c7d520810011227w19a0efd8q9a9fc3986750b256@mail.gmail.com>
Date: Wed, 1 Oct 2008 15:27:34 -0400
To: "Hannes Magnusson" <hannes.magnusson@gmail.com>
Cc: "Stanislav Malyshev" <stas@zend.com>, 
	"Elizabeth M Smith" <auroraeosrose@gmail.com>, phpdoc@lists.php.net, 
	internals@lists.php.net
In-Reply-To: <7f3ed2c30810011206o69bf2b25h2ec38df8ffe5e47f@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/alternative; 
	boundary="----=_Part_17956_752714.1222889254515"
References: <7f3ed2c30810010639q445b94b3m637ed929215d1cc6@mail.gmail.com>
	 <c0e7fa7f0810010707r724c089dv61bde6763b34898@mail.gmail.com>
	 <49.5C.04812.F70B3E84@pb1.pair.com> <48E3BB65.9040405@zend.com>
	 <7f3ed2c30810011206o69bf2b25h2ec38df8ffe5e47f@mail.gmail.com>
Subject: Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
From: brandon@brandonsavage.net ("Brandon Savage")

------=_Part_17956_752714.1222889254515
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

All,

I am what I guess you'd call a "newbie" - Elizabeth got me on this list
during ZendCon and though I've been following it I still have no idea how
the doc editing process works. I'm exactly who you want this kind of tool
for - a new contributor who is eager to contribute but unsure about how to
do so.

I've always been a fan of finding easy ways to do hard things. And I think
that this kind of system would be great for contributors, new and old alike.

My .02.

Brandon

On Wed, Oct 1, 2008 at 3:06 PM, Hannes Magnusson <hannes.magnusson@gmail.com
> wrote:

> On Wed, Oct 1, 2008 at 20:03, Stanislav Malyshev <stas@zend.com> wrote:
> >
> > On Wed, Oct 1, 2008 at 19:17, Elizabeth M Smith <auroraeosrose@gmail.com>
> wrote:
> >>
> >> tools).  Writing in XML is not a natural thing.  An online interface
> >> where people can edit docs would seriously boost people helping out.
> >> Why do you think there are so many user notes in the PHP manual ;)
> >
> > I think a web-based tool that would allow to generate standard docbook
> pages
> > (at least most primitive ones) and allow to edit certain sections while
> > supporting some basic stuff like paragraphs, links, styles (italic, bold)
> > etc. would be a HUGE help. I can write docbook and have experience with
> it
> > and I still find it annoying and hard to remember all the details, I can
> > only imagine how intimidating it appears to a newbie.
>
> You were extremely unlucky when you wrote the intl docs, sorry for that! :)
>
> Now we do however have skeletons for 99% cases, and even a 5minutes
> tutorial on howto document exceptions[1].
> NOTE: Most of the 5minutes are spent explaining how to build the docs.
>
>
> Sure, an online editing tool would be great but I don't think that is
> a realistic expectation for the time being. I'd rather want PHP5.3
> documented before its release then someone spending all their time on
> weird dirty mixed application that will probably not be ready until
> PHP6.
>
>
>
> >> Why do you think there are so many user notes in the PHP manual ;)
>
> Speaking of which, we do also need volunteers to review them.
> If you login to php.net (via bugsweb or
> http://master.php.net/manage/users.php) you'll see three boxes
> above(to the right) of all user notes:
> 1) Edit (rarely used, mostly just to add <?php ?> tags for syntax
> highlighting if people missed them
> 2) Reject the note (questions and stuff like that)
> 3) Delete (wtf notes, bad code/advise, huge code...)
>
> _EVERYONE_ with a php.net account can do that and it would be greatly
> appreciated if people would remove the horror notes when they
> encounter them. It would even be more appreciated if extension
> maintainers regularly review the notes attached to their extensions
> (currently Derick is prettymuch the online who does that).
>
> >> However...you will have to wade through the bad docs too.  And I have no
> >> solution for dealing with the "three million tools" issues.
>
> I don't understand this argument.
> All you need for building and view the documentations are 4things: CVS
> client, PHP, text editor and a browser. All of which you have
> installed already if you have any interest in PHP at all.
>
> To build and view the docs follow these 6steps for the first time,
> after you follow it once you only have to repeat 3 of the steps
>
> 1) cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
> 1b) cd phpdoc
> 2) php configure.php
> 3) pear channel-discover doc.php.net && pear install doc.php.net/phd-beta
> 4) phd -d .manual.xml -t chunkedhtml
> 5) firefox html/index.html
> 6) notepad en/reference/spl/spl/book.xml
>
> Now repeat step 2, 4, and 5 after each change you make with you text
> editor.
>
> If you can install PHP on your operating system then you can build the
> docs and contribute.
>
> -Hannes
>
> [1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
>

------=_Part_17956_752714.1222889254515--