From: jmmolina at free dot fr Operating system: PHP version: Irrelevant PHP Bug Type: Feature/Change Request Bug description: Use styles to improve the doc semantics
Description: ------------ Terminology : - Styles : CSS, HTML styles, DocBook tags, XSLT... I read the « Classes and Objects (PHP 5) » chapter and thought you could greatly improve the documentation, specially this chapter, by using styles to highlight keywords. It would improve the documentation semantics. For example the hyperlink style denotes a chapter, a link to an other section of the documentation. Let's take some example. First the sentence « Classes which implement an interface should do so using the implements keyword » of the « Object Abstraction » sub-chapter. It uses the verb implement and the PHP keyword implements. It's kind of confusion. Using a different style for the implements keyword would make it far much easier to understand the sentence. For example you could use a monospaced font family as a style for the keywords. Here I use the « and » characters to quote and could decide to use the double quotes character, ", to denote a PHP keyword : « Classes which implement an interface should do so using the "implements" keyword » Let's take a last one example. I reported bug 30511 because a documentation page contains a few spelling mistakes, I should say semantics mistakes : « A class can inherit methods and members of another class by using the extend keyword in the declaration. » In this chapter the author mixes the extend verb with the "extends" keyword. In this sentence it used the extend verb when it should have used the "extends" keyword. By using styles we could avoid these spelling and semantics mistakes. The correct sentence would be, using my quote and double quote semantics : « A class can inherit methods and members of another class by using the "extends" keyword in the declaration. » Using styles is part of the technical writing process. Styles for UI components (menus, buttons...), styles for programming languages keywords (class, function...) and of course implicit styles like hyperlinks (underline, blue color), headings... Note that the documentation (written using DocBook ?) already use some PHP semantics styles, the « phpcode » for example, it denotes a « PHP code ». -- Edit bug report at http://bugs.php.net/?id=30512&edit=1 -- Try a CVS snapshot (php4): http://bugs.php.net/fix.php?id=30512&r=trysnapshot4 Try a CVS snapshot (php5.0): http://bugs.php.net/fix.php?id=30512&r=trysnapshot50 Try a CVS snapshot (php5.1): http://bugs.php.net/fix.php?id=30512&r=trysnapshot51 Fixed in CVS: http://bugs.php.net/fix.php?id=30512&r=fixedcvs Fixed in release: http://bugs.php.net/fix.php?id=30512&r=alreadyfixed Need backtrace: http://bugs.php.net/fix.php?id=30512&r=needtrace Need Reproduce Script: http://bugs.php.net/fix.php?id=30512&r=needscript Try newer version: http://bugs.php.net/fix.php?id=30512&r=oldversion Not developer issue: http://bugs.php.net/fix.php?id=30512&r=support Expected behavior: http://bugs.php.net/fix.php?id=30512&r=notwrong Not enough info: http://bugs.php.net/fix.php?id=30512&r=notenoughinfo Submitted twice: http://bugs.php.net/fix.php?id=30512&r=submittedtwice register_globals: http://bugs.php.net/fix.php?id=30512&r=globals PHP 3 support discontinued: http://bugs.php.net/fix.php?id=30512&r=php3 Daylight Savings: http://bugs.php.net/fix.php?id=30512&r=dst IIS Stability: http://bugs.php.net/fix.php?id=30512&r=isapi Install GNU Sed: http://bugs.php.net/fix.php?id=30512&r=gnused Floating point limitations: http://bugs.php.net/fix.php?id=30512&r=float MySQL Configuration Error: http://bugs.php.net/fix.php?id=30512&r=mysqlcfg
