Re: [PHP-DOC] manual translation issues, part 2 From: eschmid+sic <email protected>
Date: 12/28/00

On Thu, Dec 28, 2000 at 09:42:36PM +0200, Jouni Ahto wrote:
>
> On Wed, 27 Dec 2000, Egon Schmid ( <email protected>) wrote:
 
> > Yes and all opening verbs should start with a capital letter and the
> > description should not have a punctuation mark.
>
> I've been noting that we have several other inconsistencies besides
> true/false sometimes been tagged to 'literal' and sometimes not. For
> example:
>
> -- Referring to a functions arguments. They are sometimes tagged as
> 'parameter', sometimes as 'literal' and probably something else too.
> -- Options to configure have been tagged as 'option', 'literal' and often
> not at all.
> -- Constants have been tagged a few times as 'literal, mostly not at all.
> DocBook has the tag 'constant' and we should be using it. TRUE/FALSE might
> be better with this tag too.
> -- Many cases where 'refname' has been written using both capital and
> small letters, 'function' in 'funcdef' with only small letters. There is a
> consensus now how functions in PHP should be named, and at least for those
> modules that conform to it, the documentation should be fixed so that we
> use only small letters. Even when the function name begins a sentence.
> -- The examples use both the form 'function (args)' and 'function(args)'.
> -- 'See also' and 'See also:'.
> -- Several others that don't come to my mind now...

And what should be the wording for refpurpose:

Creates a new reference to a COM component
Create a new reference to a COM component

I think the first is more common.
 
> If there's any interest, I'll go through the docs and try to list every
> problem I do see. We could then open up a discussion and create the exact
> guidelines of how PHP should be documented.

I hope you will not rewrite the "The Chicago Manual of Style" for PHP.
Hartmut told me the last days, he has also a copy and reread it. IMHO all
titles are wrong. "COM support functions for Windows" should be written as
"COM Support Functions for Windows".

-Egon 

-- 
http://www.linuxtag.de/
http://php.net/books.php 
http://www.concert-band.de/