Escape Sequences in Strings

Escape Sequences in Strings

[Jean Cohen]

I'm quite new to Ada and consider a transition from C++, therefore I am 
still 
evaluating the benefits of the language.

There is a minor annoyance (minor in terms of importance) which plagues me 
ever since: what about ANSI escape sequences in strings? As you all 
certainly 
know it is quite easy and straightforward in C++ to set cursor positions, 
the 
format (tabulators, newlines etc.) of a string etc. by using escape 
sequences.
(by the way, I like the concept of streams in C++.)

My question is then - How is it possible to use escape sequences (or 
something 
functionally equivalent) in Ada 95?

Thanks for your replies,
Jean Cohen

Re: Escape Sequences in Strings

[John English]

Jean Cohen wrote:
> My question is then - How is it possible to use escape sequences (or
> something functionally equivalent) in Ada 95?

Escape sequences are easy enough:
  Ada.Text_IO.Put(ASCII.ESC & "[2J");    -- clear the screen (?)

However, "something functionally equivalent" is probably a better
way to go...

-----------------------------------------------------------------
 John English              | mailto:je@brighton.ac.uk
 Senior Lecturer           | http://www.it.bton.ac.uk/staff/je
 Dept. of Computing        | ** NON-PROFIT CD FOR CS STUDENTS **
 University of Brighton    |    -- see http://burks.bton.ac.uk
-----------------------------------------------------------------

Re: Escape Sequences in Strings

[Robert Dewar]

In article <3A1275A2.F2A843E9@bton.ac.uk>,
  John English <je@bton.ac.uk> wrote:

> Escape sequences are easy enough:
>   Ada.Text_IO.Put(ASCII.ESC & "[2J");    -- clear the screen


But we would never want to do that in a program, and indeed
Ada here helps us avoid the nasty habit of embedding odd
escape sequences in strings in C without any comments, often
with a result of making the program non-portable. The proper
coding in Ada would be:

  Clear_Screen : constant String := ASCII.ESC & "[2J";
  --  ANSI escape sequence for clearing screen. Modify to
  --  meet requirements of your system.

  Put (Clear_Screen);

It is almost always wrong to have mysterious constants in code!


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Escape Sequences in Strings

[Ehud Lamm]

Robert Dewar <robert_dewar@my-deja.com> wrote in message
news:8uub09$9sr$1@nnrp1.deja.com...
> In article <3A1275A2.F2A843E9@bton.ac.uk>,
>   John English <je@bton.ac.uk> wrote:
>
> > Escape sequences are easy enough:
> >   Ada.Text_IO.Put(ASCII.ESC & "[2J");    -- clear the screen
>
>
> But we would never want to do that in a program, and indeed
> Ada here helps us avoid the nasty habit of embedding odd
> escape sequences in strings in C without any comments, often
> with a result of making the program non-portable. The proper
> coding in Ada would be:
>
>   Clear_Screen : constant String := ASCII.ESC & "[2J";
>   --  ANSI escape sequence for clearing screen. Modify to
>   --  meet requirements of your system.
>
>   Put (Clear_Screen);
>
> It is almost always wrong to have mysterious constants in code!
>

And while you are at it, put the constant in a seperate packge of env.
specific control codes.


--
Ehud Lamm   mslamm@mscc.huji.ac.il
http://purl.oclc.org/NET/ehudlamm <==  Me!

Re: Escape Sequences in Strings

[John English]

Ehud Lamm wrote:
> Robert Dewar <robert_dewar@my-deja.com> wrote in message
> news:8uub09$9sr$1@nnrp1.deja.com...
> > In article <3A1275A2.F2A843E9@bton.ac.uk>,
> >   John English <je@bton.ac.uk> wrote:
> >
> > > Escape sequences are easy enough:
> > >   Ada.Text_IO.Put(ASCII.ESC & "[2J");    -- clear the screen
> >
> >
> > But we would never want to do that in a program, and indeed
> > Ada here helps us avoid the nasty habit of embedding odd
> > escape sequences in strings in C without any comments, often
> > with a result of making the program non-portable. The proper
> > coding in Ada would be:
> >
> >   Clear_Screen : constant String := ASCII.ESC & "[2J";
> >   --  ANSI escape sequence for clearing screen. Modify to
> >   --  meet requirements of your system.
> >
> >   Put (Clear_Screen);
> >
> > It is almost always wrong to have mysterious constants in code!
> >
> 
> And while you are at it, put the constant in a seperate packge of env.
> specific control codes.
> 
> --
> Ehud Lamm   mslamm@mscc.huji.ac.il
> http://purl.oclc.org/NET/ehudlamm <==  Me!

Hey guys, I agree completely, but I wanted to give a *short* answer,
not a complete package hierarchy with all the trimmings... and I
said it wasn't the way to go anyway... Give us a break!

-----------------------------------------------------------------
 John English              | mailto:je@brighton.ac.uk
 Senior Lecturer           | http://www.it.bton.ac.uk/staff/je
 Dept. of Computing        | ** NON-PROFIT CD FOR CS STUDENTS **
 University of Brighton    |    -- see http://burks.bton.ac.uk
-----------------------------------------------------------------

Re: Escape Sequences in Strings

[Marin David Condic]

John English wrote:

> Hey guys, I agree completely, but I wanted to give a *short* answer,
> not a complete package hierarchy with all the trimmings... and I
> said it wasn't the way to go anyway... Give us a break!

Good point. Sometimes we tend to "over answer" a question, possibly leading
a newbie to believe that Ada is just too complicated to do what they want.
With the original question, I thought the best thing was to explain how to
do what the questioner wanted to do - use escape codes in a string.
Presumably, if he learns this much, Ada is now useful to him. As he moves
along with learning the language, it will probably become clear that there
are better ways of structuring code to manipulate the cursor. Possibly, he
was already in the process of building such a package and just wanted to
know how to implement the low-level features? (Even in C++, you'd isolate
this kind of thing at a low level - or learn rather quickly that you
*should* have! :-)

Let's keep the life of a newbie comfortable and possibly just suggest that
there *are* better ways and wait to see if they ask...

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Escape Sequences in Strings

[Tarjei T. Jensen]

John English
>Hey guys, I agree completely, but I wanted to give a *short* answer,
>not a complete package hierarchy with all the trimmings... and I
>said it wasn't the way to go anyway... Give us a break!

Perhaps even worse, it may not be what the person wanted to know. It is more
likely that he wanted to know about the equivalent of the C escape characters
like \n, \r, \a, \t, \oxXX, etc.


Greetings,

Re: Escape Sequences in Strings

[Ken Garlington]

"Tarjei T. Jensen" <tarjei.jensen@kvaerner.com> wrote in message
news:8v0m76$1mt1@news.kvaerner.com...
:
: John English
: >Hey guys, I agree completely, but I wanted to give a *short* answer,
: >not a complete package hierarchy with all the trimmings... and I
: >said it wasn't the way to go anyway... Give us a break!
:
: Perhaps even worse, it may not be what the person wanted to know. It is
more
: likely that he wanted to know about the equivalent of the C escape
characters
: like \n, \r, \a, \t, \oxXX, etc.

Character     C_Escape_Sequence     Ada_Equivalent
"     \"     "" or Ada.Characters.Latin_1.Quotation
'     \'     ' or Ada.Characters.Latin_1.Apostrophe
?     \?     ? or Ada.Characters.Latin_1.Question
\     \\     \ or Ada.Characters.Latin_1.Reverse_Solidus
BEL     \a     Ada.Characters.Latin_1.BEL
BS     \b     Ada.Characters.Latin_1.BS
FF     \f     Ada.Characters.Latin_1.FF
NL     \n     Ada.Characters.Latin_1.NL
CR     \r     Ada.Characters.Latin_1.CR
HT     \t     Ada.Characters.Latin_1.HT
VT     \v     Ada.Characters.Latin_1.VT
octal     \ddd     Character'Val(8#ddd#)
hex     \xhh     Character'Val(16#hh#)

For Ada83 compilers, ASCII can be used in lieu of Ada.Characters.Latin_1 in
most cases (with Query for Question and Back_Slash for Reverse_Solidus).

Re: Escape Sequences in Strings

[Marin David Condic]

Ken Garlington wrote:

> Character     C_Escape_Sequence     Ada_Equivalent
> "     \"     "" or Ada.Characters.Latin_1.Quotation
> '     \'     ' or Ada.Characters.Latin_1.Apostrophe
> ?     \?     ? or Ada.Characters.Latin_1.Question
> \     \\     \ or Ada.Characters.Latin_1.Reverse_Solidus
> BEL     \a     Ada.Characters.Latin_1.BEL
> BS     \b     Ada.Characters.Latin_1.BS
> FF     \f     Ada.Characters.Latin_1.FF
> NL     \n     Ada.Characters.Latin_1.NL
> CR     \r     Ada.Characters.Latin_1.CR
> HT     \t     Ada.Characters.Latin_1.HT
> VT     \v     Ada.Characters.Latin_1.VT
> octal     \ddd     Character'Val(8#ddd#)
> hex     \xhh     Character'Val(16#hh#)

And you can even avoid the verbosity (if desired) using a "use" clause as in:

with Ada.Characters.Latin_1 ;
use Ada.Characters.Latin_1 ;
procedure Demo is
    Some_String    : constant String    := "Ring the bell: " & BEL & "New Page:
" & FF  ;
begin
    null ;
end Demo ;

Its pretty obvious to us Ada Old Timers, but a newbie might see  "Ring the
bell: " & Ada.Characters.Latin_1.BEL as so needlessly verbose that they'll run
off telling everyone that Ada sucks because they can't write  "Ring the bell:
\a". If it were true, they'd have a point.

Just a small thing - but often something we forget.

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Escape Sequences in Strings

[Keith Thompson]

"Ken Garlington" <Ken.Garlington@computer.org> writes:
[...]
> NL     \n     Ada.Characters.Latin_1.NL

There is no Ada.Characters.Latin_1.NL.  The C '\n' character is most
commonly LF (linefeed).  In general, it's whatever acts as a newline
character on the current system.  On some systems, the I/O subsystem
has to map '\n' to a CR LF sequence on output, and do the reverse
mapping on input.

-- 
Keith Thompson (The_Other_Keith) kst@cts.com  <http://www.ghoti.net/~kst>
San Diego Supercomputer Center           <*>  <http://www.sdsc.edu/~kst>
Welcome to the last year of the 20th century.

Re: Escape Sequences in Strings

[Preben Randhol]

On Wed, 15 Nov 2000 05:07:12 -0500, Jean Cohen wrote:
>I'm quite new to Ada and consider a transition from C++, therefore I am 
>still 
>evaluating the benefits of the language.
>
>There is a minor annoyance (minor in terms of importance) which plagues me 
>ever since: what about ANSI escape sequences in strings? As you all 
>certainly 
>know it is quite easy and straightforward in C++ to set cursor positions, 
>the 
>format (tabulators, newlines etc.) of a string etc. by using escape 
>sequences.

Yes, though not necessarily the best solution. I recommend you use
ncurses or some other library to do this.

>(by the way, I like the concept of streams in C++.)

>
>My question is then - How is it possible to use escape sequences (or 
>something 
>functionally equivalent) in Ada 95?

http://www.adapower.com/reuse/Formatted_Output.html


-- 
Preben Randhol  --  Ph.D Student  --  http://www.pvv.org/~randhol
                                               -- Life is a habit

Re: Escape Sequences in Strings

[Marin David Condic]

Jean Cohen wrote:

> (by the way, I like the concept of streams in C++.)
>

Ada has streams and stream I/O as well. It works pretty well and I think if
you get familiar enough with Ada to understand "The Ada Way" of doing it,
you'll find it to be a handy feature.

>
> My question is then - How is it possible to use escape sequences (or
> something
> functionally equivalent) in Ada 95?

Escape sequences are just a series of characters in Ada, pretty much as they
are in C/C++. You can include non-printable characters into a string by using
the constants defined in the package Ada.Characters.Latin_1. See Appendix
A.3.3 of the ARM for the full list.

However, you might find it easier to shop around for an existing package to do
all your cursor moving for you. Start cruising around http://www.Adapower.com/
for reusable components and links to other Ada sites. I'm sure someone here
will point you at more than one package to do this job for you.

MDC

--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Ada Streams usage (was Escape Sequences in Strings)

[Marc A. Criley]

Marin David Condic wrote:
> 
> Jean Cohen wrote:
> 
> > (by the way, I like the concept of streams in C++.)
> >
> 
> Ada has streams and stream I/O as well. It works pretty well and I think if
> you get familiar enough with Ada to understand "The Ada Way" of doing it,
> you'll find it to be a handy feature.

Streams were an excellent addition to the Ada 95 standard and have
proven to
be very useful and flexible.

Not only does one get all the benefits of a stream-based approach, but
by
extending the Root_Stream_Type via inheritance and implementing one's
own
Read() and Write() subprograms, one can employ stream-based
communication
via any available communication medium, not just files.

I've done this for sockets, and so now I can output to a socket by doing
something along the lines of:

   Type_Name'Write(Socket_Stream, Item);

with a corresponding 'Read on the other end.  Naturally 'Output and
'Input are also available and have been used.

And of course I can change the transport mechanism if necessary by
modifying the extension of Root_Stream_Type.  ("Socket_Stream" was used
for illustrative purposes, you don't necessarily want to include an
indication of the internals of an activity within its name.)

A number of cool additions were made to Ada 95, things like Streams and
the Distributed Systems Annex, that I have found are so straightforward
to
use that it's not unusual to have small, experimental prototypes working
the first time they're run.

Marc A. Criley
Senior Staff Engineer
Quadrus Corporation

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

What a bright and clever guy you must be! What company did you say you worked
for? They must be lucky to have you on staff and they must have a real eye for
talent. I'll bet they have a real powerhouse of a team as a result. Its clear
they know how to hire the very best. I'm sure when someone does business with
your company, they really get their money's worth! :-) :-) :-)

Streams are a really powerful mechanism especially for communication stuff. My
only real gripe is with some low level issues such as representation (not a
problem in many cases) and the potential overhead problems for hard-real-time
applications.

I've done some things with streams, etc., for Winsock applications. If you get
curious about it and maybe want to give me some opinions on it, we should talk.
Drop me a note when you get a minute.

MDC



"Marc A. Criley" wrote:

> Streams were an excellent addition to the Ada 95 standard and have
> proven to
> be very useful and flexible.
>
> Not only does one get all the benefits of a stream-based approach, but
> by
> extending the Root_Stream_Type via inheritance and implementing one's
> own
> Read() and Write() subprograms, one can employ stream-based
> communication
> via any available communication medium, not just files.
>
> I've done this for sockets, and so now I can output to a socket by doing
> something along the lines of:
>
>    Type_Name'Write(Socket_Stream, Item);
>
> with a corresponding 'Read on the other end.  Naturally 'Output and
> 'Input are also available and have been used.
>
> And of course I can change the transport mechanism if necessary by
> modifying the extension of Root_Stream_Type.  ("Socket_Stream" was used
> for illustrative purposes, you don't necessarily want to include an
> indication of the internals of an activity within its name.)
>
> A number of cool additions were made to Ada 95, things like Streams and
> the Distributed Systems Annex, that I have found are so straightforward
> to
> use that it's not unusual to have small, experimental prototypes working
> the first time they're run.
>
> Marc A. Criley
> Senior Staff Engineer
> Quadrus Corporation

--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Ted Dennison]

In article <3A13F487.59859C0F@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:

> Streams are a really powerful mechanism especially for communication
> stuff. My only real gripe is with some low level issues such as
> representation (not a problem in many cases) and the potential
> overhead problems for hard-real-time applications.

We are using streams for subsystem checkpointing in a hard real time
system. Its actually working quite well. But I did have to write my own
stream types to get it to work the way I needed it to.

Streams are quite useful any time you need to mainupulate large amounts
of unstructured data entirely within Ada. But if you need low-level
control over what is going on you are probably going to end up having to
write your own streams and stream attribute routines. That can be a lot
of work compared to some of the old-fashioned alternatives. Plus if you
are rewriting both ends, often there's no benifit to using streams over
just making your own custom object with read and write methods.

--
T.E.D.

http://www.telepath.com/~dennison/Ted/TED.html


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Ted Dennison wrote:

> We are using streams for subsystem checkpointing in a hard real time
> system. Its actually working quite well. But I did have to write my own
> stream types to get it to work the way I needed it to.
>

Well, part of my objection to streams is the overhead of the data motion and
the way it degenerates to a (potentially) large number of small procedure
calls. (It wouldn't be so bad if the compiler could figure out when to
generate a really fast block-move instruction instead of a bazillion
procedure calls. But I suppose there may be language issues - or maybe just
that it is really hard to do.) If you find a way to "roll your own" that
eliminates or minimizes this, then it can still work quite well.

I guess some of it depends on how hard is "hard". Its at least a
deterministic amount of overhead if the message sizes don't vary. (Dynamic
things like Unbounded_String, etc. might pose problems in this respect.) But
if you are running a heavily loaded processor, the overhead is unnecessary
work that ought to be eliminated so you can use it for something more
important.

Maybe my usage of the word is not entirely accurate. "Hard-real-time"
usually means that failure to meet deadlines constitutes failure of the
system. If your processor does a gazillion-instructions-per-second and
you're only using 1% of your CPU, it can still be a "hard-real-time" system.
I suppose I was thinking more along the lines of "difficult" real time
systems. :-)

>
> Streams are quite useful any time you need to mainupulate large amounts
> of unstructured data entirely within Ada. But if you need low-level
> control over what is going on you are probably going to end up having to
> write your own streams and stream attribute routines. That can be a lot
> of work compared to some of the old-fashioned alternatives. Plus if you
> are rewriting both ends, often there's no benifit to using streams over
> just making your own custom object with read and write methods.

Yeah. I understand. In most cases, I'd like to just use the standard Ada
streams because it just automagically works for you. You do some fairly
small amount of work at the base level and it just off and does it for
everything you build up on it. Very elegant. Very tidy. Extremely clever.
But when you've got to overcome the representation issues and/or eliminate
the overhead by doing your own Read and Write routines, you end up putting
so much extra work into it that you might just as well pitch streams and
handle all the bytes yourself.

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Ted Dennison]

In article <3A14108E.CCB398A1@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:

> Well, part of my objection to streams is the overhead of the data
> motion and the way it degenerates to a (potentially) large number of
> small procedure calls. (It wouldn't be so bad if the compiler could
> figure out when to generate a really fast block-move instruction
> instead of a bazillion procedure calls. But I suppose there may be

Quite true. There was one instance where we had to replace a 'Write on a
large array to a dispatching call to Ada.Streams.Write. The old way was
causing one 60Hz task to take 20ms to complete (Bzzzzt! Wrong. Thanks
for playing...) Since it was an unstructured array of bytes already, it
wasn't too painful to just change its native type to
Ada.Streams.Stream_Element array that cut it to less than 1 ms.

> Maybe my usage of the word is not entirely accurate. "Hard-real-time"
> usually means that failure to meet deadlines constitutes failure of
> the system. If your processor does a gazillion-instructions-per-second
> and you're only using 1% of your CPU, it can still be a
> "hard-real-time" system.

Well, we admitedly do have a bit of headroom, since we are using a PC as
our target. The last CPU utilization numbers I saw were running at about
%35 (Contractually we have to be under %50). Even if we do cut it close,
the march of technology will wipe out most problems. Now they are
ordering them as PIII's, next year, who knows?

> I suppose I was thinking more along the lines of "difficult" real time
> systems. :-)
Well, I don't know if there is a good word for that, but there probably
ought to be. A lot of embedded real-time work is done on older (slower)
microprocessors due to the cost factor.

--
T.E.D.

http://www.telepath.com/~dennison/Ted/TED.html


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Ted Dennison wrote:

> > I suppose I was thinking more along the lines of "difficult" real time
> > systems. :-)
> Well, I don't know if there is a good word for that, but there probably
> ought to be. A lot of embedded real-time work is done on older (slower)
> microprocessors due to the cost factor.
>

A few years back I did a rocket engine job that used a MilStd-1750a. It was
Rad-Hard, bog slow and we were restricted to 64kwords of memory. (Using the
extended address spaces would have only made it slower. We didn't have board
realestate anyway.) By the time we were done with the job, we were upwards
of 93% CPU utilization and we were all sweating bullets that something was
going to drive it over the edge. In that kind of environment, you REALLY get
sensitive to the cost of every little data motion or procedure call
overhead. You get REALLY tricky in what you can coax out of the compiler and
how you can speed up every little operation.

I think so long as we have computers, there will be jobs we want to do with
them that will drive them to their limits. Hence I think we'll always be
worried about the kind of code we get out of enbedded system compilers. Most
apps won't care about the overhead involved with streams - whats a few
hundred milliseconds for an app that wants to load/store its data using
streams or send a message down a TCP/IP pipe across the Internet? But that
isn't the whole universe of applications. :-)

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Brian Orpin wrote:

> I looked at using this for connecting to an RS232 port (PC and Sun
> Box) but failed miserably and have not had time to go back to it.  I
> got some stuff from Marin but never really persued it.  Any tips or
> even code that works <G>.  My biggest problem was that I am fine on 83
> but have not yet got my head around all the 95 stuff.
>

Yeah, there is a lot of "new flavor" to 95 that requires getting your brain
wrapped around it. It can be hard getting used to the inheritance thing and
streams definitely need this understanding.

The trick to streams is understanding that when you derive from the base stream
package, you are creating a Read and Write that explain what to do with arbitrary
bytes as they become available. (Put them in a buffer, feed them to a
communications port, drop them on the floor, whatever.) Then whenever you use the
'Read and 'Write attribute of some type, the compiler figures out how to bust it
up into bytes and send them to the Read and Write you provided. There's obviously
a lot more to know and the Devil is always in the details. But basically, that's
the story.

I may have some code around here that I could trim down into an example. Let me
know if that might help...

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[David Kristola]

On Sat, 18 Nov 2000 5:33:59 -0800, Marin David Condic wrote
(in message <3A168546.89CA38F7@acm.org>):

> I may have some code around here that I could trim down into an example. Let 
> me know if that might help...

It would help me.  I tried playing with streams and ended up writing lots
of code, more than it seemed i should have been writing.  I figure i must
have been doing something wrong if it was that hard to get where i wanted
to be.

--djk, Quadrus Corp. wannabe

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

I'll see what I can do to trim down a small example and post it here.

In the mean time, send me your resume. :-)

MDC


David Kristola wrote:

> On Sat, 18 Nov 2000 5:33:59 -0800, Marin David Condic wrote
> (in message <3A168546.89CA38F7@acm.org>):
>
> > I may have some code around here that I could trim down into an example. Let
> > me know if that might help...
>
> It would help me.  I tried playing with streams and ended up writing lots
> of code, more than it seemed i should have been writing.  I figure i must
> have been doing something wrong if it was that hard to get where i wanted
> to be.
>
> --djk, Quadrus Corp. wannabe

--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Marin David Condic wrote:

> I'll see what I can do to trim down a small example and post it here.

Here's a relatively short example that will compile and run. It doesn't do anything
terribly useful, but you could use it as the basis for playing some games & learning
how it works. For example, you can throw some Text_IO into the code to see when the
Read and Write get called and with what values. You could add a big ring buffer to
the My_Stream_Type and have it store and retrieve values from there - sort of
simulating the existence of a Stream file. Or you could use Text_IO to simulate an
I/O device in some way. You might also try defining your own data type - some sort
of class (record, tagged record, etc.) and fool with overriding the Read and Write.
See what you get with the defaults and see how you might implement your own methods
of getting things into a byte stream.

This will begin to give you a feel for how it works and you'll understand some of
the issues relating to streams better. (Efficiency, representations, etc.) More
questions? Post them here and we'll see if answers come up.

with Ada.Streams ;


package My_Stream is

    type My_Stream_Type is new Ada.Streams.Root_Stream_Type with private ;

    type My_Stream_Ptr is access all Ada.Streams.Root_Stream_Type'Class ;

    --
    --  You need this to get a pointer to the My_Stream object. The
    --  pointer is used in calls such as:
    --  Some_Type'Read (My_Stream_Ptr, My_Object) ;
    --
    procedure Stream (
        My_Stream      : in out My_Stream_Type ;
        Ptr            :    out My_Stream_Ptr) ;

private

    procedure Read (
        Stream  : in out My_Stream_Type ;
        Item    :    out Ada.Streams.Stream_Element_Array ;
        Last    :    out Ada.Streams.Stream_Element_Offset) ;

    procedure Write (
        Stream  : in out My_Stream_Type ;
        Item    : in     Ada.Streams.Stream_Element_Array) ;

    type My_Stream_Type is new Ada.Streams.Root_Stream_Type with record
        --
        --  This is where you would retain information about I/O buffers,
        --  I/O ports, etc. so that Read and Write can know where to
        --  retreive or send their data. A simple case might be a big ring
        --  buffer with Write attaching to the end and Read pulling stuff
        --  off from the beginning. Not really useful, but it makes the
        --  point.
        --
        null ;
    end record ;
    --
end My_Stream ;

package body My_Stream is




    procedure Stream (
        My_Stream      : in out My_Stream_Type ;
        Ptr            :    out My_Stream_Ptr) is
        --
    begin
        Ptr    := My_Stream'Unchecked_Access ;
    end Stream ;



    procedure Read (
        Stream  : in out My_Stream_Type ;
        Item    :    out Ada.Streams.Stream_Element_Array ;
        Last    :    out Ada.Streams.Stream_Element_Offset) is
        --
        --  This is called automagically from the background as things
        --  are being converted by Something'Read.
        --
    begin
        --
        --  Normally, you'd do something to access a low-level I/O
        --  device or use some other means to get hold of raw bytes
        --  from some source at this point in the code. Here we
        --  just fill it with zeros as a not too useful example.
        --
        for X in Item'Range loop
            Item (X) := 0 ;
        end loop ;
        Last    := Item'Last ;
    end Read ;



    procedure Write (
        Stream  : in out My_Stream_Type ;
        Item    : in     Ada.Streams.Stream_Element_Array) is
        --
        --  This is called automagically from the background as things
        --  are being converted by Something'Write.
        --
    begin
       --
       --  This is where you would do something to make the bytes in Item
       --  go out to some low level I/O port or other destination. Here
       --  we basically do nothing for this example.
       --
       for X in Item'Range loop
           null ;    -- Insert your "Write a byte to the I/O port" code here.
       end loop ;
    end Write ;



end My_Stream ;

with My_Stream ;
use My_Stream ;

procedure My_Stream_Driver is
    A_Stream    : My_Stream_Type ;
    A_Ptr       : My_Stream_Ptr ;
    --
    Some_Int    : Integer           := 15 ;
    Some_Float  : Float             := 10.5 ;
    Some_String : String (1..10)    := "XXXXXXXXXX" ;
begin
    Stream (
        My_Stream    => A_Stream,
        Ptr          => A_Ptr) ;
    --
    --  Finds its way to My_Stream.Write with (probably) a 4 byte
    --  Stream_Element_Array.
    --
    Integer'Write (A_Ptr, Some_Int) ;
    --
    --  Goes to My_Stream.Write with how many bytes?
    --
    Float'Write (A_Ptr, Some_Float) ;
    --
    --  This *should* go to My_Stream.Write with 10 bytes.
    --
    String'Write (A_Ptr, Some_String) ;
    --
    --  Read the values in - We get useless values unless
    --  we fill in the My_Stream.Read with something to
    --  get the values from somewhere.
    --
    String'Read (A_Ptr, Some_String) ;
    Float'Read (A_Ptr, Some_Float) ;
    Integer'Read (A_Ptr, Some_Int) ;
    --
end My_Stream_Driver ;
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Brian Orpin]

On Sun, 19 Nov 2000 13:33:51 -0500, Marin David Condic
<mcondic.nospam@acm.org> wrote:

>Marin David Condic wrote:
>
>> I'll see what I can do to trim down a small example and post it here.

<snip>
>    type My_Stream_Type is new Ada.Streams.Root_Stream_Type with record
>        --
>        --  This is where you would retain information about I/O buffers,
>        --  I/O ports, etc. so that Read and Write can know where to
>        --  retreive or send their data. A simple case might be a big ring
>        --  buffer with Write attaching to the end and Read pulling stuff
>        --  off from the beginning. Not really useful, but it makes the
>        --  point.
>        --
>        null ;
>    end record ;

Can't see how information on the IO buffers goes in here.

>    procedure Read (
>        Stream  : in out My_Stream_Type ;
>        Item    :    out Ada.Streams.Stream_Element_Array ;
>        Last    :    out Ada.Streams.Stream_Element_Offset) is
>        --
>        --  This is called automagically from the background as things
>        --  are being converted by Something'Read.
>        --
>    begin
>        --
>        --  Normally, you'd do something to access a low-level I/O
>        --  device or use some other means to get hold of raw bytes
>        --  from some source at this point in the code. Here we
>        --  just fill it with zeros as a not too useful example.
>        --
>        for X in Item'Range loop
>            Item (X) := 0 ;
>        end loop ;
>        Last    := Item'Last ;
>    end Read ;

It is the bit about getting the raw bytes that interested me.  I was
hoping that Streams did a bit more but obviously not.

I just can't believe that someone hasn't done this and made it available.
It is such a common problem.  Ho Hum I suppose I will need to find the
time to do it.

-- 
Brian Orpin    BAE SYSTEMS, Edinburgh
"If you really know C++, there isn't much you can't do with it, though it may 
not always be what you intended!"  Tucker Taft 1998 

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Brian Orpin wrote:

> >    type My_Stream_Type is new Ada.Streams.Root_Stream_Type with record
> >        --
> >        --  This is where you would retain information about I/O buffers,
> >        --  I/O ports, etc. so that Read and Write can know where to
> >        --  retreive or send their data. A simple case might be a big ring
> >        --  buffer with Write attaching to the end and Read pulling stuff
> >        --  off from the beginning. Not really useful, but it makes the
> >        --  point.
> >        --
> >        null ;
> >    end record ;
>
> Can't see how information on the IO buffers goes in here.
>

Suppose for example that you are supporting a MilStd1553 communications device.
Or maybe several of them. There's going to be information here about addresses &
subaddresses which you would store in here via some kind of "Initialize"
procedure that is visible from the spec. The 1553 is likely to have one or more
memory mapped buffers from which it reads a chunk of data and spews it down the
wire. Your code needs to know where those buffers are and probably has to
maintain info about which is the next one to be filling, etc. So you would store
the memory addresses here.

Or you might have an application that uses some other hardware or protocol where
you don't want to send every little byte that comes along, but want to save them
up into some bigger chunk. Declare a local buffer (a Stream_Element_Array) of
some sufficient size along with indexes to know where you left off filling it.
When it gets full, you do the sending of the data at that point.

It depends on your application, but that's generally the way I would use the
Root_Stream_Type for a communication application. I've found other uses for it as
well - it can be used as a means of converting data of some type (tagged records
in particular) into a Stream_Element_Array using the Root_Stream_Type as an
intermediary storage location.

Use your imagination and you may come up with more...


>
> >    procedure Read (
> >        Stream  : in out My_Stream_Type ;
> >        Item    :    out Ada.Streams.Stream_Element_Array ;
> >        Last    :    out Ada.Streams.Stream_Element_Offset) is
> >        --
> >        --  This is called automagically from the background as things
> >        --  are being converted by Something'Read.
> >        --
> >    begin
> >        --
> >        --  Normally, you'd do something to access a low-level I/O
> >        --  device or use some other means to get hold of raw bytes
> >        --  from some source at this point in the code. Here we
> >        --  just fill it with zeros as a not too useful example.
> >        --
> >        for X in Item'Range loop
> >            Item (X) := 0 ;
> >        end loop ;
> >        Last    := Item'Last ;
> >    end Read ;
>
> It is the bit about getting the raw bytes that interested me.  I was
> hoping that Streams did a bit more but obviously not.
>

What did you think they should do? Were you under the impression that Streams
could be informed of the source of some raw bytes and that they would connect up
to it with little or no code provided by the programmer? I'm not clear about what
you are saying here.

>
> I just can't believe that someone hasn't done this and made it available.
> It is such a common problem.  Ho Hum I suppose I will need to find the
> time to do it.

Done what and made it available? I'm lost here.

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Ted Dennison]

Marin David Condic wrote:

> communications port, drop them on the floor, whatever.) Then whenever you use the
> 'Read and 'Write attribute of some type, the compiler figures out how to bust it
> up into bytes and send them to the Read and Write you provided. There's obviously

...unless you have overridden the 'Read and 'Write attributes. In that case *you*
decide how to break the object into stream elements (not *precisely* bytes, but
probably the same in practice).


--
T.E.D.

Home - mailto:dennison@telepath.com  Work - mailto:dennison@ssd.fsi.com
WWW  - http://www.telepath.com/dennison/Ted/TED.html  ICQ  - 10545591

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Ted Dennison wrote:

> ...unless you have overridden the 'Read and 'Write attributes. In that case *you*
> decide how to break the object into stream elements (not *precisely* bytes, but
> probably the same in practice).
>

Berzactly!!!

And *then* you start getting into the Deviled-Details. For most of your primitive and
compound types, you may be all right to accept whatever the compiler does for 'Read and
'Write - except that you get no guarantees of representation - which can be a *real
bitch!* if you have to pass stuff down a wire to some unknown listener who is expecting
things to occupy precise positions within the stream. It works O.K. if you're going to
create a stream file and read it back in later with the same program - then you don't
really care - maybe. (Useful for building something like the "Serialize" functions in
MFC/C++)

Or you can take your compound types and do some intensive representation control and
through some reliable mechanism (overlays, for example) convert them to a
Stream_Element_Array and now they go down the hose the way you want them to. Unless, of
course, it is a tagged record type and then you open up all sorts of cans of worms
concerning representation. To get around that, there are techniques, but you then have
to *continually* write your own overrides for every child type instead of having a
single class-wide operation: Some_Type'Class'Write - which would be really cool to have
if you could make it work.

For some things, just accepting what the compiler gives you is a pretty good choice. If
your working only internal to a single program, or the communications are between two
programs compiled by the same compiler for the same OS and same machine, then whatever
the compiler generates is probably going to work OK - for a while - until someone makes
a mess of it by changing compiler versions or using your data for some third system,
etc. In my experience, the minute you start broadcasting data to another system, you
had better get good control of the representation or you'll really hate yourself later.

And the instant you have to write code that deals with someone else's defined flow of
data, you can just bag the whole thing if you don't want to get outside the default
'Read.

It is *almost* a really wonderful thing to have Streams. :-)

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Robert Dewar]

In article <3A182633.BDE82EA9@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:
> Ted Dennison wrote:

> And *then* you start getting into the Deviled-Details. For
> most of your primitive and compound types, you may be all
> right to accept whatever the compiler does for 'Read and
> 'Write - except that you get no guarantees of representation -
> which can be a *real bitch!* if you have to pass stuff down a
> wire to some unknown listener who is expecting
> things to occupy precise positions within the stream.

Well I find that a little pessimistic. The representation
of primitive items should be governed by the IA in the RM

17   If a stream element is the same size as a storage element,
then the normal in-memory representation should be used by Read
and Write for scalar objects.  Otherwise, Read and Write should
use the smallest number of stream elements needed to represent
all values in the base range of the scalar type.

Note that in all implementations in normal use the predicate
at the start of this paragraph is true.

There is a bit of a puzzle about base types, but that is
compeltely resolved by a recent AI (GNAT incidentally is
already conforming to the recommendations of this AI, and
always has).

As for compound types, the RM requires that these be output
as a sequence of stream elements for the primitive components,
recursively, so this is 100% well defined.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Randy Brukardt]

Robert Dewar wrote in message <8v9lip$2dr$1@nnrp1.deja.com>...
>In article <3A182633.BDE82EA9@acm.org>,

>There is a bit of a puzzle about base types, but that is
>compeltely resolved by a recent AI (GNAT incidentally is
>already conforming to the recommendations of this AI, and
>always has).

My, GNAT is implemented in a hurry. We just approved the intent of this
AI (AI-195) during the Sunday session of the recent ARG meeting, roughly
4 hours before Robert sent his message. And Tucker didn't even finish
the proposal until Wednesday night. It is amazing how fast GNAT is
implemented.  :-) :-)

Seriously, the AI in question is not (finally) approved and still needs
more work. So I think claiming to conform to it is premature.
(Importantly, the base type problem means that streams may not be
portable between different Ada compilers on the same machine. Even if
GNAT is following the AI proposal, there is no requirement that other
compilers do so until the AI is completed.... Caveat empor.)

                Randy Brukardt (ARG Editor)

Re: Ada Streams usage (was Escape Sequences in Strings)

[Ted Dennison]

In article <rAjS5.627$aX.271957@homer.alpha.net>,
  "Randy Brukardt" <randy@rrsoftware.com> wrote:
> (Importantly, the base type problem means that streams may not be
> portable between different Ada compilers on the same machine. Even if
> GNAT is following the AI proposal, there is no requirement that other
> compilers do so until the AI is completed.... Caveat empor.)

That *still* won't make streams compatable between diferent compilers
though, will it? Isn't the representation of a tagged type's tag on
'output implementation defined? You can of course specify it. But you'd
have to know ahead of time that you want to use streams portably with
your objects, then go in and specify the external tag for every object.

--
T.E.D.

http://www.telepath.com/~dennison/Ted/TED.html


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Randy Brukardt]

Ted Dennison wrote in message <8ves0e$a0m$1@nnrp1.deja.com>...
>In article <rAjS5.627$aX.271957@homer.alpha.net>,
>  "Randy Brukardt" <randy@rrsoftware.com> wrote:
>> (Importantly, the base type problem means that streams may not be
>> portable between different Ada compilers on the same machine. Even if
>> GNAT is following the AI proposal, there is no requirement that other
>> compilers do so until the AI is completed.... Caveat empor.)
>
>That *still* won't make streams compatable between diferent compilers
>though, will it? Isn't the representation of a tagged type's tag on
>'output implementation defined? You can of course specify it. But you'd
>have to know ahead of time that you want to use streams portably with
>your objects, then go in and specify the external tag for every object.

Yes, for tagged types, you have to specify the external tag for every
tagged type. I doubt anything will change there soon (could be wrong,
though). I was thinking more about reading an untagged object from a
stream. We ran into this problem trying to read Windows bitmaps from a
stream (given that it is hetrogeneous, we pretty much have to use
streams to do it); this isn't a tagged type (we do put the data into a
tagged object after reading it, but it isn't read as one). We had quite
a time getting all of the supported compilers to do it right.

            Randy Brukardt.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Robert Dewar]

In article <rAjS5.627$aX.271957@homer.alpha.net>,
  "Randy Brukardt" <randy@rrsoftware.com> wrote:
> Seriously, the AI in question is not (finally) approved and
> still needs more work. So I think claiming to conform to it is
> premature.

I disagree, the "more work" that Randy refers to is the usual
fiddling with language. The basic (and to me very obvious)
conclusion of how the technical issue should be resolved was
never in dispute, and as I said earlier, GNAT always took the
position (use the representation of the base type) that the
AI recommends. To me, any other choice was a clear mistake
precisely because it introduces worrisome non-portability.

Of course it will indeed be some time before all compilers
are conformant to the AI. But I never claimed otherwise.

I just wanted to reassure anyone using GNAT that no change in
the implementation is required or expected as a result of the
AI, whatever state of word-smithing it is in.

Robert Dewar


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Robert Dewar]

In article <rAjS5.627$aX.271957@homer.alpha.net>,
  "Randy Brukardt" <randy@rrsoftware.com> wrote:
> (Importantly, the base type problem means that streams may not
> be portable between different Ada compilers on the same
> machine. Even if GNAT is following the AI proposal, there is
> no requirement that other compilers do so until the AI is
> completed.... Caveat empor.)

Wait a moment, there is no requirement on compilers to use any
particular representation for stream elements in the first
place. This is all implementation advice, and compilers may
after all choose different representations for the base type.
This has very little to do with streams being portable between
Ada compilers, since there is no guarantee in any case. If you
want portable streams in this sense, write your own stream
routines!


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Randy Brukardt]

Robert Dewar wrote in message <8vcjcc$e09$1@nnrp1.deja.com>...
>In article <rAjS5.627$aX.271957@homer.alpha.net>,
>  "Randy Brukardt" <randy@rrsoftware.com> wrote:
>> (Importantly, the base type problem means that streams may not
>> be portable between different Ada compilers on the same
>> machine. Even if GNAT is following the AI proposal, there is
>> no requirement that other compilers do so until the AI is
>> completed.... Caveat empor.)

>Wait a moment, there is no requirement on compilers to use any
>particular representation for stream elements in the first
>place. This is all implementation advice, and compilers may
>after all choose different representations for the base type.

True enough, but the point of the AI is to introduce a specifiable
attribute to provide some control over this. Which is enough for most
applications (of course, hetrogeneous networks need to go beyond what
the language can provide). I suspect that you are thinking about the
recommendations about the default base type representation (which GNAT
indeed always has supported), but the AI goes beyond that (and indeed it
was always intended that it would do so, it's just been waiting for
Tucker to write the proposal up).

            Randy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Robert Dewar]

In article <MvCS5.758$aX.307819@homer.alpha.net>,
  "Randy Brukardt" <randy@rrsoftware.com> wrote:
> but the AI goes beyond that (and indeed it
> was always intended that it would do so, it's just been
waiting for
> Tucker to write the proposal up).


Right I know, the ARG loves to invent complex solutions for
problems that don't really need a solution at all :-)


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Marin David Condic]

Robert Dewar wrote:

> Well I find that a little pessimistic. The representation
> of primitive items should be governed by the IA in the RM
>
> 17   If a stream element is the same size as a storage element,
> then the normal in-memory representation should be used by Read
> and Write for scalar objects.  Otherwise, Read and Write should
> use the smallest number of stream elements needed to represent
> all values in the base range of the scalar type.
>

Which is fine - right up to the point where something in the message
stream doesn't exactly line right up on an even byte boundary. Don't
tell me that never happens, because it does. Please don't say "thats a
bad protocol" because it doesn't matter when you're trying to
communicate with some piece of avionics that is 20 years old and you
can't redesign the protocol that came with it. Its stuff like this that
means I have to have 100% absolute total control over the exact and
precise representation of the data right down to the bit level. I can't
do that with streams as easily as I would like.

Yes, I can find ways to "cheat" and get things to work. I've been doing
that sort of cheating professionally for a number of years now. :-) Its
just that I don't end up with as clean and elegant an answer as I would
like. I don't think it is a "frundamental" flaw in the language - it
might be fixable with a few pragmas.

>
> Note that in all implementations in normal use the predicate
> at the start of this paragraph is true.
>
> There is a bit of a puzzle about base types, but that is
> compeltely resolved by a recent AI (GNAT incidentally is
> already conforming to the recommendations of this AI, and
> always has).
>
> As for compound types, the RM requires that these be output
> as a sequence of stream elements for the primitive components,
> recursively, so this is 100% well defined.

"Well Defined" is not the same thing as "Useful". I'm sure you
understand that. The "recursive" nature of this poses a problem in terms
of efficiency - it can (and does in the tests I've run) degenerate to a
whole bunch of really small procedure calls. It also doesn't necessarily
guarantee what I'm going to get if I have spanned data across byte
boundaries or figured out other ways of making my life difficult. :-)

I may get a guarantee of a certain behavior. It just doesn't guarantee
the behavior I want.

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Ada Streams usage (was Escape Sequences in Strings)

[Robert Dewar]

In article <3A1939E1.AA643766@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:
> Which is fine - right up to the point where something in the
> message stream doesn't exactly line right up on an even byte
> boundary. Don't tell me that never happens, because it does.

So -- write your own stream protocols to handle this. I really
do not understand what you are grumbling about here. Obviously
different apps will have different data representation
requirements, which is why we leave data representation in
streams under program control. Yes, there is a default that
will be useful to many people, No, this default is not always
what you want. If the default is not what you want, do not use
it. Seems pretty straightforward to me.

You could argue for a different default (for example in GNAT,
we provide two different defaults), or a mechanism for more
easily selecting among defaults (that's a planned GNAT
enhancement), but other than that, I see no useful input here.



Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada Streams usage (was Escape Sequences in Strings)

[Ted Dennison]

Marin David Condic wrote:

> It is *almost* a really wonderful thing to have Streams. :-)

That just about says it all in one sentence.

--
T.E.D.

Home - mailto:dennison@telepath.com  Work - mailto:dennison@ssd.fsi.com
WWW  - http://www.telepath.com/dennison/Ted/TED.html  ICQ  - 10545591

Re: Ada Streams usage (was Escape Sequences in Strings)

[Robert Dewar]

In article <3A17C7AA.84445608@telepath.com>,
  Ted Dennison <dennison@telepath.com> wrote:
> Marin David Condic wrote:
>
> > It is *almost* a really wonderful thing to have Streams. :-)

> That just about says it all in one sentence.

I must say I find the attitude that streams are not quite what
you want because the representations are not well defined to
be a bit peculiar. The language has NEVER been in the business
of defining default representations. If you want a particular
representation, you need to say so.

Note that for people who *really* *do* want a completely well
defined target-independent stream representation standard, the
XDR package in GLADE provides exactly this for Ada 95 streams.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Escape Sequences in Strings

[Andrew Hately]

Jean Cohen wrote:
> 
> I'm quite new to Ada and consider a transition from C++

Welcome. Its very hard to go back.
 
> As you all certainly know it is quite easy and 
> straightforward in C++ to set cursor positions,
> the format (tabulators, newlines etc.) of a string etc. by using escape
> sequences.

IMHO Ada is easier and more straight forward.
See section A.10 of the Ada Reference manual. "Text Input-Output"
especially A.10.5 "Operations on Columns, Lines and Pages"

Andrew Hately
shameless plug: http://www.ada-europe.org/conference2001.html

Re: Escape Sequences in Strings

[Keith Thompson]

Andrew Hately <hat@cfmu.eurocontrol.be> writes:
> Jean Cohen wrote:
[...]
> > As you all certainly know it is quite easy and 
> > straightforward in C++ to set cursor positions,
> > the format (tabulators, newlines etc.) of a string etc. by using escape
> > sequences.
> 
> IMHO Ada is easier and more straight forward.
> See section A.10 of the Ada Reference manual. "Text Input-Output"
> especially A.10.5 "Operations on Columns, Lines and Pages"

It depends on what you're trying to do.  If you want to do things like
moving the cursor to a specified position on the screen, neither C++
nor Ada helps you much unless you use a library designed for the
purpose (curses, ncurses, terminfo, termcap).  Ada's New_Page
procedure doesn't necessarily perform any specific action if you're
writing to a terminal; the only thing really guaranteed is that if
you're writing to a file, it writes something that will be recognized
as a page break when the file is read using Ada.Text_IO.

-- 
Keith Thompson (The_Other_Keith) kst@cts.com  <http://www.ghoti.net/~kst>
San Diego Supercomputer Center           <*>  <http://www.sdsc.edu/~kst>
MAKE MONEY FAST!!  DON'T FEED IT!!

Re: Escape Sequences in Strings

[Lao Xiao Hai]

Instead of moving the cursor using Text_IO, I have seen a very interesting
Ada program written by a Japanese programmer that used the low-level
features of the language to directly reference Address Location
Hexadecimal B800 to manipulate the screen mappings.  This turns out
to be quite easy with Ada.   And it is really fast if you are doing high-speed
game programming.  No ESC sequences required.

Richard Riehle

-------------------------------------------------------------------------------------

Keith Thompson wrote:

> Andrew Hately <hat@cfmu.eurocontrol.be> writes:
> > Jean Cohen wrote:
> [...]
> > > As you all certainly know it is quite easy and
> > > straightforward in C++ to set cursor positions,
> > > the format (tabulators, newlines etc.) of a string etc. by using escape
> > > sequences.
> >
> > IMHO Ada is easier and more straight forward.
> > See section A.10 of the Ada Reference manual. "Text Input-Output"
> > especially A.10.5 "Operations on Columns, Lines and Pages"
>
> It depends on what you're trying to do.  If you want to do things like
> moving the cursor to a specified position on the screen, neither C++
> nor Ada helps you much unless you use a library designed for the
> purpose (curses, ncurses, terminfo, termcap).  Ada's New_Page
> procedure doesn't necessarily perform any specific action if you're
> writing to a terminal; the only thing really guaranteed is that if
> you're writing to a file, it writes something that will be recognized
> as a page break when the file is read using Ada.Text_IO.
>
> --
> Keith Thompson (The_Other_Keith) kst@cts.com  <http://www.ghoti.net/~kst>
> San Diego Supercomputer Center           <*>  <http://www.sdsc.edu/~kst>
> MAKE MONEY FAST!!  DON'T FEED IT!!

Re: Escape Sequences in Strings

[Robert Dewar]

In article <3A66A95F.61C03A3B@ix.netcom.com>,
  Lao Xiao Hai <laoxhai@ix.netcom.com> wrote:
> Instead of moving the cursor using Text_IO, I have seen a
very interesting
> Ada program written by a Japanese programmer that used the
low-level
> features of the language to directly reference Address
Location
> Hexadecimal B800 to manipulate the screen mappings.  This
turns out
> to be quite easy with Ada.   And it is really fast if you are
doing high-speed
> game programming.  No ESC sequences required.


Ummm yes, well if you are running a 16-bit DOS environment,
and all you want is super low resolution character output,
but this is definitely a gasp-from-the-past

(by the way, this is not somehow some secret programming trick
known only to obscure Japanese programmers, it was absolutely
standard in early DOS days). Of course very few Ada compilers
ever operated in this kind of environment (RR and Janus only)


Sent via Deja.com
http://www.deja.com/

Re: Escape Sequences in Strings

[Randy Brukardt]

Robert Dewar wrote in message <9471mj$8a5$1@nnrp1.deja.com>...
>Ummm yes, well if you are running a 16-bit DOS environment,
>and all you want is super low resolution character output,
>but this is definitely a gasp-from-the-past
>
>(by the way, this is not somehow some secret programming trick
>known only to obscure Japanese programmers, it was absolutely
>standard in early DOS days). Of course very few Ada compilers
>ever operated in this kind of environment (RR and Janus only)


Robert is right: it's hardly an obscure trick. The "Windows" package
that someone donated to our public software archive in 1983 worked this
way. More recently, the DOS version of the "JWindows" packages also used
direct hardware access. ("JWindows" also supported "high resolution"
graphics screens (i.e. VGA) with 50-line windows.)

But none of that works on Windows NT or 2000, and most of it only works
in DOS mode on Windows 95 or 98, making it too obnoxious to use even on
those systems.

                Randy.

Re: Escape Sequences in Strings

[Dale Stanbrough]

Robert Dewar wrote:

>  Of course very few Ada compilers
> ever operated in this kind of environment (RR and Janus only)


The Meridian Ada compiler also did this.
I wrote a package that did a similar thing to allow for various
screen based output routines using this compiler.

Dale

directly accessing DOS screen memory (was: Re: Escape Sequences in Strings)

[Jeffrey Carter]

I used a similar technique to write a VGA graphics driver using the
Meridian Ada compiler.

-- 
Jeff Carter
"English bed-wetting types."
Monty Python & the Holy Grail

Re: Escape Sequences in Strings

[tmoran]

> straightforward in C++ to set cursor positions,
> the format (tabulators, newlines etc.) of a string etc. by using escape
> sequences.
  Ada.Text_IO.Put(ascii.esc & "[0p");
(My memory of these is hazy so that particular example may make no sense.)
  A better way is to define routines to clear the screen, set position,
etc.  Check:
http://www.seas.gwu.edu/faculty/mfeldman/papers/portable-diners.html

Re: Escape Sequences in Strings

[Robert Dewar]

In article
<e2J76.118602$A06.3833145@news1.frmt1.sfba.home.com>,
  tmoran@acm.org wrote:

>   Ada.Text_IO.Put(ascii.esc & "[0p");

If I saw this in code, I would be unhappy. Mysterious constants
have no place appearing like this. Better style is

  Home_Cursor constant String := Ascii.ESC & "[0p";
  --  Sequence for homing cursor

  Ada.Text_IO.Put (Home_Cursor & "hello there!");

Note that Ada requires that the concatenation be done at
compile time, so no inefficiency is involved.

Note: I don;t know if this is the home cursor command, I
just use this for illustrating the style.


Sent via Deja.com
http://www.deja.com/

Re: Escape Sequences in Strings

[tmoran]

In article
<93objj$guk$1@nnrp1.deja.com>,
  robert_dewar@my-deja.com wrote:

>   Ada.Text_IO.Put (Home_Cursor & "hello there!");

If I saw this in real code, I would be unhappy.  It assumes
a) that cursor positioning is done by sending a special string,
b) that this greeting string should always be placed at cursor home position,
c) that the string will always be "hello there!".
  A more thorough application of information hiding would have a
low level routine "Home_Cursor" used by a mid-level routine
"Move_To_Greeting_Field" which would be followed by output of
a Greeting string from a set of message string constants.

Re: Escape Sequences in Strings

[Robert Dewar]

In article
<ZSS76.120778$A06.3893142@news1.frmt1.sfba.home.com>,
  tmoran@acm.org wrote:
> In article
> <93objj$guk$1@nnrp1.deja.com>,
>   robert_dewar@my-deja.com wrote:
>
> >   Ada.Text_IO.Put (Home_Cursor & "hello there!");

You are completely (perhaps deliberately? :-) misreading
what I wrote. I was just reacting to your code that embedded
a peculiar constant string, and using the above statement to
illustrate that if you do want to send strange strings to
Put, they should be sent using named constants, that's all!

> If I saw this in real code, I would be unhappy.  It assumes:

> a) that cursor positioning is done by sending a special
> string

Yes, indeed it assumes that, and that is true at the lowest
level in some systems, so at the lowest level, you will see
code like this.

> b) that this greeting string should always be placed at
> cursor home position

Sure, that is the assumption in the example, if it is not true
of your case, you have to change the example.

> c) that the string will always be "hello there!".

Sure, that is the assumption in the example, if it is not true
of your case, you have to change the example.

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 :-)

> A more thorough application of information hiding would
> have a low level routine "Home_Cursor"

I was of course just showing the kind of code that might
appear in low level routines.

> used by a mid-level
> routine "Move_To_Greeting_Field" which would be followed by
> output of a Greeting string from a set of message string
> constants.

Well such a structure might be appropriate depending on the
application. If the program at hand has the following spec,
as a homework assignment might:

Print "hello there!" at the home position on your screen,

then this amount of structure would be overkill. You do
sometimes see students doing this kind of thing (making
mountains out of molehills :-)

But Tom, the real point that I was making is that REGARDLESS
of the structure or requirements of your program, NEVER EVER
put junk constants in the code, that was the ONLY point I was
making, I was not writing a treatise on how to do the abstract
top down structure of a program that puts information on the
screen.

I really think it is bad practice to EVER write even example
code that has junk constants in it, as your example did. Yes,
it is easy to do when we are being lazy, but it sets a bad
example (I certainly have done this in examples in the past,
if you go through my own posts, but that does not make it
right).

I find all the time that people put junk constants in code.

MINIMAL (the language which I designed solely for the purpose
of writing one program, namely MACRO-SPITBOL) is the only
language I know that completely forbids constants except in
constant declarations.

That's a little fierce, because constants like 1 and 0, and
perhaps 2 can reasonably appear in that form, and it is also
OK to use constants which are fudnamental to the problem in
some cases e.g. 7 for days of the week, but even there naming
the 7 as Days_Per_Week can clarify code.


Sent via Deja.com
http://www.deja.com/

Examples in Docs, was Re: Escape Sequences in Strings

[peter_richtmyer]

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/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article <940f9j$nj2$1@nnrp1.deja.com>,
  peter_richtmyer@my-deja.com wrote:
> 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.

Be careful to note that I was just expressing my
own personal viewpoint. As I said, and as I say
in what is quoted above, I quite understand that
most people *do* like examples, and indeed many
people find it very difficult to read language
rules without examples. So I am all in favor of
providing examples, and you will see loads of
examples in the GNAT documentation (particularly
in the specs of the GNAT.xxx library).

Note however, that there is a danger which is
to let examples take the place of thorough
rules. Some people seem to think they can
replace full semantic descriptions by examples,
and *that* is surely a mistake.

> 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.

I am not sure there is really any specific connection
between examples in documents and comments in code.
Comments in code are descriptions of what the code
does and why and how it does it. Examples may be
often be useful in this connection if some obscure
piece of code in GNAT for instance is to handle some
particular obscure use of the language, it is often
helpful to readers to provide examples.

Going back to my original comment, I again stress that
I perfectly well understand that my taste is not typical
here. I doubt there are many people who learned COBOL
from the ANSI standard (as I did :-)

> But then, I have written documents that I thought
> were pretty clear, only to find that others
> needed examples to understand them.

Yes, as I say, many people *do* need examples. However,
there is a danger that there understanding is limited to
the examples, and is not comprehensive. Actually there are
few programmers who really thoroughly know the semantics
of the language they are using.

> But code and
> documents should be written for the reader.
> (Yes, I know that that is not an original thought
> on my part). :-)

The right way to look at comments in code is to
think of it as a text book, and yes, of course
comments are written for the user. If something
is not clear in the code, there is a bug in the
comments and it needs to be fixed, and it is the
reader not the writer who is the arbiter of what
is clear.

We always encourage new people coming into the
GNAT project to make comments on what was NOT
clear to them in the code, since they have a
fresh eye and a more useful perspective in some
respects.

I don't think we really disagree on anything
here (though we may have personally different
tastes with respect to language definitions :-)


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[mark_lundquist]

In article <940n0u$tnf$1@nnrp1.deja.com>,
  Robert Dewar <robert_dewar@my-deja.com> wrote:

>
> I am not sure there is really any specific connection
> between examples in documents and comments in code.

Not a connection, an analogy.  With respect to the function of a
program, comments are superfluous; with respect to the language
definition, examples are superfluous.  But of course the purpose of a
program and the purpose of a language definition are not the same :-)

>
> Going back to my original comment, I again stress that
> I perfectly well understand that my taste is not typical
> here. I doubt there are many people who learned COBOL
> from the ANSI standard (as I did :-)

You're probably right, not many... :-)

Wanting examples in the RM is absurd because it's to say "I want to
learn the language from the definition", then to turn around and say "I
don't like this standard, it doesn't have enough examples for me to
learn the language from"!  You want to learn it from the LRM, fair
enough, but then you have take it on its own terms, i.e. a definition
w/o the redundant bloat of examples!

> [...] Actually there are
> few programmers who really thoroughly know the semantics
> of the language they are using.
>

To digress... :-)

Although I've used C++, I don't really know it, and my study of it
impressed me that to really understand C++ requires more intelligence
than I'm possessed of -- or at least, more brain cells than I could
spare to devote to the task.  It seems like in order to do even
fundamental things reasonably well in C++, you have to wrap your brain
around all kinds of deep and intertwined details about the meanings of
references, const, temporaries, construction and destruction in
general, copy constructors in particular, etc., etc.  Maybe it's just
me and I have yet to get "closure" on it in a way that all those
details can stay with me.  Maybe Ada's the same way and I'm just no
longer aware of it.  Maybe the vast ocean of C++ programmers really
*are* that much smarter than me...



Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Larry Kilgallen]

In article <942brr$b0t$1@nnrp1.deja.com>, mark_lundquist@my-deja.com writes:

> longer aware of it.  Maybe the vast ocean of C++ programmers really
> *are* that much smarter than me...

Not in language preference :-)

Certainly there are going to be programming tasks where C++ is ideal,
but current usage of compilers labeled C++ is out of proportion to
that small subset.

Re: Examples in Docs, was Re: Escape Sequences in Strings

[mark_lundquist]

In article <gOg7My9dEks+@eisner.decus.org>,
  Kilgallen@eisner.decus.org.nospam (Larry Kilgallen) wrote:
> In article <942brr$b0t$1@nnrp1.deja.com>, mark_lundquist@my-deja.com
writes:
>
> > longer aware of it.  Maybe the vast ocean of C++ programmers really
> > *are* that much smarter than me...
>
> Not in language preference :-)

Well that's something, anyway...

Uh, thanks Larry!
:-) :-) :-)


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article <942brr$b0t$1@nnrp1.deja.com>,
  mark_lundquist@my-deja.com wrote:

> Not a connection, an analogy.  With respect to the function
> of a program, comments are superfluous; with respect to the
> language definition, examples are superfluous.

I disagree strongly with this analogy.

In the case of a language definition, examples indeed convey
no information that cannot be derived from the definition
proper (unless the definition is incomplete). Yes, they may
be helpful in understanding, but they do not have any
non-derivable information.

With comments in a program, the situation is quite different.
Yes, they do not provide any additional information with regard
to what the program does at the implementation loevel, but
*that is NOT the purpose of comments*. The purpose of comments
is to explain what the code is doing at a higher level of
abstraction, and much more importantly WHY it is doing it that
way (and in some cases, very importantly why it is NOT doing it
some other way). You cannot even derive the specification of a
program from the implementation (since the code typically
embodies an over-specification). You for SURE cannot derive the
motivation and high level abstract design from the code.

Indeed if you write comments that CAN be derived from the code,
as in:

   a := a + 1;   -- increment a

then you have written a junk, completely useless comment.
Indeed I would say that comments like this are what are
analogous to examples in programming language definitions :-)


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[mark_lundquist]

We're in violent agreement :-)

Note how the analogy has to be set up so narrowly to remain valid, that
it ends up being useless.

Most analogies are useless anyway :-)... They're only helpful when
there's an underlying principle to illustrate that doesn't depend on
the analogy, and the illustration is strong enough not to be
compromised by the inevitable flaws of the analogy.

Reasoning by analogy was a hallmark of Midieval thought -- analogies
were advanced and accepted as proofs.

Analogies can still be a very useful creative thinking tool, though.

This is so pathetically OT, I will stop now :-)



Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Brian Rogoff]

On Wed, 17 Jan 2001, Robert Dewar wrote:
> In article <942brr$b0t$1@nnrp1.deja.com>,
>   mark_lundquist@my-deja.com wrote:
> 
> > Not a connection, an analogy.  With respect to the function
> > of a program, comments are superfluous; with respect to the
> > language definition, examples are superfluous.
> 
> I disagree strongly with this analogy.
> 
> In the case of a language definition, examples indeed convey
> no information that cannot be derived from the definition
> proper (unless the definition is incomplete). Yes, they may
> be helpful in understanding, but they do not have any
> non-derivable information.
[...snip...]
> Indeed if you write comments that CAN be derived from the code,
> as in:
> 
>    a := a + 1;   -- increment a
> 
> then you have written a junk, completely useless comment.
> Indeed I would say that comments like this are what are
> analogous to examples in programming language definitions :-)

I wonder if you learned SML programming from "The Definition of Standard
ML" :-). 

Seriously, I'm pretty amazed that anyone can learn to program from a 
typical language spec without examples. Do you think it is a learnable 
and teachable skill (do you teach your students this?), or is it a 
unique quirk?

-- Brian

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Wayne Lydecker]

Personally, I'd like to have a book that was nothing but examples.
When coding, especially in a language new to me, I search for code
similar to what I need to do and modify it for my usage.  A book of
examples would allow me to find templates to use.  Ada is not one
of the easier languages to learn and it has gotten more complex in
'95.  Reading the LRM does not make it easier to understand.  BTW,
can someone tell me exactly what "abstract tagged limited private"
or "abstract tagged limited null record" means?  How about some
examples instead?

-- Wayne.

Brian Rogoff wrote:
> 
> I wonder if you learned SML programming from "The Definition of Standard
> ML" :-).
> 
> Seriously, I'm pretty amazed that anyone can learn to program from a
> typical language spec without examples. Do you think it is a learnable
> and teachable skill (do you teach your students this?), or is it a
> unique quirk?
> 
> -- Brian

Re: Examples in Docs, was Re: Escape Sequences in Strings

[BSCrawford]

Wayne Lydecker said, in part,

>Personally, I'd like to have a book that was nothing but examples.
>When coding, especially in a language new to me, I search for code
>similar to what I need to do and modify it for my usage.  A book of
>examples would allow me to find templates to use.

My book may help.  It's not exactly "nothing but examples" but 
it has lots of examples, and the Glossary/Index makes it easy to 
find them. 

Bard S. Crawford, 
  Author of "Ada Essentials: Overview, Examples and Glossary," 
  a compact volume available in three forms: printed book, pdf 
  file, and a collection of browser-based web pages.  See
http://www.learnada.com  
-----------------------
Stage Harbor Software
9 Patriots Drive - Lexington, MA - 02420 USA
bard@learnada.com - 781-862-3613

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Jerry Petrey]

BSCrawford wrote:
> 
> Wayne Lydecker said, in part,
> 
> >Personally, I'd like to have a book that was nothing but examples.
> >When coding, especially in a language new to me, I search for code
> >similar to what I need to do and modify it for my usage.  A book of
> >examples would allow me to find templates to use.
> 
> My book may help.  It's not exactly "nothing but examples" but
> it has lots of examples, and the Glossary/Index makes it easy to
> find them.
> 
> Bard S. Crawford,
>   Author of "Ada Essentials: Overview, Examples and Glossary,"
>   a compact volume available in three forms: printed book, pdf
>   file, and a collection of browser-based web pages.  See
> http://www.learnada.com
> -----------------------
> Stage Harbor Software
> 9 Patriots Drive - Lexington, MA - 02420 USA
> bard@learnada.com - 781-862-3613

I concur.  "Ada Essentials: Overview, Examples and Glossary" is indeed
a very good, concise book for learning Ada.

Well done Brad!

Jerry
-- 
-----------------------------------------------------------------------------
-- Jerry Petrey                                                
-- Senior Principal Systems Engineer - Navigation, Guidance, & Control
-- Raytheon Missile Systems          - Member Team Ada & Team Forth
-- NOTE: please remove <NOSPAM> in email address to
reply                  
-----------------------------------------------------------------------------

Re: Examples in Docs, was Re: Escape Sequences in Strings

[tmoran]

>can someone tell me exactly what "abstract tagged limited private"
>or "abstract tagged limited null record" means?  How about some
>examples instead?
  There are several good Ada texts that talk about these things.
If one book is unclear to you, another may explain it better.

Roughly:
  "tagged" I can't explain in a short newsgroup post.

  "abstract" means it's sort of a placeholder.  You can't actually declare
an object of the type, but you can declare derived types and declare
objects of those derived types.  In Claw (Class library for Ada on Windows)
for instance, Root_Tool_Type is abstract with a private, non-null, record.
It has children like Brush_Type and Pen_Type (the Windows "tools").  You
can't create an object of Root_Tool_Type, but you can create an object of
Brush_Type, Pen_Type, etc.  The (private) record for Root_Tool_Type
contains stuff, like a Windows handle, that all tools have, while the
particular tools like Brushes and Pens contain additional information
specific to that kind of tool.  Some operations exist only for Brushes,
others only for Pens, etc, but some exist for any tool, eg
    function Is_Attached (Tool : in Root_Tool_Type'Class) return Boolean;

  "limited" means you can't make copies.  Claw.Sockets.Root_Socket_Type
is limited, for instance.  Life gets complicated if you allow:
  A,B : Socket_Type;
  ...
  Open(A, "1.2.3.4");
  B := A;   -- is B now a synonym for A or a second socket also
            -- connected to 1.2.3.4?
  Close(A);
  -- Is B still open?
(similarly for any "handle" type of thing).  If the type is "limited",
the compiler will point out that "B := A;" is not allowed.

  "private" in "abstract tagged limited private" just means "there's some
data associated with this, but it's none of your business."  The actual
record specification comes in the private portion of the package spec.
"null record" means "there's no actual data associated with this".  So the
Root_Tool_Type (above) uses "private" and the actual data includes the
Windows handle for the tool.  That's private because the application
program shouldn't be playing with the Windows tool handle directly while
leaving Claw in the dark about the status of the tool handle.

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article
<Pine.BSF.4.21.0101170815001.21897-100000@shell5.ba.best.com>,
  Brian Rogoff <bpr@shell5.ba.best.com> wrote:
> I wonder if you learned SML programming from "The Definition
> of Standard ML" :-).

Yes, it's the only document I ever read to learn ML.

> Seriously, I'm pretty amazed that anyone can learn to program
> from a  typical language spec without examples. Do you think
> it is a learnable  and teachable skill (do you teach your
> students this?), or is it a unique quirk?

Well certainly it helps to have a lot of experience in looking
at different language designs.

I don't think it is a quirk by any means. After all a
mathematician does not need examples of what a proof is
talking about.

Examples can never tell you what the general rules are, they
can only illustrate particular cases, and therefore there is
a danger of not understanding the generalization.

Certainly a BNF grammar is a FAR clearer documentation of
syntax than syntactic examples, wouldn't you agree?


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Brian Rogoff]

On Thu, 18 Jan 2001, Robert Dewar wrote:
> In article
> <Pine.BSF.4.21.0101170815001.21897-100000@shell5.ba.best.com>,
>   Brian Rogoff <bpr@shell5.ba.best.com> wrote:
> > I wonder if you learned SML programming from "The Definition
> > of Standard ML" :-).
> 
> Yes, it's the only document I ever read to learn ML.

Well, I am in awe. If I remember correctly, there are a few important
aspects of SML programming, like evaluation order, that are not
explicitly stated but have to be deduced. I can't imagine anyone getting a 
feel for how to program in ML from the definition, especially if they were 
not familiar with functional programming style.  

> > Seriously, I'm pretty amazed that anyone can learn to program
> > from a  typical language spec without examples. Do you think
> > it is a learnable  and teachable skill (do you teach your
> > students this?), or is it a unique quirk?
> 
> Well certainly it helps to have a lot of experience in looking
> at different language designs.

When you started your career as a language researcher, did you learn from 
language specs? I realize that this is a bit off topic for the ng, but I 
can always find a way to relate it to Ada :-) if people complain. 

> I don't think it is a quirk by any means. After all a
> mathematician does not need examples of what a proof is
> talking about.

I agree, but I think mathematics is quite a bit different from
programming, and I have a decent background in both. (Note to 
RBKD: that's why I chose SML as an example, since it's definition is 
the most "mathematical" of any well known current programming language).
If we look at the history of certain ideas in mathematics, say the 
foundations of the infinitesimal calculus (*), we see that the progress 
is from examples to rules, not the other way around. I learned counting
from examples before I learned Peano's Axioms. 

Bourbaki /= good pedagogy

> Examples can never tell you what the general rules are, they
> can only illustrate particular cases, and therefore there is
> a danger of not understanding the generalization.

I agree with this. That's why I like to have a reference manual at my side 
when I'm learning. However, I've found that like most people I learn best 
by example. I personally detest the analogy between programming languages 
and human languages, since any good Chomskyan will tell you we have hard
wiring for the latter, but I suspect that even you Robert learned your
native language by generalizing incorrectly from examples.
 
> Certainly a BNF grammar is a FAR clearer documentation of
> syntax than syntactic examples, wouldn't you agree?

Of course! However, when I learn a new programming language, to get an
idea of the syntax I look at a few representative examples first. That
allows me to get an idea if the syntax is familiar. Here is a rough cut at
some language syntax "classes" where I've grouped languages into
*synatactically" similar groups:

Algol: Pascal, Modula-<X>, Oberon-<X>, Ada, Dylan
C : C++, Objective-C, Java, C#
Lisp: Scheme, Emacs-Lisp, Common-Lisp...
Prolog: Erlang, Mercury
Haskell: Clean, Python, OCCAM ("offset rules")
ML: SML, OCaml

While I'm not intimately familiar with all of these languages, a quick
glance at new language examples allows me to categorize it (or not!) and 
I find that I can get up to speed *on syntax* quickly. Then, afterwards, I 
go to the BNF. I take it that you just go straight to the BNF and skip 
the examples altogether.

The reason I asked if you teach your way, and if students are receptive, 
is that I'd be interested in trying it myself. In fact, I'll try this
with the next PL I learn. 

-- Brian

(*) Yes, I deliberately used "infinitesimal". I'm a rebel. The theory of 
    limits is oppressive, and infinitesimals came first. Non-standard 
    analysis rules :-)

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article
<Pine.BSF.4.21.0101180808230.9927-100000@shell5.ba.best.com>,
  Brian Rogoff <bpr@shell5.ba.best.com> wrote:
> Well, I am in awe. If I remember correctly, there are a few
> important aspects of SML programming, like evaluation order,
> that are not explicitly stated but have to be deduced. I
> can't imagine anyone getting a  feel for how to program in ML
> from the definition, especially if they were  not familiar
> with functional programming style.

Neither can I :-) Indeed I was completely familiar with
functional programming style (e.g. I knew Miranda well as well
as the whole EFL (English-functional-language) work.

Actually there is a very important point here which is that
examples ARE very valuable for showing style, as opposed to
rules. And indeed, I can't imagine learning style without
learning rules.

An analogy is a piano, you can read a set of specifications
that clearly tell you, press this key to get middle A, which
is 440Hz etc. But you do NOT get an idea of how to play Chopin
from such specs. And even if you were Bach, you might still
find yourself a bit mystefied by a Chopin score without any
examples of how it sounded on a modern piano.

So for stylistic issues etc, I quite agree that examples are
helpful, indeed critical, and actually one of our big failings
in teaching programming is that students do not get to study
large examples of well written programs.

> I agree, but I think mathematics is quite a bit different
> from programming, and I have a decent background in both.

Interesting, people differ on this point. Certainly Lambert
Meertens would disagree with you I think :-)

>(Note to RBKD: that's why I chose SML as an example, since
> it's definition is  the most "mathematical" of any well known
> current programming language).

Well I think the definition of Algol-68 is a whole lot more
difficult in that respect, and actually the PL/1 standard is
pretty mathematical (it's VDL style denotational semantics).


> However, I've found that like most people I learn best
> by example.

And I have strongly agreed with that position from the start.
But this still does not answer the question of whether to put
more or less examples in the RM, because it is also the case
that most people do NOT learn a language from its defining
standard in any case (a point you are essentially arguing :-)
So it is not clear that the above agreed on fact (that most
people learn best from examples) means that examples belong
in the RM, especially trivial examples that assume you do not
know the language at all (which is the nature of most of the
current RM examples -- they are NOT there to illustrate tricky
points in the language).


> > Certainly a BNF grammar is a FAR clearer documentation of
> > syntax than syntactic examples, wouldn't you agree?
>
> Of course! However, when I learn a new programming language,
> to get an idea of the syntax I look at a few representative
> examples first.

Ah well, there we are diffeent, I find it quite sufficient
to scan through the BNF. Part of the trouble in Algol-68 is
that there IS no BNF, only the two level grammar, which
embodies all the syntax AND static semantic information, and
this makes the syntax somewhat inpenetrable (at least at
first).

> Algol: Pascal, Modula-<X>, Oberon-<X>, Ada, Dylan
> C : C++, Objective-C, Java, C#
> Lisp: Scheme, Emacs-Lisp, Common-Lisp...
> Prolog: Erlang, Mercury
> Haskell: Clean, Python, OCCAM ("offset rules")
> ML: SML, OCaml
>
> While I'm not intimately familiar with all of these
languages, a quick
> glance at new language examples allows me to categorize it
(or not!) and
> I find that I can get up to speed *on syntax* quickly. Then,
afterwards, I
> go to the BNF. I take it that you just go straight to the BNF
and skip
> the examples altogether.

OK, I see that point, that makes sense ... I think I have never
come to a new language without knowing in advance which
category it belonged in :-)

> The reason I asked if you teach your way, and if students are
> receptive,  is that I'd be interested in trying it myself. In
> fact, I'll try this with the next PL I learn.

I have not tried to insist on students learning languages from
the standard, but I have tried to insist that they read the
standard. I taught a course on language standards a while ago,
and we looked at several standards, including the COBOL
standard in detail, and some students in the class definitely
learned COBOL from the standard plus lectures.

Going back to Algol-68, I must say this was a huge and
surprising failure for me. I joined a little study group
where we read through the A68 report, and attended several
meetings, and at the end of these meetings I simply had
NO IDEA AT ALL what was going on.

Which is too bad, because I had been interested in doing a
compiler for A68 early on (following off the SPITBOL work),
but I decided it was inpenetrable. It was not till several
years later that I visited Leeds University where there was
an ICL machine with RRE A68 installed, and I read Ian Currie's
wonderful 70 page yellow book covering all of A68. I read it
an evening. Came the next day, wrote a few hundred line A68
program -- worked first time -- great! And then I got fully
involved in A68 (I chaired IFIP WG2.1 and the A68 maintenance
committee for many years, and participated in some of the late
design efforts including the representation standard, and the
modules standard [the latter influenced the Ada design]), but
that delay of several years was a pity.

[interestingly, if I had not read Ian's book, I would never
have got involved in Ada, since my Ada involvement came from
the IFIP connection :-)]

By the end of things, I was one of the relatively few people
who really knew the A68 standard cover to cover.

But some people are MUCH better at reading this kind of
formal document than me. Phil Shaw wrote a thesis describing
a language GYVE for operating system construction. He read
the A68 report, immediately understood and liked it, and
wrote a complete 2 level grammar for GYVE as part of his
thesis.

I must say, I still look for the Ada equivalent of Ian Currie's
little yellow book -- I know, I know, I should write it :-)
[it was of course full of examples, as something like that
should be].

I actually started out a year or so ago with a description of
Ada by example only -- nothing but examples -- no rules at all.
You can see a start of this on the compilers course home page
at www.cs.nyu.edu. It's an interesting approach for those who
like to learn by example.


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Georg Bauhaus]

Robert Dewar (robert_dewar@my-deja.com) wrote:

: I actually started out a year or so ago with a description of
: Ada by example only -- nothing but examples -- no rules at all.
: You can see a start of this on the compilers course home page
: at www.cs.nyu.edu.

From it:
	"The subtype mechanism allows defining variables
	 that have a limited range.  This is useful for 
	 debugging and documentation purposes..."

There! Is this a hint that we should not be relying
on range checking in some cases, e.g. when using a
subtype for an array index range?



Georg Bauhaus

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article <947sei$r2r$1@news-hrz.uni-duisburg.de>,
  sb463ba@l1-hrz.uni-duisburg.de (Georg Bauhaus) wrote:

> There! Is this a hint that we should not be relying
> on range checking in some cases, e.g. when using a
> subtype for an array index range?

Indeed, good Ada style is that a program should not be
written so that catching constraint_errors is part of
the normal processing logic. For one thing, optimization
can cause a lot of surprises in this area (you really
need to read *and understand* 11.6 if you are going to
write your own constraint_error handlers).



Sent via Deja.com
http://www.deja.com/

Learning methods

[Anders Wirzenius]

"Robert Dewar" <robert_dewar@my-deja.com> wrote in message
news:947hj1$o1r$1@nnrp1.deja.com...
> In article
> <Pine.BSF.4.21.0101180808230.9927-100000@shell5.ba.best.com>,
...
>
> An analogy is a piano, you can read a set of specifications
> that clearly tell you, press this key to get middle A, which
> is 440Hz etc. But you do NOT get an idea of how to play Chopin
> from such specs. And even if you were Bach, you might still

I suppose that you by "specifications" don't mean the notes.

> find yourself a bit mystefied by a Chopin score without any
> examples of how it sounded on a modern piano.

Some musicians discourage their colleagues not to listen to other performers
interpretation for not to be too affected by their way of playing.

> I have not tried to insist on students learning languages from
> the standard, but I have tried to insist that they read the
> standard. I taught a course on language standards a while ago,

I have used a two-phase method sometimes:
1. Learning by playing (not the piano :-). That was pretty much learning by
example and making own examples over and over again.
2. Learing by specification. That meant going back and start reading the
specification or the manual starting from page 1.

Phase 1 raises me to a level where I don't have to use a major part of my
energy to learn to understand the basic concepts. Phase 2 is time consuming
but it is the only way of raising your knowledge to the level_of_wisdom.

> formal document than me. Phil Shaw wrote a thesis describing
> a language GYVE for operating system construction. He read
> the A68 report, immediately understood and liked it, and
> wrote a complete 2 level grammar for GYVE as part of his
> thesis.

Maybe he was not familiar with the language, but he certainly was an
experienced interpreter of specifications.

Re: Examples in Docs, was Re: Escape Sequences in Strings

[mark_lundquist]

In article <947hj1$o1r$1@nnrp1.deja.com>,
  Robert Dewar <robert_dewar@my-deja.com> wrote:
>
> I actually started out a year or so ago with a description of
> Ada by example only -- nothing but examples -- no rules at all.

Kind of a Suzuki method for programming?

:-)

-- Mark


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Dale Stanbrough]

Robert Dewar wrote:

> ... the RM, especially trivial examples that assume you do not
> know the language at all (which is the nature of most of the
> current RM examples -- they are NOT there to illustrate tricky
> points in the language).

It's interesting to note that English law, and countries that
have inherited this model, rely on case law to nail down the
semantics of the laws that are made via examples. Still, I 
suppose we shouldn't hold our breath waiting for a full
mathematical notation of the next taxation law semantics :-).


Dale

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article <dale-2E1DCB.22580421012001@news-server>,
  Dale Stanbrough <dale@cs.rmit.edu.au> wrote:

> It's interesting to note that English law, and countries that
> have inherited this model, rely on case law to nail down the
> semantics of the laws that are made via examples. Still, I
> suppose we shouldn't hold our breath waiting for a full
> mathematical notation of the next taxation law semantics :-).

Indeed the use of examples (case law) to nail down lack of
clarity in the statutes is a pretty good example of what we
want to avoid when it comes to programming languages. It is
one thing to find out that the law is interpreted differently
in the second and fourth circuits, and quite another to find
that two different compilers for language XXX do different
things based on different local interpretations and examples!

Actually there *has* been one attempt to formalize a law. As an
excercise in the use of Prolog, the revised citizenship law in
England which embodied changes pushed by the Thatcher
government (*) was complex and was encoded as a set of Prolog
rules implementing the predicate Is_Citizen and related
predicates from the law. This excercise actually caught some
internal inconsistencies which were revised before the law
became final.

(*) Non-technical note: These changes included the rather
amazing change that for the first time in recent times makes
a difference between men and women when it comes to passing
on citizenship. English men pass citizenship to their children,
English women do not always do so if they are married to
aliens.


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Matthew Woodcraft]

Robert Dewar <robert_dewar@my-deja.com> writes:

> In the case of a language definition, examples indeed convey
> no information that cannot be derived from the definition
> proper (unless the definition is incomplete). Yes, they may
> be helpful in understanding, but they do not have any
> non-derivable information.

There's also the case where the definition is buggy. If examples were given
normative force (saying 'this code is legal, and has such-and-such an
effect'), they could change a consistent but undesirable definition to an
inconsistent one.

To continue the stretched analogies between language definitions and code,
they could act as 'assertions'.

I don't know how errata in the Ada standard are dealt with, but I can
imagine a case where the language designers could be stuck with a meaning
they didn't intend (making some construct effectively unusable, for
example), but be unable to change it because the standard as published was
consistent and unambiguous. An example of the construct as they had intended
it to be used would prevent this occurring.

-M-

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article <871yu16d9j.fsf@chiark.greenend.org.uk>,
  Matthew Woodcraft <mattheww@chiark.greenend.org.uk> wrote:
> I don't know how errata in the Ada standard are dealt with,
> but I can imagine a case where the language designers could
> be stuck with a meaning they didn't intend (making some
> construct effectively unusable, for example), but be unable
> to change it because the standard as published was
> consistent and unambiguous.

This represents a serious misconception, of course the
standards committee can fix errors of this kind, and this
has often occured. No one ever gets "stuck" in a case like
this. You are imagining a problem that simply does not exist.

For example, in the original Ada 83 definition, it was clear
and unambiguous that

  subtype r is range 1 .. 10;

did NOT make r a static subtype. In fact there were essentially
no static subtypes. The definition was clear, consistent, and
unambiguous on this point, but of course this was understood to
be an error (it is indeed interesting to study how this error
arose), and was fixed.

> An example of the construct as they had intended
> it to be used would prevent this occurring.

Very unlikely indeed. Most of the examples are trivial and very
unlikely to be informative in this manner. We HAVE found a
number of cases where the examples were incorrect :-)


Sent via Deja.com
http://www.deja.com/

RE: Examples in Docs

[Robert C. Leif, Ph.D.]

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/

RE: Examples in Docs

[mark_lundquist]

In article <mailman.979661289.9558.comp.lang.ada@ada.eu.org>,
  comp.lang.ada@ada.eu.org wrote:
> 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

I've been thinking about how more thorough self-reference could make a
HT version of the RM a really powerful tool, even without additional
material such as examples (not to discount your idea, which I think is
a good one).

What I would like to have:

1) every cross-reference anchor a hyperlink to the referenced text
2) every use of a defined term (e.g. "protected action", "nominal
subtype", "master", etc.) anchor a HL to the definition of the term
3) the instance of every term in its definition anchor a HL to the
index entry for the term
4) HLs in the syntax summary/cross-reference

My RM of choice :-) is the annotated version w/ Technical Corrigenda on
the ACAA web site; the annotations help me understand why things are
what they are, and I feel like I'm getting the "full meal deal".  A HT
version of that that allowed the user to expand/elide the annotations
would be great.

A nice companion would be a HT version of the Rationale with HLs
linking to the RM (and maybe from the RM).

Throwing the AIs into the mix would create a document system that might
be really nice for a small handful of people, but I don't know if it'd
be worth the effort for that... same w/ Steelman for the
historically/legally inclined :-)  I'm now diluting my own idea with
brain fartage so I will stop...

--
--
Post (Brain.Fart);
-- :-) mark lundquist


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs

[Randy Brukardt]

mark_lundquist@my-deja.com wrote in message
<942eet$das$1@nnrp1.deja.com>...

>I've been thinking about how more thorough self-reference could make a
>HT version of the RM a really powerful tool, even without additional
>material such as examples (not to discount your idea, which I think is
>a good one).
>
>What I would like to have:
>
>1) every cross-reference anchor a hyperlink to the referenced text
>2) every use of a defined term (e.g. "protected action", "nominal
>subtype", "master", etc.) anchor a HL to the definition of the term
>3) the instance of every term in its definition anchor a HL to the
>index entry for the term
>4) HLs in the syntax summary/cross-reference
>
>My RM of choice :-) is the annotated version w/ Technical Corrigenda on
>the ACAA web site; the annotations help me understand why things are
>what they are, and I feel like I'm getting the "full meal deal".  A HT
>version of that that allowed the user to expand/elide the annotations
>would be great.


Humm, the HTML version of the RM on the ACAA website in fact includes
items 1 and 3 on your list above. (Try clicking on any index entry, and
you will be taken directly to the item referenced.)

Item  2 would be wonderful, but it would be very expensive to do (as the
source of the RM does not mark uses of terms in any special way).
Usefully picking them out with any automated method is bound to be very
incomplete.

Item 4 is partially accomplished by the HTML RM -- the section numbers
are hot links (so you can get to the section where the production is
defined). But not the individual items.

Therefore, I conclude that what you want is already available in the
HTML ARM available on the ACAA web site. When I building these versions
of the RM, I expected that almost all on-line use of the RM would use
these HTML versions (the PDF versions being restricted to printing).

>Throwing the AIs into the mix would create a document system that might
>be really nice for a small handful of people, but I don't know if it'd
>be worth the effort for that.

Well, almost all of the AIs included in the Technical Corrigendum (and
in the Record of Responses document, as well) are represented by (new)
annotations in the annotated version of the RM. The handful that don't
have annotations were too complex to explain in the limited time I had,
or simply didn't have an obvious point in the RM to put them. All such
annotations (and text changes as well) are linked to the associated
Defect Reports (the ISO term for AIs).

Of course, new AIs aren't included that way, but there are very few of
them finished at the moment, so you're not missing much...

I put a lot of thought into what could be accomplished with the time I
had available, and I'm glad that people appreciate that work (even if
they don't know yet that it was done for them!).

                    Randy Brukardt
                    ARG Editor

Re: Examples in Docs

[mark_lundquist]

In article <q4r96.1026$Br5.374077@homer.alpha.net>,
  "Randy Brukardt" <randy@rrsoftware.com> wrote:
> mark_lundquist@my-deja.com wrote in message
> <942eet$das$1@nnrp1.deja.com>...
>
> >I've been thinking about how more thorough self-reference could make
a
> >HT version of the RM a really powerful tool, even without additional
> >material such as examples (not to discount your idea, which I think
is
> >a good one).
> >
> >What I would like to have:
> >
> >1) every cross-reference anchor a hyperlink to the referenced text
> >2) every use of a defined term (e.g. "protected action", "nominal
> >subtype", "master", etc.) anchor a HL to the definition of the term
> >3) the instance of every term in its definition anchor a HL to the
> >index entry for the term
> >4) HLs in the syntax summary/cross-reference
> >
> >My RM of choice :-) is the annotated version w/ Technical Corrigenda
on
> >the ACAA web site; the annotations help me understand why things are
> >what they are, and I feel like I'm getting the "full meal deal".  A
HT
> >version of that that allowed the user to expand/elide the annotations
> >would be great.
>
> Humm, the HTML version of the RM on the ACAA website in fact includes
> items 1

So it does... and I'm sure I've used it many times without even
noticing it, so I just didn't remember it without having it up in a
browswer in front of me! :-)

> and 3 on your list above. (Try clicking on any index entry, and
> you will be taken directly to the item referenced.)

Yes of course, but what I'm wanting is a link in the opposite
direction, from the defining instance of the term into the index, at
the family of index entries for that term.

The combination of (2) and (3) is the real point... Let's say you were
reading along and you came to the term 'discrete range', and you say "I
want to see where that's defined, so you just click on it and (2) go to
the definition.  Then you say "I wonder where else this term is used",
so you click again and (3) you're in the index looking at all the index
entries for 'discrete range'.  So if you can see a term in your browser
you are only 3 clicks away from any other instances of use of the term.

>
> Item  2 would be wonderful, but it would be very expensive to do (as
the
> source of the RM does not mark uses of terms in any special way).
> Usefully picking them out with any automated method is bound to be
very
> incomplete.

Undoubtedly...

>
> Item 4 is partially accomplished by the HTML RM -- the section numbers
> are hot links (so you can get to the section where the production is
> defined). But not the individual items.
>

So I guess my wish-list would include finer-grained cross-references...

> [...]
> I put a lot of thought into what could be accomplished with the time I
> had available, and I'm glad that people appreciate that work

I sure do appreciate it!

BTW, I'm not suggesting that my ideas above are anything that I think
should have to do with ACAA or ARG editorial activities.  It seems like
you've gone "above and beyond the call of duty" as it is! :-)  I guess
I was imagining that someone else would produce it, maybe a student
project or something.

But now that you bring it up, there are two modest improvements that I
think could be made to the ACAA version even with limited time :-)

1) 'A'..'Z' links into the index (it's a pretty big index to scroll
through)

2) Chapter links into the TOC (again, to reduce scrolling)

In fact those are so easy, maybe I'll just make my own index page and
TOC and bookmark those...

Best Regards,
Mark




Sent via Deja.com
http://www.deja.com/

RE: Examples in Docs

[J. David Bryan]

On Tue, 16 Jan 2001 21:29:13 GMT in article <942eet$das$1@nnrp1.deja.com>, 
mark_lundquist@my-deja.com wrote...
>
>
>What I would like to have:
>
>1) every cross-reference anchor a hyperlink to the referenced text
>2) every use of a defined term (e.g. "protected action", "nominal
>subtype", "master", etc.) anchor a HL to the definition of the term
>3) the instance of every term in its definition anchor a HL to the
>index entry for the term
>4) HLs in the syntax summary/cross-reference

If you're running Windows, the WinHelp version of the Ada RM from:

  http://www.adaic.org/standards/95lrm/LRMWinHelp/

may address your requirements.  From the "Foreword to the WinHelp Version" 
contained therein:

  Scroll Buttons:

  At the top of several topics are lettered or numbered "scroll buttons"
  which, when clicked, will scroll the topic to the first entry with the 
  indicated character.  For example, when viewing the RM Table of Contents 
  page, clicking the button marked 12 scrolls the page to the first entry for 
  RM Section 12.

  The following helpfile pages have scroll buttons:

    *  RM Table of Contents
    *  Annex P, Syntax Summary
    *  Annex P, Syntax Cross Reference
    *  RM Index

  Syntax References:

  Nonterminals (syntactic categories) present on the right side of syntax 
  rules are hyperlinked to their definitions.  Clicking on a nonterminal will 
  open up a secondary window which will display the syntax rule defining the 
  nonterminal and a hyperlink to the paragraph of the RM where the rule is 
  given.  In addition, referenced nonterminals in the secondary window are 
  also hyperlinked to their definitions.

  [...]

  Term Definitions:

  The helpfile index (accessed by the INDEX button) contains links to the text 
  of the definitions of terms in the RM.  Each defined term appears in the
  helpfile index under the heading, "terms defined."

  Term References:

  References to terms defined elsewhere in the RM are hyperlinked to their 
  respective definitions, unless the definition either immediately precedes or 
  follows the reference.


>My RM of choice :-) is the annotated version w/ Technical Corrigenda on
>the ACAA web site....

I intend to produce a WinHelp version of the RM+TC as soon as time permits.
I will post a notice in CLA when that is available.

-- 
                                        -- Dave Bryan
 
NOTE: Due to unrelenting SPAM, I regret that I have been forced to post with
an encoded address.  Please ROT13 this message to obtain the reply address.
Address also available at http://www.bcpl.net/~dbryan/mailto.html
 
Cyrnfr ercyl gb guvf nqqerff:  wqoelna@npz.bet

RE: Examples in Docs

[Robert Dewar]

In article <mailman.979661289.9558.comp.lang.ada@ada.eu.org>,
  comp.lang.ada@ada.eu.org wrote:
> From: Bob Leif
> 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.

Perhaps it could use the existing wording in the Ada Reference
Manual section 1.1.2 :-)

14   The core language and the Specialized Needs Annexes are
normative, except that the material in each of the items listed
below is informative:

   15  Text under a NOTES or Examples heading.

   16  Each clause or subclause whose title starts with the
       word ``Example'' or ``Examples''.

I generally don't think the RM is a very good source for
learning anyway, though perhaps a version which was annotated
with explanations and extra examples, all hyper-linked could
be useful. The old annotated Fortran standard might be an
interesting model




Sent via Deja.com
http://www.deja.com/

RE: Examples in Docs

[Robert C. Leif, Ph.D.]

From: Bob Leif
To: Robert Dewar et al.

Although, the RM contains the disclaimer you cited, the very fact that these
examples were included in the document encourages belief that they are
gospel.

How about, "The material in each of the hypertext linked examples is only
informative, does not have the same authorship, and is not to be construed
as part of this document."
-----Original Message-----
From: comp.lang.ada-admin@ada.eu.org
[mailto:comp.lang.ada-admin@ada.eu.org]On Behalf Of Robert Dewar
Sent: Tuesday, January 16, 2001 6:43 PM
To: comp.lang.ada@ada.eu.org
Subject: RE: Examples in Docs


In article <mailman.979661289.9558.comp.lang.ada@ada.eu.org>,
  comp.lang.ada@ada.eu.org wrote:
> From: Bob Leif
> 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.

Perhaps it could use the existing wording in the Ada Reference
Manual section 1.1.2 :-)

14   The core language and the Specialized Needs Annexes are
normative, except that the material in each of the items listed
below is informative:

   15  Text under a NOTES or Examples heading.

   16  Each clause or subclause whose title starts with the
       word ``Example'' or ``Examples''.

I generally don't think the RM is a very good source for
learning anyway, though perhaps a version which was annotated
with explanations and extra examples, all hyper-linked could
be useful. The old annotated Fortran standard might be an
interesting model




Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[mark_lundquist]

In article <940f9j$nj2$1@nnrp1.deja.com>,
  peter_richtmyer@my-deja.com wrote:
> [...]
> 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.

Of course you don't mean that comments are unnecessary in program text,
only that they do not affect the function :-)

Cheers,
Mark Lundquist


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Peter Richtmyer]

<mark_lundquist@my-deja.com> wrote in message
news:94299p$8dd$1@nnrp1.deja.com...
> In article <940f9j$nj2$1@nnrp1.deja.com>,
>   peter_richtmyer@my-deja.com wrote:
> > [...]
> > 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.
>
> Of course you don't mean that comments are unnecessary in program text,
> only that they do not affect the function :-)
>
Actually, I did mean they are *unnecessary*, meaning *not needed*.

They are certainly not required by the compiler. With respect to the human
reader,
given enough time, and given access to the requirements, design specs, PDl,
interface
specs,  other docs, other people, etc,  the program comments are *not
needed*.
Please don't misunderstand, I tend to be a *comment freak*, writing more
lines of
comments than code in the programs that I write. I tend to attach words like
*lazy*, *discourteous*, and *unprofessional* to programmers I work with who
do not adequately comment our code. Though *clue-less* might pertain too.

I used the word *our* above very intentionally too. I am talking about our
team
and our company. No one person owns the code at work. I take pride in my
code. But not sole possession.
>
>
In another sub-thread of this discussion, someone stated that document
examples
and program comments are not *analogous*. I agree. I intentionally avoided
the
use of the word *analogy*, instead weasle-wording it with the phrase
*somewhat similar* (see above).

Examples and comments are somewhat similar in that they both make it easier
to
understand what I am reading (document or program) . They can also make it
easier to perform what is quite often the next step, i.e. to create or
modify some
code.  And, of course, the comments.  :-)

Peter

P.S.  Why do I keep using * instead of "  ?     :-)

Re: Examples in Docs, was Re: Escape Sequences in Strings

[mark_lundquist]

In article <J_e96.5326$DI.58950@e420r-atl1.usenetserver.com>,
  "Peter Richtmyer" <pmr@efortress.com> wrote:
> <mark_lundquist@my-deja.com> wrote in message
> news:94299p$8dd$1@nnrp1.deja.com...
> > In article <940f9j$nj2$1@nnrp1.deja.com>,
> >   peter_richtmyer@my-deja.com wrote:
> > > [...]
> > > 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.
> >
> > Of course you don't mean that comments are unnecessary in program
text,
> > only that they do not affect the function :-)
> >
> Actually, I did mean they are *unnecessary*, meaning *not needed*.
>
> They are certainly not required by the compiler. With respect to the
human
> reader,
> given enough time, and given access to the requirements, design
specs, PDl,
> interface
> specs,  other docs, other people, etc,  the program comments are *not
> needed*.

So strictly speaking, it's not comments that are necessary (for
understandability), but documentation...

I almost said that in another post, but I didn't want to cloud the
issue!  Bad call, I guess... :-)

I think the idea of embedded hyperlinks in comments to navigate out to
supporting documentation of the kind you mention could really be
worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)

>
> Peter
>
> P.S.  Why do I keep using * instead of "  ?     :-)
>

Maybe some kind of pinky finger deformity? :-)

Cheers,
Mark


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article <94a2jj$tc2$1@nnrp1.deja.com>,
  mark_lundquist@my-deja.com wrote:
> I think the idea of embedded hyperlinks in comments to
> navigate out to supporting documentation of the kind you
> mention could really be
> worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)

Generally I much prefer ALL technical documentation (as opposed
to user documentation) of the code to be in the code. Why?
Simple, in my experience VERY few programmers have the
discipline to maintain external documents, so they quickly get
out of sync and become completely useless.

It is hard enough for most people to be diligent about
maintaining comments and documentation that *are* part of
the source code.

You really have to develop the exact opposite opinion from
"comments don't really matter and have no effect", and consider
that a bad spelling in a comment is a real bug :-) Sure a bad
spelling is not serious, but the attitude that will not
tolerate bad spelling in program comments is one that goes
along with a commitment to maintaining good internal
documentation.


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Preben Randhol]

On Sat, 20 Jan 2001 14:24:50 GMT, Robert Dewar wrote:
>
>Generally I much prefer ALL technical documentation (as opposed
>to user documentation) of the code to be in the code. Why?
>Simple, in my experience VERY few programmers have the
>discipline to maintain external documents, so they quickly get
>out of sync and become completely useless.

I agree. If one wanted an external documentation, one can run a
script/program which extracts the documentation from the sourcefiles and
assemble it as one likes. Then it would be easier to maintain an
external document as well if that was desired.

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar]

In article
<slrn96j8l9.ig.randhol+abuse@kiuk0156.chembio.ntnu.no>,
  randhol+abuse@pvv.org (Preben Randhol) wrote:

> I agree. If one wanted an external documentation, one can run
> a script/program which extracts the documentation from the
> sourcefiles and assemble it as one likes. Then it would be
> easier to maintain an external document as well if that was
> desired.

Yes, that seems like a good compromise but in this case I
favor minimal markup, so that the documentation can still
be easily read with ordinary editing tools while working
with the source. One can imagine a universal environment
allowing fancy markup, and that would be fine, if and
when it is universal :-)

An interesting example of this approach in action (extracting
documentation from listings) would be to generate a manual for
the GNAT component library (GNAT.xxx) where all the user level
documentation is currently maintained in the specs of the
packages.


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Preben Randhol]

On Sat, 20 Jan 2001 15:00:46 GMT, Robert Dewar wrote:
>Yes, that seems like a good compromise but in this case I
>favor minimal markup, so that the documentation can still
>be easily read with ordinary editing tools while working
>with the source. One can imagine a universal environment
>allowing fancy markup, and that would be fine, if and
>when it is universal :-)

One could of course in the spirit of Ada, choose a markup system that
increases the readability without inflicting a lot of tag insertions :-)

GtkAda uses a system that looks something like this:

--  <description>
--  This widget implements a top level window.
--  It is used as the base class for dialogs, ...

[I have clipped off some of the text]

--  A window can also be modal, i.e. grab all the mouse and keyboard
--  events in the application while it is displayed.
--
--  </description>
--  <c_version>1.2.6</c_version>

[...]

   procedure Gtk_New
     (Window   : out Gtk_Window;
      The_Type : in  Gtk.Enums.Gtk_Window_Type := Gtk.Enums.Window_Toplevel);
   --  Create a new window.
   --  The_Type specifies the type of the window, and can be either a
   --  top level window, a dialog or a popup window. You will most often only
   --  need to use Window_Toplevel, the other types are mostly used internally
   --  by gtk+.
   --  A Popup window is used to display a temporary information window. It has
   --  no borders nor resizing handles.

To see how it looks on the web look at:

   http://gtkada.eu.org/docs/gtkada_rm_113.html#SEC475

This could be used to make reference manuals, not tutorials nor
spec documents, but think that that should be in a separate document.

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Ted Dennison]

In article <slrn96lhou.ekk.randhol+abuse@kiuk0156.chembio.ntnu.no>,
  randhol+abuse@pvv.org (Preben Randhol) wrote:

> GtkAda uses a system that looks something like this:
>
> --  <description>
> --  This widget implements a top level window.
> --  It is used as the base class for dialogs, ...
>
> [I have clipped off some of the text]
> --  </description>

Interesting. I take it you have a custom tool that does the transformation?

--
T.E.D.

http://www.telepath.com/~dennison/Ted/TED.html


Sent via Deja.com
http://www.deja.com/

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Preben Randhol]

On Mon, 22 Jan 2001 14:47:59 GMT, Ted Dennison wrote:
>Interesting. I take it you have a custom tool that does the transformation?

There is a perl script, I believe, distributed with the gtkada source.

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Preben Randhol]

On 22 Jan 2001 20:08:22 GMT, Preben Randhol wrote:
>There is a perl script, I believe, distributed with the gtkada source.

It is called generate_doc.pl and found in docs/gtkada_rm directory of
the latest GtkAda source code distribution[*].

[*] Note I have only checked the linux distribution, I don't know about
the Windows distribution, but I guess it is there aswell.

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Stephen Leake]

Robert Dewar <robert_dewar@my-deja.com> writes:

> Generally I much prefer ALL technical documentation (as opposed
> to user documentation) of the code to be in the code. Why?
> Simple, in my experience VERY few programmers have the
> discipline to maintain external documents, so they quickly get
> out of sync and become completely useless.

In general, I agree. But there are times when an external document is
better:

1) The document presents an overview of the design of a large system,
   so it uses diagrams, and it doesn't belong in any one source file.

2) The document presents an algorithm that is best described by
   mathematical notation; flat ASCII is just not good enough for this.

I'm sure there are other times, but these are the ones I've run
across.

When I write an algorithm document, I define the mapping from math
symbols to Ada names. I also use LaTeX, so I can edit the document in
the same editor (Emacs) as the Ada source; that makes it much easier
to keep them in synch.

-- 
-- Stephe

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Georg Bauhaus]

Stephen Leake (stephen.a.leake.1@gsfc.nasa.gov) wrote:

: 1) The document presents an overview of the design of a large system,
:    so it uses diagrams, and it doesn't belong in any one source file.

: 2) The document presents an algorithm that is best described by
:    mathematical notation; flat ASCII is just not good enough for this.

: When I write an algorithm document, I define the mapping from math
: symbols to Ada names. I also use LaTeX, so I can edit the document in
: the same editor (Emacs) as the Ada source; that makes it much easier
: to keep them in synch.


There is a still evolving tool for this, and the direction into
which it moves is, it seems, under consideration.
http://www.eecs.harvard.edu/~nr/noweb/wish.html


Georg Bauhaus

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Preben Randhol]

On 20 Jan 2001 14:02:48 -0500, Stephen Leake wrote:
>In general, I agree. But there are times when an external document is
>better:
>
>1) The document presents an overview of the design of a large system,
>   so it uses diagrams, and it doesn't belong in any one source file.

Yes, but wouldn't that go into the spec documentation?

>2) The document presents an algorithm that is best described by
>   mathematical notation; flat ASCII is just not good enough for this.

Yes that is true, though one could use LaTeX markup for equations within
the source code comment and have the parser generate a external
document. One could use the MathML (http://www.w3.org/Math/) as well,
but last time I look at it looked like a real pain[*] to write the
markup.

[*] Example:

x + a/b

<mrow>
   <mi> x </mi>
   <mo> + </mo>
   <mrow>
      <mi> a </mi>
      <mo> / </mo>
      <mi> b </mi>
   </mrow>
</mrow>

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt

Re: Examples in Docs, was Re: Escape Sequences in Strings

[Mark Lundquist]

Robert Dewar <robert_dewar@my-deja.com> wrote in message
news:94c73f$hs9$1@nnrp1.deja.com...
> In article <94a2jj$tc2$1@nnrp1.deja.com>,
>   mark_lundquist@my-deja.com wrote:
> > I think the idea of embedded hyperlinks in comments to
> > navigate out to supporting documentation of the kind you
> > mention could really be
> > worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)
>
> Generally I much prefer ALL technical documentation (as opposed
> to user documentation) of the code to be in the code.

I was involved with the IEEE POSIX P1003.5c standardization-- the Ada
binding to network services.  That's a pretty reasonably big-sized document
:-)  I'd hate for that to have to go into the source code as comments...

> Why?
> Simple, in my experience VERY few programmers have the
> discipline to maintain external documents, so they quickly get
> out of sync and become completely useless.
>
> It is hard enough for most people to be diligent about
> maintaining comments and documentation that *are* part of
> the source code.

True enough...

I think embedded HLs in comments would help.  They effectively increase the
"proximity" of the document to the code (just a click away) so people
hopefully care a little more that the documentation be right.

I find super comment-heavy code cumbersome to work with.

> You really have to develop the exact opposite opinion from
> "comments don't really matter and have no effect", and consider
> that a bad spelling in a comment is a real bug :-) Sure a bad
> spelling is not serious, but the attitude that will not
> tolerate bad spelling in program comments is one that goes
> along with a commitment to maintaining good internal
> documentation.

Yes, that's the attitude one has to develop.  At least we agree that
documentation is important, wherever it goes :-) and that the "all that
matters is the code" mindset is one that has to be eliminated.

---

Just to be irrelevant...

It's [flame-bait :] analogous :-) to attitudes about style and design
principles.  Some people think that the most important thing about a program
is that it be correct (which is only true for the version of a program that
is deployed).  Under that view, a kludgy, brittle, crappy program that has
been debugged into existence and finally gives the right answer is
infinitely preferable to a well-designed, elegant program that has a minor
bug (let's say, a one-line bug) so that it gives a wrong answer.  In fact, I
once worked with a manager that held this opinion.  But, I want software
that both is well-written and gives the right answer, because that software
by definition is easy to understand and easy to change in the future, so it
will be fun to work on and not such a pain to change that years go by with
nobody being able to find the time or work up the nerve to overhaul it.
Given that, I'll take Program Number Two any day, because it is *much*
closer (just a minor bug away) from the ideal of correctness and elegance,
whereas the "correct" program will never, ever get there.

Increasing the readability of Ada was RE: Examples in Docs

[Robert C. Leif, Ph.D.]

From: Bob Leif
To: Robert Dewar et al.

I totally agree. However, if the inclusion of information into the Ada
source is to be maximized, then the XML annotation data type or equivalent
(structured comments) should be created for Ada or present documentation
technology should be applied to Ada source. If an XML schema were created
for Ada, an XML editor with a plug-in could be used to edit Ada source. This
would have several advantages: 1) future commercial editors could be readily
adapted for Ada. 2) The style information would be separated from the text.
A style sheet or separate schema could be employed for capitalization etc.
3) Special annotations could be created with the requirement that text be
entered or even specific elements must be entered. 4) Hyperlinks to external
documentation could be included. And 5) Mathematics could be rendered in
MathML, which provides the interesting possibility of translation of MathML
into Ada.

XML Schema Part 1: Structures
W3C Candidate Recommendation 24 October 2000
This version:
http://www.w3.org/TR/2000/CR-xmlschema-1-20001024/
(in XML (with its own DTD, XSL stylesheet (Nov REC version)) and HTML), with
separate provision of the schema and DTD for schemas described herein.
4.3.10 XML Representation of Annotation Schema Components

Mathematical Markup Language (MathML) Version 2.0
W3C Proposed Recommendation 08 January 2001
This version:
http://www.w3.org/TR/2001/PR-MathML2-20010108
Also available as: HTML zip archive, XHTML zip archive, XML zip archive, PDF
(screen), PDF (paper)
`

-----Original Message-----
From: comp.lang.ada-admin@ada.eu.org
[mailto:comp.lang.ada-admin@ada.eu.org]On Behalf Of Robert Dewar
Sent: Saturday, January 20, 2001 6:25 AM
To: comp.lang.ada@ada.eu.org
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings


In article <94a2jj$tc2$1@nnrp1.deja.com>,
  mark_lundquist@my-deja.com wrote:
> I think the idea of embedded hyperlinks in comments to
> navigate out to supporting documentation of the kind you
> mention could really be
> worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)

Generally I much prefer ALL technical documentation (as opposed
to user documentation) of the code to be in the code. Why?
Simple, in my experience VERY few programmers have the
discipline to maintain external documents, so they quickly get
out of sync and become completely useless.

It is hard enough for most people to be diligent about
maintaining comments and documentation that *are* part of
the source code.

You really have to develop the exact opposite opinion from
"comments don't really matter and have no effect", and consider
that a bad spelling in a comment is a real bug :-) Sure a bad
spelling is not serious, but the attitude that will not
tolerate bad spelling in program comments is one that goes
along with a commitment to maintaining good internal
documentation.


Sent via Deja.com
http://www.deja.com/

RE: Escape Sequences in Strings

[Jean Cohen]

>===== Original Message From Marin David Condic <mcondic.nospam@acm.org> =====
>John English wrote:
>
>> Hey guys, I agree completely, but I wanted to give a *short* answer,
>> not a complete package hierarchy with all the trimmings... and I
>> said it wasn't the way to go anyway... Give us a break!
>
>Good point. Sometimes we tend to "over answer" a question, possibly leading
>a newbie to believe that Ada is just too complicated to do what they want.
>With the original question, I thought the best thing was to explain how to
>do what the questioner wanted to do - use escape codes in a string.
>Presumably, if he learns this much, Ada is now useful to him. As he moves
>along with learning the language, it will probably become clear that there
>are better ways of structuring code to manipulate the cursor. Possibly, he
>was already in the process of building such a package and just wanted to
>know how to implement the low-level features? (Even in C++, you'd isolate
>this kind of thing at a low level - or learn rather quickly that you
>*should* have! :-)
>
>Let's keep the life of a newbie comfortable and possibly just suggest that
>there *are* better ways and wait to see if they ask...

Yours and others replies were very helpful regarding my original question. 
John English answered my post just as I expected an answer to be like. The 
additional comments were nevertheless helpful as well (specifically the 
mention of the Latin1 character set and streams), since they illustrate a 
little of "The Ada Way" of doing things. So again - thank you all!

Kind regards,
Jean Cohen