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