Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969379451 php.internals:40832
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.128.185 as permitted sender)
DomainKey-Status: bad
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:date:from:to:subject:cc:in-reply-to:mime-version
         :content-type:content-transfer-encoding:content-disposition
         :references;
        b=PO7UlLNWC5ybJNWsO0wyHN27Q22iNToYU3vBQlsTON4k3eU+I+G5BbJF310ByYhOWb
         UQLmQaF+rtKmch90FT4yPGCaHaEOtbFo9tXjd54/9ThsQhc7xYjIpsCw7I1YDrXYahJs
         I1SQoARbC2/2R0/Qq2M+zQNrjX8egxXjHDEZw=
Message-ID: <2dedb8a0810011857v63ade4e2wb43994e43aa2147b@mail.gmail.com>
Date: Thu, 2 Oct 2008 03:57:23 +0200
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: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
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-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
From: kalle.php@gmail.com ("Kalle Sommer Nielsen")

Hi Hannes

2008/10/1 Hannes Magnusson <hannes.magnusson@gmail.com>:
> 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

Actually this isn't always as easy on Windows, mainly because the
go-pear seems to not like Windows at all, I still havn't been able to
install pear with go-pear.

To install PhD I had to manually edit the phd.bat for it to work.

> 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
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>



-- 
Kalle Sommer Nielsen