Hi!
Just want to confirm that the following are true as I don't believe these have been made official [yet]:
a) No ending period in the reftitle
b) No ending period in the see also
c) Only part of docs wider than 78 characters is methodsynopsis
d) New examples use ' not " wherever possible (this is
old since PEAR coding standards describe it but few
do it, not sure why)
e) All new (and eventually old) docs will use the new upcoming 'refsect style'
Regarding (a), it's a little strange when a reftitle has
multiple sentences, or commas, as it means only partial
punctuation is used when we leave off the ending period. Should we live with that? Most are not this way so it should be fine. Also, many times these titles aren't even complete sentences.
Are there reftitles with multiple sentences? Huh... Reftitle supposed to be short, isn't it?
With (b) it would be nice if we didn't manually type in commas either but it seems we abandoned that idea. Goba?
Adding them feels a little dirty but also simple and doable.
Since we are not using a list markup for see also lists, we should add commas ourselfs. If we would use some list markup, then we could autogenerate commas (and the ending ", and" part between the last two list items).
As far as (e) goes I'll write a separate email regarding a CHANGELOG refsect1 proposal (this has been discussed many times!) but other than that what do you guys think?
Regarding (c), most of our docs is wrapped at 78, but maybe there are more places (additionaly to methodsynopsis), where it is fine to keep the non-wrapped lines.
Goba
