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
On Sun, 31 May 1998, Peter Gerwinski wrote:
Hi Folks,
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'.
I would suggest to use the plain text format for discussion and convert it into texi only when the final version is ready.
- 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 ...)
Short examples for every single section make the reference part very long. How about to include sample source as Appendix? They could be longer and more real-life like. In the reference sections we can point to them: "See sample code xxx, zzz ..". For that the selected - possibly revised - versions of the test suit will do. (So it is not much extra work.)
Cheers,
miklos
According to Miklos Cserzo:
I would suggest to use the plain text format for discussion and convert it into texi only when the final version is ready.
I agree in spirit, but how do you know whether the version you are submitting is already the final one or not? Another problem is to make sure that everyone is talking about the same version - including some context that only comes somewhere later in the section.
Short examples for every single section make the reference part very long.
Yes, but at least I learn a lot better from examples than from explanations. When I want, for instance, learn something about Extended Pascal I compile a short program with Prospero Extended Pascal (which claims to be compliant). Reading the ISO specifications causes nothing but confusion and headaches - except for the examples included at some places.
How about to include sample source as Appendix? They could be longer and more real-life like.
This is certainly a useful addition, but IMHO an example should accompaign (sp?) every single section - even if this makes it long. The hypertext structure helps not to lose overview.
In the reference sections we can point to them: "See sample code xxx, zzz ..". For that the selected - possibly revised - versions of the test suit will do. (So it is not much extra work.)
This causes a lot of searching in the book in case someone really prints it out. I would be looking up page numbers all the time.
Greetings,
Peter
On Tue, 2 Jun 1998, Peter Gerwinski wrote:
According to Miklos Cserzo:
I would suggest to use the plain text format for discussion and convert it into texi only when the final version is ready.
I agree in spirit, but how do you know whether the version you are submitting is already the final one or not? Another problem is to make sure that everyone is talking about the same version - including some context that only comes somewhere later in the section.
Well, the contributors should submit the sections twice. First for comments and corrections in plain text, second in texi after the proper changes introduced.
Short examples for every single section make the reference part very long.
Yes, but at least I learn a lot better from examples than from explanations. When I want, for instance, learn something about Extended Pascal I compile a short program with Prospero Extended Pascal (which claims to be compliant). Reading the ISO specifications causes nothing but confusion and headaches - except for the examples included at some places.
OK, keep the examples but keep them short and simple, then add a reasonable number of sample programs as an Appendix.
Cheers,
miklos
According to Miklos Cserzo:
Well, the contributors should submit the sections twice. First for comments and corrections in plain text, second in texi after the proper changes introduced.
This makes sense. Okay with me - as long as the contributors *really* submit a texified version. And if something does not get comments, the contributor posts the texified version after some days?
OK, keep the examples but keep them short and simple, then add a reasonable number of sample programs as an Appendix.
What about having those longer example programs both in the Appendix as well as in a directory coming with the distribution - as demo programs?
Peter
On Tue, 2 Jun 1998, Peter Gerwinski wrote:
According to Miklos Cserzo:
Well, the contributors should submit the sections twice. First for comments and corrections in plain text, second in texi after the proper changes introduced.
This makes sense. Okay with me - as long as the contributors *really* submit a texified version. And if something does not get comments, the contributor posts the texified version after some days?
OK, keep the examples but keep them short and simple, then add a reasonable number of sample programs as an Appendix.
What about having those longer example programs both in the Appendix as well as in a directory coming with the distribution - as demo programs?
Fine for me. Let's do it in this way.
miklos
-
Miklos Cserzo -
Peter Gerwinski