| Gabor Hojtsy 2004-07-28, 3:57 pm |
| 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
|