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