Re: manual translation issues, part 2

From: Date: Thu, 28 Dec 2000 20:30:44 +0000
Subject: Re: manual translation issues, part 2
References: 1 2  Groups: php.doc 
Request: Send a blank email to phpdoc+get-969333418@lists.php.net to get a copy of this message
On Thu, Dec 28, 2000 at 09:42:36PM +0200, Jouni Ahto wrote: > > On Wed, 27 Dec 2000, Egon Schmid (@work) 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/

« previous php.doc (#969333418) next »