Hi, everybody! Miklos Cserzo wrote:

Before the official release we should do something about the documentation. It is really poor. Some 160 pages are missing from the language reference. That is definitely too much writing for a single person but with a joint effort it should not be a problem. How about to post the missing sections of the reference to the list?

I consider this a VERY GOOD idea! While some nice people are already working on improving the documentation, a joint effort will certainly yield a faster and better result. Of course, such a project must be coordinated; otherwise we will end up with a lot of incompatible fragments. Here are my thoughts about how to do that: * Everyone is encouraged to write or improve sections of the GPC reference, `reference.texi'. The article should be mailed to this list with a subject like GPC REFERENCE: abs It must contain a complete section of `reference.texi' in the standardized format (GNU Texinfo) *including* the separator lines beginning with `@c'. I will post a real-world example in a few minutes. For a description of the GNU Texinfo format, type `info -f texinfo'. * When replying and improving the text, always include a complete snippet as described above without leading `> ' or such. This is to simplify integration into the file `reference.texi'. * Spelling corrections are welcome. And now for some guidelines how the documentation should look like: * Be exact. Examples must work. * Really explain it. "Help" screens like "Use the `Procedure' keyword to declare a procedure" do not help anyone. *Nothing* is self-evident. * Give examples. Besides a tiny easy-to-understand example there should always be a real-world example that helps to avoid pitfalls. (See `info -f gpc -n and' for an example: The first `if' is the easy example, while the `else if' describes a common pitfall. Maybe it would be even better to separate them ...) * Use cross references. When a cross reference appears in the help text, it is usually desirable to repeat it in the `See also' subsection. * Be technical, not personal. For example, I do not like `goto', and I never use it in my programs, but if I explain it, this does not matter. If there are some *technical* drawbacks using `goto' I can mention them, but a sentence telling "better don't use `goto'" causes nothing but confusion. * Read the tips in `info -f texinfo -n Tips'. Comments? An example of what I mean will follow in a few minutes. Also, I am uploading the file `reference.texi' to ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/alpha/reference.texi so you do not need to download the whole GPC source just to get your hands on that single file. Peter -- Peter Gerwinski, Essen, Germany, http://home.pages.de/~Peter.Gerwinski/ Maintainer GNU Pascal - http://home.pages.de/~GNU-Pascal/ - gpc-980511 PGP key on request - 6C 94 45 BE 28 A4 96 - 0E CC E9 12 47 25 82 75 Fight the SPAM and UBE! - http://spam.abuse.net/ - http://maps.vix.com/