[commit-cp] [bugs #11104] Comments should use XHTML-1.0-Strict and prefer meaningful markup

[Julian Scheid]

This mail is an automated notification from the bugs tracker
 of the project: classpath.




/**************************************************************************/
[bugs #11104] Full Item Snapshot:

URL: <http://savannah.gnu.org/bugs/?func=detailitem&item_id=11104>
Project: classpath
Submitted by: Julian Scheid
On: Mon 11/22/2004 at 15:53

Category:  classpath
Severity:  1 - None
Resolution:  None
Privacy:  Public
Assigned to:  None
Status:  Open
Platform Version:  None


Summary:  Comments should use XHTML-1.0-Strict and prefer meaningful markup

Original Submission:  All javadoc comments should comply with XHTML-1.0-Strict. 
 In addition, structural markup should be preferred over presentational markup. 
 For example, instead of &lt;b&gt; the tag &lt;em&gt; or &lt;strong&gt; should 
be used. If decorations (like colors, font sizes etc.) are required, they 
should be added using CSS.

Furthermore, a set of standard CSS classes should be established which should 
then be consistently used in all comments.  For instance, Java code examples 
could always be put inside a &lt;div class="java-code-example"&gt; tag.

Rationale: when all comments use meaningful XHTML-1.0-Strict markup only, the 
API documentation can be generated in XHTML-1.0-Strict format, and it can be 
converted properly to non-HTML formats like DocBook.

At a later point, gjdoc may help with the process of converting to XHTML by 
emitting warnings when a comment uses markup other than valid XHTML-1.0-Strict.

See also:
http://www.w3.org/TR/xhtml1/
http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd












For detailed info, follow this link:
<http://savannah.gnu.org/bugs/?func=detailitem&item_id=11104>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/