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
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
