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