php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Request #30512 Use styles to improve the doc semantics
Submitted: 2004-10-21 16:13 UTC Modified: 2010-12-31 20:42 UTC
From: jmmolina at free dot fr Assigned:
Status: Not a bug Package: *General Issues
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: jmmolina at free dot fr
New email:
PHP Version: OS:

 

 [2004-10-21 16:13 UTC] 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 ?.


Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2010-12-31 20:42 UTC] jani@php.net
-Status: Open +Status: Bogus -Package: Feature/Change Request +Package: *General Issues
 [2010-12-31 20:42 UTC] jani@php.net
Your report is not very stylish. And anyway, this is wrong place for such reports.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sun Dec 01 19:01:30 2024 UTC