php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #51667 improve consistency of rendering methodsynopsis and fieldsynopsis
Submitted: 2010-04-26 18:04 UTC Modified: 2012-04-06 17:27 UTC
Votes:1
Avg. Score:3.0 ± 0.0
Reproduced:0 of 1 (0.0%)
From: danielc@php.net Assigned: bjori (profile)
Status: Closed Package: Doc Build problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2010-04-26 18:04 UTC] danielc@php.net
Description:
------------
Here are suggestions on improving how fieldsynopsis elements are rendered inside description sections, per discussion on php-doc ("improving object oriented / procedural combinations", http://news.php.net/php.doc/969381741).  The CSS changes are attached.  The DocBook sources and proposed HTML output are entered below.

STATIC
------
DocBook:
  <classsynopsis>
   <ooclass><classname>foo</classname></ooclass>
   <fieldsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
    <type>int</type>
    <varname>bar</varname>
   </fieldsynopsis>
  </classsynopsis>

HTML:
<div class="refsect1 description">
 <h3 class="title">Description</h3>
 <p class="para">Object oriented style</p>
 <div class="fieldsynopsis">
  <span class="modifier">public</span>
  <span class="modifier">static</span>
  <span class="type">int</span>
  <span class="classname">foo</span>::$<var class="varname">bar</var>
 </div>
</div>

------------
OBJECT
------
DocBook:
  <classsynopsis>
   <ooclass><classname>foo</classname></ooclass>
   <fieldsynopsis>
    <modifier>public</modifier>
    <type>int</type>
    <varname>bar</varname>
   </fieldsynopsis>
  </classsynopsis>

HTML:
<div class="refsect1 description">
 <h3 class="title">Description</h3>
 <p class="para">Object oriented style</p>
 <div class="fieldsynopsis">
  <span class="modifier">public</span>
  <span class="type">int</span>
  $<span class="classname">foo</span>-&gt;<var class="varname">bar</var>
 </div>
</div>



Patches

fieldsynopsis-site.css (last revision 2010-04-26 16:06 UTC by danielc@php.net)

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2010-04-26 18:06 UTC] danielc@php.net
The following patch has been added/updated:

Patch Name: fieldsynopsis-site.css
Revision:   1272297977
URL:        http://bugs.php.net/patch-display.php?bug=51667&patch=fieldsynopsis-site.css&revision=1272297977
 [2010-04-27 23:00 UTC] bjori@php.net
-Assigned To: +Assigned To: bjori
 [2010-05-12 03:20 UTC] danielc@php.net
Some OOP methodsynopsis in our existing DocBook sources are marked up inside classsynopsis, even though the standard is to just have them on their own.  So, while you're doing the fieldsynopsis changes, it seems like a good idea to also adjust the rendering engine produce the same HTML either way.

DOCBOOK WITH CLASSYNOPSIS
-------------------------
  <classsynopsis>
   <ooclass><classname>XMLWriter</classname></ooclass>
   <methodsynopsis>
    <type>bool</type><methodname>openURI</methodname>
    <methodparam><type>string</type><parameter>uri</parameter></methodparam>
   </methodsynopsis>
  </classsynopsis>

STANDARD DOCBOOK
----------------
  <methodsynopsis>
   <type>bool</type><methodname>XMLWriter::openURI</methodname>
   <methodparam><type>string</type><parameter>uri</parameter></methodparam>
  </methodsynopsis>

SHOULD BOTH PRODUCE THE FOLLOWING HTML
--------------------------------------
  <div class="methodsynopsis dc-description">
   <span class="methodname"><b>XMLWriter::openURI</b></span>()
  </div>
 [2010-05-14 17:58 UTC] danielc@php.net
-Summary: improve fieldsynopsis (property) rendering in descriptions +Summary: improve consistency of rendering methodsynopsis and fieldsynopsis
 [2010-05-14 17:58 UTC] danielc@php.net
Sorry to use this bug report as a way of working through this issue...  It seems like a good idea to have properties marked up the same way we mark up methods -- put the class name in the method/field element.  This is better because it is consistent and shorter.

So the changes should also allow the following markup to produce the same HTML output as discussed above.

DOCBOOK FOR OBJECT
------------------
   <fieldsynopsis>
    <modifier>public</modifier>
    <type>int</type>
    <varname>$foo->bar</varname>
   </fieldsynopsis>

DOCBOOK FOR STATIC
------------------
   <fieldsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
    <type>int</type>
    <varname>foo::$bar</varname>
   </fieldsynopsis>
 [2010-07-03 02:34 UTC] bjori@php.net
Automatic comment from SVN on behalf of bjori
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=300959
Log: Fixed bug#51667 (improve consistency of rendering methodsynopsis and fieldsynopsis)
# Well, part#2 of it, part#1 and part#3 still left
 [2010-07-03 02:35 UTC] bjori@php.net
These are way to many issues in one report.
Specific example page, or the current output would also simplify this.

The <ooclass><classname> stuff is fixed, haven't looked at the fieldsynopsis 
things yet.
 [2012-04-06 17:27 UTC] bjori@php.net
I'm fairly certain all issues here are fixed in the current versions.
 [2012-04-06 17:27 UTC] bjori@php.net
-Status: Assigned +Status: Closed
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Fri Mar 29 10:01:28 2024 UTC