[Lazarus] Incorrect documentation for TCustomTreeView.TopItem

[Hans-Peter Diettrich]

Vladimir Zhirov schrieb:

>> I'm currently revising the documentation. If you can create an patch, 
>> you can send it to me and I'll commit it, or you proceed in the usual 
>> way, using the bug tracker.
>> ...
>> I'd suggest that you (or everybody else) reviews the entire
>> documentation of a class, and creates an patch for an update.
>> ...
> 
> Ok, then one more question. Can we use parts of existing Delphi
> documentation (I mean words and phrases, not entire help articles),
> or it is illegal and we must create a "cleanroom" docs?

IMO it's legal to use parts of the Delphi documentation, with regards to 
the contained *information*. International copyright (droit d'auteur) 
protects (primarily) the *form* of a document, while the contained 
information is (almost) freely usable. Scientific and technical 
documentation tends to be very short and precise, so that there often 
exists no way to express the contained information in an different way, 
without a risk to introduce errors or chances for misunderstandings (in 
detail when written by non-native speakers of a language).

The extracted information should be checked for consistency with the 
Lazarus implemententation, eventual errors have to be corrected, and the 
reviewed information then can be rephrased - as far as there exists room 
for a different wording. IMO it doesn't make sense and is not required 
to express information in a more complicated or otherwise different 
wording, when such an attempt may result in incorrect information.

But that's only my opinion, let's hear what others think about it...

> In the latter
> case avoiding Delphi documentation at all could be quite difficult for
> those whose English is poor. I.o.w. should we leave ambiguous terms
> to the review of native English speakers rather than spy such terms in
> Delphi docs?

In scientific writing *citations* are commonly used. IMO it's a good 
idea to enclose literally copied parts in quotes, to mark it as a 
quotation, *and* as an hint to further reviewers of the documentation, 
where some brushing-up may be required. The sources of the quotations 
have to be mentioned, somewhere, at least in the preface or other 
prominent place of the entire Lazarus documentation. [I've started to 
add more hints for reviewers, enclosed in brackets like this sentence is.]

In the first run over the documentation I see no special need for 
formatting, except for lists and links. Important links should be placed 
into the "See also" section first, from where they can be copied later 
into all places in the final text, where hyperlinks may be helpful to 
the reader.


Another way to circumvent legal problems were the immediate use of the 
Delphi help files in Lazarus, where every user only must get the files 
from some legal source (e.g. from the Embarcadero download pages, 
openKylix or Delphi Explorer or trial versions...). Then it makes no 
(legal) difference, whether the files are used privately by a Delphi or 
Lazarus user or IDE :-)

Since the Delphi documentation is not fully applicable to Lazarus and 
the LCL, I also thought about publishing my helpfile decompilers (for 
HLP and CHM files), so that Lazarus specific patches can be applied to 
the extracted text. This would reduce the amount of reviews for an 
immediately usable online help. The patched text could be converted into 
HTML, or any other format, for online help display. One of my first 
exercises in OH was a replacement for WinHelp, that presented the help 
topics in exactly the same way as WinHelp does, including the handling 
of links. Unfortunately that program was developed with BC3, for Win3.1, 
so that the code can not be incorporated easily into the Lazarus IDE or 
used on other platforms.

DoDi