Re: peardoc2
| From: | Thomas Schöfbeck | Date: | Thu, 16 Jan 2003 20:58:49 +0000 |
| Subject: | Re: peardoc2 | ||
| References: | 1 | Groups: | php.pear.doc |
| Request: | Send a blank email to pear-doc+get-284@lists.php.net to get a copy of this message | ||
Alexander Merz wrote:
As you see on the CVS commits, i worked on peardoc2 last week heavily. DB_DataOjects will be finished today. So peardoc2 will be ready for public release! Please take a look on peardoc2, if no one say -1, we can release it this week. (I will publish a HTML-version for reading at the end of the day) Hello Alexander,even I'm new to peardoc, +1 for publishing it. I had a short glance to the peardoc2-rep., and some small questions and suggestions came into mind: - all subchapters of 'PECL Packages' have roman numbers while all others have normal numbers - is this intended, or a bug in the styles? - I've already requested karma for pear and peardoc, so I don't mention the typos and small bugs here, but will commit them later. But: There is a planned system mentioned, which should create the docbook-code automatically out of the php-files (as far as I've understood ;) -> is there somewhere more info about it (Does/will it apply only for selected or all package-files, etc.)? - Just some suggestions, since pear and the doc will grow: - I'd use also .cvsignore for the result-files (e.g. configure as a
result of configure.in), so that "global" committers don't commit
accidentially these files and produce so much unnecessary
cvs-traffic.
- I'd also integrate the 'make-pearweb.sh' in the makefile.in
- You've mentioned in the docs the "phpdoc-tools"-dir for win-users
like in the phpdoc-group, but configure.in doesn't check for the
php.bat there. So I'suggest to eighter document that the arg
--with-php... has to be provided, or implement this check like in
the phpdoc-group (works fine there), and document the needed bat-file.
More general things:
- Who is the target audience for the package-descriptions?
Why I ask: e.g. parse() from HMTL_Template_IT has documented the
following syntax (btw, "__global" should be "__global__", and
"IntegratedTemplate" should be "HTML_Template_IT"):
void IntegratedTemplate::parse ([string $block = "__global" [, boolean
$flag_recursion = false]])
If the aimed audience is the user who cares just for the interface,
but not for the class-source: shouldn't this internal default VALUE
be omitted, and the default BEHAVIOR described in the text? (e.g.
"__global__" is only internally used, and nowhere else documented
here).
Hmm... On the other hand, if the source-comments get autogenerated
to the manual, this question might be bogus.
- Translations: My experience from phpdoc shows, that we invest MUCH
more time for the maintenance of the translated files than for the
transl. itself. So the question is if there would be a tool similar
to phpdoc's 'revcheck' useful.
So I think these are enough thoughts for the moment ;)
Cu,
Thomas