Re: Ann: Little tutorial about streams

[Ludovic Brenta <ludovic@ludovic-brenta.org>]

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.