Re: [PHP-DOC] phpdoc-HOWTO-mini -- Was: (Re: [PHP-DOC] cvs: phpdoc /en/functions oracle.xml) From: Egon Schmid ( <email protected>) (( <email protected>))
Date: 08/23/00

Daniel Beckham wrote:
>
> I have to say.. not only is the howto.xml and README out of date.. they
> don't do a very good job of getting the new contributor started. I've been
> here for some time and I only just got myself properly setup with emacs,
> psgml and jade.
>
> And on top of that.. the howto.xml is an... XML file. If you need to read
> the howto in order to help you get started, you have to already know how to
> make the howto! Which comes first the chicken or the egg?

Thats no so bad. XML means it should be readable (without a DTD) by
machines and humans. Humans who wouldn't learn XML should not read it at
all.
 
> I've been considering writing a new howto to help get new users started.
> Something that pretty much step by step explains how to get psgml and the
> doc tools installed, explains some basic emacs commands. (Meta-q is the
> most helpful one I've ever seen. =) And then walks them through how to make
> changes to a file, how to add new sections, how to 'make test' or 'make
> html' to test their changes and then how to properly commit the document
> into the repository.
>
> This would be in addition to the current README and howto.xml documents.
> I'm thinking "phpdoc-HOWTO-mini" would be appropriate.
>
> What do people think of this? I'm willing to write the initial document if
> other people are willing to critique me and offer suggestions from their own
> experiences.

Go on and do this. It's a good idee. Stig, Torben, Hartmut, and Jouni
have much more expierence with this and will help if something is not so
correct.

-Egon 

-- 
SIX Offene Systeme GmbH · Stuttgart  -  Berlin  -  New York
Sielminger Straße 63   ·    D-70771 Leinfelden-Echterdingen
Fon +49 711 9909164 · Fax +49 711 9909199 http://www.six.de