Re: [PHP-DOC] manual translation issues, part 2 From: Jouni Ahto (jah <email protected>)
Date: 12/28/00

On Wed, 27 Dec 2000, Egon Schmid ( <email protected>) wrote:

> Cynic wrote:
> >
> > While hammering through the manual pages I noticed that
> > true/false terms are sometimes in the <literal> element,
> > and sometimes not. Are the occurences of 'plain' true/false
> > candidates for updates, or is there a reason behind this?
> > I they'd get changed sometime, should I go ahead, and
> > translate true to <literal>true</literal> and false
> > to <literal>false</literal> where needed?
>
> Go ahead.
>
> > Should the contents of <refpurpose> elements be translated
> > so that the verb opening the sentence is given in the
> > infinitive form? I would think so, but in Czech this looks
> > strange. Then again, I don't know all the current / future
> > uses of the element, and don't want to break anything.
>
> 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...

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.

-- Jouni