From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-2.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI autolearn=unavailable autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,e61c8636ef35379d X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2001-01-16 08:10:02 PST Path: supernews.google.com!sn-xit-03!supernews.com!freenix!enst!enst.fr!not-for-mail From: "Robert C. Leif, Ph.D." Newsgroups: comp.lang.ada Subject: RE: Examples in Docs Date: Tue, 16 Jan 2001 08:06:49 -0800 Organization: ENST, France Sender: comp.lang.ada-admin@ada.eu.org Message-ID: Reply-To: comp.lang.ada@ada.eu.org NNTP-Posting-Host: marvin.enst.fr Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: avanie.enst.fr 979661289 61306 137.194.161.2 (16 Jan 2001 16:08:09 GMT) X-Complaints-To: usenet@enst.fr NNTP-Posting-Date: Tue, 16 Jan 2001 16:08:09 +0000 (UTC) To: Return-Path: X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2911.0) In-Reply-To: <940f9j$nj2$1@nnrp1.deja.com> Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4522.1200 Errors-To: comp.lang.ada-admin@ada.eu.org X-BeenThere: comp.lang.ada@ada.eu.org X-Mailman-Version: 2.0 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: comp.lang.ada mail<->news gateway List-Unsubscribe: , List-Archive: Errors-To: comp.lang.ada-admin@ada.eu.org X-BeenThere: comp.lang.ada@ada.eu.org Xref: supernews.google.com comp.lang.ada:4058 Date: 2001-01-16T08:06:49-08:00 From: Bob Leif To: Peter Richtmyer et al. I believe that you have two subjects intertwined. Since the Ada Reference Manual is an official document, for purposes of correctness and maintenance, it should be kept as small as possible. However, when it serves as a teaching document (using teaching in a broad sense), the user would benefit from examples. Since many of us make use of the HTML version, it should be possible to add hypertext linkages to jump to examples in this derived document. The hypertext document should include a disclaimer and each example could have a short disclaimer stating that the example(s) are not part of the official Reference Manual. I hope this will be a useful compromise or work-around. -----Original Message----- From: comp.lang.ada-admin@ada.eu.org [mailto:comp.lang.ada-admin@ada.eu.org]On Behalf Of peter_richtmyer@my-deja.com Sent: Monday, January 15, 2001 7:31 PM To: comp.lang.ada@ada.eu.org Subject: Examples in Docs, was Re: Escape Sequences in Strings Robert Dewar said: > Note: for my own taste, I hate to present-by- example, and I > hate examples, but my experience is most people like examples. > For instance, most people want MORE examples in the RM, I > regard them as irritating redundant (well hopefully redundant) > non-normative junk :-) This statement surprised me a little at first. I always enjoy reading your comments (Unless you are *bashing* one of my comments.) :-) I have saved a comment of yours where you said that you *liked* to document code, and encourage others to do so. You said that, if you do it enough, you can get to enjoy it (or words to that effect.) Putting examples in documents is somewhat similar to putting comments in code. It is not necessary, but it sure makes it easier for the readers. But then, I have written documents that I thought were pretty clear, only to find that others needed examples to understand them. And yet I am like those people. I like good examples in the documents and *good* comments in the code. In either code or documents, the author (almost) always knows what he is saying. But code and documents should be written for the reader. (Yes, I know that that is not an original thought on my part). :-) (Of course, code is written for the compiler too) :-) My best regards, Peter Sent via Deja.com http://www.deja.com/