On 22 April 2010 03:28, Daniel Convissor <dani...@analysisandsolutions.com> wrote: > Hi Folks: > > In trying to add the procedural style interface to the DateTime docs I > went searching for how we currently present stuff that has both object > oriented and procedural interfaces. It turns out there is no consistent > way of going about it, plus there are some other oddities that would be > good to discuss. > > 1) How to label the OOP methodsynopsis? > > Here are the current usages: > > Object oriented style: > Object oriented style > Object oriented style (method): > Object oriented style (method) > Object oriented style (constructor): > Object oriented style (property): > Object oriented style (property) > &style.oop; > > (Though the style.oop entity was mistakenly defined as "Oriented object > style", though I just fixed it to "Object oriented style". > > I suggest we go with &style.oop; (mapping to "Object oriented style") for > everything. The parenthetical method/constructor/property are > supurfluous because the way the stuff is rendered clearly explains the > usage. > > Similarly, "&style.procedural;" should be substituted for "Procedural > style". > > Does this seem reasonable to you?
Yes, using just the entities wherever possible seems the best approach to me. > > > 2) Where to put the example output? > > Generally, output for examples is put inside the <example> element. But > when both OOP and procedural styles are shown, it's easier to > write/maintain one output. > > Some docs put it in one of the examples, a la > http://us3.php.net/manual/en/rararchive.getcomment.php. It's a somewhat > inelegant. > > Some docs put it outside the <example> section. It works, but it looks a > little funny without it being offset inside a box. See > http://us3.php.net/manual/en/mysqli.affected-rows.php for what I mean. > > I did a test of putting the output block inside a separate <example> > element just above </refsect1>. It works nicely. Does this sound good > to everyone? I don't think having a new example block just for output makes much semantic sense. How about having multiple <programlisting> elements (one per paradigm) and one <screen> with the &examples.outputs* entities? > > > 3) The way properties are documented/rendered in description refsect1's > can be better. > > Take a look at mysqli affected-rows page (same as above link). "mysqli" > is in a box on one line and then "int $affected_rows;" is on another row. > Right now we mark up the DocBook like this: > > <classsynopsis> > <ooclass><classname>mysqli</classname></ooclass> > <fieldsynopsis> > <type>int</type><varname>affected_rows</varname> > </fieldsynopsis> > </classsynopsis> > > The <classsynopsis> / class name in this section of the output is > unnecessary because the class in question is clear from the page > title/etc, plus we don't use it for methods. > > It seems like things would be much clearer if the class name weren't > there and it came out something like this: > > public int $affected_rows > > DocBook allows the <fieldsynopsis> to go directly into the <refsect1>. > So to accomplish this, the DocBook can be written as such: > > <fieldsynopsis> > <modifier>public</modifier> > <type>int</type> > <varname>affected_rows</varname> > </fieldsynopsis> > > and then add "div.refsect1 div.fieldsynopsis" to line 979 of site.css to > get the border around it just like "div.refsect1 div.methodsynopsis". > Looks sweet. What do people think? > > > Once we come to agreements on which ways to go, I'll be glad implement > them throughout the existing files. > > Thanks, > > --Dan > > -- > T H E A N A L Y S I S A N D S O L U T I O N S C O M P A N Y > data intensive web and database programming > http://www.AnalysisAndSolutions.com/ > 4015 7th Ave #4, Brooklyn NY 11232 v: 718-854-0335 f: 718-854-0409 >
