Hi,

I found a problem in documentation that I think should be reported. Currently, TCustomTreeView.TopItem documentation at http://lazarus-ccr.sourceforge.net/docs/lcl/comctrls/tcustomtreeview.topitem.html says

"TopItem - the first node on the list"

while in fact this is wrong. TopItem is "the first visible" or "topmost" node, as specified in VCL documentation at http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/ComCtrls_TCustomTreeView_TopItem.html

If there is more appropriate way to handle
such problems please let me know.

I found a problem in documentation that I think should be reported.

[...]

If there is more appropriate way to handle such problems please let me know.

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 also could update the documentation of single items on the fly, but this will result in uncontrollable patchwork. Instead I'd suggest that you (or everybody else) reviews the entire documentation of a class, and creates an patch for an update. Then it will be easier to distinguish "raw" from reviewed documentation, so that other contributors can concentrate on the improvement of the not yet reviewed documentation. I should attach a note to every reviewed class description, with the date and state of the review. In the final state the correctness of the documentation should have been approved by the implementor of the class, or by somebody else with the required knowledge about the implementation.

Poor English is not an excuse for not contributing to the documentation, I'll try to improve the supplied texts, if necessary. If some native English speaker(s) will fix my own flaws, they are invited to review the existing documentation as well.

DoDi

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? 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?

At least the same words can be used because they are part of a language and not owned by Delphi authors.
Phrases, I don't know. If a component behaves identically with Delphi component then you sometimes end up with identical phrases even without knowing it. But copy-pasting blocks of documentation is illegal sure.

Reverse engineering is used with other technical things so that one person or group figures out how a gadget works and makes a description of it. Then another person or group builds the same thing based on the description. What would it mean for Delphi documentation? Feed it to Google translator (without reading it) for your own language and then translate to English. Doesn't sound good...

Maybe someone knows the legal rules better then me.

Juha Manninen

I have done quite a lot of the LCL documentation, and have the great advantage of never having used Delphi!

I was therefore forced to use my own words for the descriptions (or sometimes copy/pasted comments from the program source).

Where possible people should try to say things in their own words; don't worry about poor knowledge of english, as other eyes can look and correct it. If you feel you MUST copy something from Delphi docs, make it clear with a comment, and someone else may try to un-Delphi it!!

Chris

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 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