Edit report at http://bugs.php.net/bug.php?id=30512&edit=1
ID: 30512 Updated by: [email protected] Reported by: jmmolina at free dot fr Summary: Use styles to improve the doc semantics -Status: Open +Status: Bogus Type: Feature/Change Request -Package: Feature/Change Request +Package: *General Issues PHP Version: Irrelevant Block user comment: N Private report: N New Comment: Your report is not very stylish. And anyway, this is wrong place for such reports. Previous Comments: ------------------------------------------------------------------------ [2004-10-21 16:13:17] jmmolina at free dot fr 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 this bug report at http://bugs.php.net/bug.php?id=30512&edit=1
