- Use example.com for all example urls
I did it for one and not the other. Will do. Does everything need to be
anonymized? (I literally took my own repository and copied over the output)
Yeah, for something like this the output would instead be made up to
look similar to reality and then use the &example.outputs.similar;
entity.
- Put all URLs in global.ent before commit
Heh, even put that in a TODO. Antony feels that I shouldn't need a CVS
account if I'm just contributing documentation for this extension, so if
I'm submitting a tarball of the svn directory, where should I put the
entities? In a patch?
Yeah, in a patch. But is this really the only extension you will document?
Do you ever get an itch to fix/enhance something else, or even fix a typo
on occasion? Committing to CVS is great fun... do it! :-)
- functions.xml is autogenerated, do not create/commit it
- First use scripts/xml_proto.php to generate skeletons for all functions
Argh! I wish I knew about this script earlier! :-) Will do.
It's pretty useful. There are many (~800) undocumented* functions that
simply have skeletons and these are useful too. However, xml_proto.php
assumes that the xml will be edited by a human after because it inserts
stuff that needs editing. Maybe we should create a --with-no-stuff
option.
*
http://doc.php.net/php/undoc_functions.php
- Fix <title>Subversion &Functions;</title>
Not sure what you mean. Do you prefer Subversion Functions without the
entity?
Silly me, I didn't realize we use this here. I foresee a commit in
the near future that inserts this entity into every extension as
few (3) use it now. Anyway, ignore me here... it's fine ;)
- Remove comments like <!-- Example: Optional parameter -->
Okay. I'm keeping them there for now to help remind me of some docbook
structures, but I'll comb through and delete them once I finish.
Sounds good... I treated your patch as something ready to commit.
- In theory, new documentation is formal (no 'you')
The part about formal (not conversational) text is a bit idealistic as
few follow this but slowly we're talking about it, and trying.
Oh, no problem. My writing style uses "You" profusely, but other than
that, I have no problem writing formally.
Cool. I think we all naturally write you this, and you that, but Sean
once reminded us all that we should use formal speech (except in places
like the FAQ and Tutorial).
Regards,
Philip Olson