On Wed, Dec 17, 2008 at 07:42, Gang Chen <eniac2...@gmail.com> wrote:
> 2008/12/17 Philip Olson <phi...@roshambo.org>:
>>> I think that the phpdoc system should have following two new features:
>>
>> These are good ideas and similar ones were briefly discussed recently here:
>>
>> http://markmail.org/message/topmhhzmesrw2xwa
>>
>>> (1) Translation healthy tag
>>>
>>> There are always have some out-of-date translated documents in most of
>>> the time, but the users do not know this -- sometimes that's nothing,
>>> but sometimes it will mislead those totally depending on the
>>> translated manual。So a healthy tag to indicate whether the translated
>>> document is up-to-date or not is important.
>>
>> This is a difficult topic. See the quoted thread above for ideas on
>> how to solve this problem.
>>
>
> I have read the thread you mentioned just now, great minds think alike :-)
>
> Appling a revision tag for each xml:id chunk is not a good idea, for
> it'll be an arduous task for the translator to synchronice the
> revision tag. Suggests that all xml:id chunks in a single XML file
> share the same revision tag, so we needn't to change current XML files
> and it will not be a difficult topic anymore. The solution is:
There is no way we can detect which chunks from an .xml file are
outdated. Either the entire file is outdated or not.
Moving the EN-Revision tag to the root node of the .xml file would be
done by a script which would bump EN-Revision if nescicery so its
bigger task for translations then it is for -en.
> (1) Modify configure.php, keep the EN-Revision tag in .manual.xm(l
> noticed that the EN-Revision tag was removed in .manual.xml)
Only translated files have EN-Revision tags. Files that are only in
the base tree (phpdoc/manual.xml) or should not be translated
(phpdoc/en/contributors.xml) will never have EN-Revision tags.
configure.php does not modify the XML in any way, all it does is
combining the thousands of files into one and process the xincludes.
> (2) Do some hacking in PhD, get revision comparison results(how
> revcheck.php does this?), output them to the manual page in a user
> friendly mode.
revcheck.php compares individual files and greps for the revision tags.
PhD can't because it doesn't know anything about files. All it knows is XML.
If the english XML file has <book xml:id="foo.bar" revision="1.2 />
PhD could however store that info.
Then when rendering translations: <book xml:id="foo.bar"
revision="1.1" />.. PhD matches the revision attribute against the
stored revision of that ID and instantly sees that 1.1 is lower,
making that chunk outdated and can therefore write "This translation
is outdated" into that chunk.
Currently we are using comments, En-Revision, but PhD has no chance of
knowing to which chunk/file that comment relates too.
>>> (2) Online bug-report
>>> Through users can report translation bug by sending an email to phpdoc
>>> mail list or via the bug-report system, but it's inconvenient。So how
>>> about add an "Report Translation Bug" at the end of each manual page?
>>> Just near the "Add a note" is OK. This report should directly mailing
>>> to phpdoc-{lang} mail list。
>>
>> This shouldn't be too difficult as we could simply link each manual
>> page to the appropriate bugs page. Not sure how far we want to go, but
>> it seems like we'd want to track the page too so we'd need to update
>> the bugs system to allow that. As for sending out emails, not sure how
>> I feel about that.
>>
> sending out emails is not the key point, for some peoples are not good
> at english, current bug report system is too complicated for them, so
> many of them will give up reporting the bug. A quick, simple bug
> report mechanism (simple as Add a Note?) will be helpful. The SPAM?
> email verification will eliminate most of them.
There are extremely few people that maintain the user contributed
notes. I don't know of any translator that even reads through them.
Reporting bugs via user notes will simply get lost.
Automatically filing bug-reports via some AJAX interface when clicking
"Report a bug on this page" is however plausible idea.
I personally do not have the time to implement it, but I would be
happy to help out and review such patch.
>> On a related note, awhile ago there was some work done on an online
>> editor but it sorta stalled... here's a thread:
>>
>> http://markmail.org/message/xchvvhk4hlvg33a3
>>
>> See what you think about all of this.
>
> I have tried the online editor locates in phpdoc/scripts directory,
> it's interesting and I think an online editing like wiki will be
> better。
No. We are not moving to a wiki.
-Hannes
