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=-1.9 required=5.0 tests=BAYES_00 autolearn=ham
	autolearn_force=no version=3.4.4
X-Google-Thread: 103376,3ae40b42b99b8123
X-Google-NewGroupId: yes
X-Google-Attributes: gida07f3367d7,domainid0,public,usenet
X-Google-Language: ENGLISH,ASCII-7-bit
Path: 
 g2news1.google.com!news4.google.com!feeder.news-service.com!85.214.198.2.MISMATCH!eternal-september.org!feeder.eternal-september.org!.POSTED!not-for-mail
From: Ludovic Brenta <ludovic@ludovic-brenta.org>
Newsgroups: comp.lang.ada
Subject: Re: Ann: Little tutorial about streams
Date: Mon, 28 Feb 2011 21:32:36 +0100
Organization: A noiseless patient Spider
Message-ID: <8739n7vr17.fsf@ludovic-brenta.org>
References: 
 <f8e7ccbf-a966-4568-9f0d-8e9e38f37dc6@glegroupsg2000goo.googlegroups.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Injection-Info: mx03.eternal-september.org;
 posting-host="QyVJj6mNDwpF2dGh28S43w";
	logging-data="7500"; mail-complaints-to="abuse@eternal-september.org";
	posting-account="U2FsdGVkX19N8NgVtysZKDkjRtP9lu1u"
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux)
Cancel-Lock: sha1:hRZE+XFZbBl+SKxjUbfNZGZOiJA=
	sha1:qAIqtfAM1s1KmLCQYPM6c2Q8yNE=
Xref: g2news1.google.com comp.lang.ada:17648
Date: 2011-02-28T21:32:36+01:00
List-Id: <comp.lang.ada>

mockturtle writes:
> Dear.all,

> remembering my initial difficulties with streams (I self-taught Ada,
> using few tutorials and lots of experiments before landing to the RM),
> I decided to write a page (my first one, so be patient :-) of the
> Wikibook with a little stream tutorial
>
> http://en.wikibooks.org/w/index.php?title=Ada_Programming/Input_Output/Stream_Tutorial
>
> As said in the page, the goal is to give to the reader an intuitive
> idea about how streams work so, in order to not hide the forest with
> too many leaves, some of the finest details have been omitted.  A
> subpage of the above page has a fairly complex example that is not
> complete yet, but I plan to complete it soon.
>
> The page is not linked yet with the book body.  I was thinking to add
> a link to it in the "Input Output" page as soon as the subpage with
> the example is in a good state.
>
> Any feedback [especially positive one :-) :-) :-) :-)] is appreciated.

Your page is great.  How's that for positive criticism :)

I've made a couple edits which you are, of course, free to revert.  I
(think I) have generally improved the style of the prose but not changed
the basic structure of the tutorial.

Now I have specific suggestions for further improvement:

* Between the sections "Abstract streams" and "Serialization functions",
  it would be nice to have a section on "Predefined concrete streams"
  discussing, in particular Ada.Text_IO.Text_Stream, so that beginners
  can start writing to the console using streams.

* In the section about Ada.Text_IO.Text_Streams, explain that this is
  much faster than Ada.Text_IO and why (hint: ARM A.10.4, A.12.2(7))

* Your first example of a serialization function, procedure
  Example.Print, seems too complicated.  But that may be on purpose, so
  I have not changed it.  Here is a simpler implementation:

  package body Example is
     procedure Print (Stream : not null access Ada.Streams.Root_Stream_Type'Class;
                      Item   : in  Int) 
     is
        -- Convert Item to String (with no trailing space)
        Value  : String := Trim(Int'Image(Item), Left);
        
        -- Convert Value'Length to String (with no trailing space)
        Len    : String := Trim(Integer'Image(Value'Length), Left);
     begin 
        String'Write (Stream, Len & 'i' & Value);
     end Print;
  end Example;

Thank you for taking the initiative writing this nice tutorial.  I think
it really helps lower the bar for novices.

-- 
Ludovic Brenta.