* Escape Sequences in Strings @ 2000-11-15 0:00 Jean Cohen 2000-11-15 0:00 ` Preben Randhol ` (4 more replies) 0 siblings, 5 replies; 94+ messages in thread From: Jean Cohen @ 2000-11-15 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 Escape Sequences in Strings Jean Cohen @ 2000-11-15 0:00 ` Preben Randhol 2000-11-15 0:00 ` Marin David Condic ` (3 subsequent siblings) 4 siblings, 0 replies; 94+ messages in thread From: Preben Randhol @ 2000-11-15 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 Escape Sequences in Strings Jean Cohen 2000-11-15 0:00 ` Preben Randhol @ 2000-11-15 0:00 ` Marin David Condic 2000-11-16 0:00 ` Ada Streams usage (was Escape Sequences in Strings) Marc A. Criley 2000-11-15 0:00 ` Escape Sequences in Strings John English ` (2 subsequent siblings) 4 siblings, 1 reply; 94+ messages in thread From: Marin David Condic @ 2000-11-15 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Ada Streams usage (was Escape Sequences in Strings) 2000-11-15 0:00 ` Marin David Condic @ 2000-11-16 0:00 ` Marc A. Criley 2000-11-16 0:00 ` Marin David Condic [not found] ` <igh81t8b3hdrsc167do6qr0h1joa73c1jr@borpin.co.uk> 0 siblings, 2 replies; 94+ messages in thread From: Marc A. Criley @ 2000-11-16 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-16 0:00 ` Ada Streams usage (was Escape Sequences in Strings) Marc A. Criley @ 2000-11-16 0:00 ` Marin David Condic 2000-11-16 0:00 ` Ted Dennison [not found] ` <igh81t8b3hdrsc167do6qr0h1joa73c1jr@borpin.co.uk> 1 sibling, 1 reply; 94+ messages in thread From: Marin David Condic @ 2000-11-16 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-16 0:00 ` Marin David Condic @ 2000-11-16 0:00 ` Ted Dennison 2000-11-16 0:00 ` Marin David Condic 0 siblings, 1 reply; 94+ messages in thread From: Ted Dennison @ 2000-11-16 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-16 0:00 ` Ted Dennison @ 2000-11-16 0:00 ` Marin David Condic 2000-11-16 0:00 ` Ted Dennison 0 siblings, 1 reply; 94+ messages in thread From: Marin David Condic @ 2000-11-16 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-16 0:00 ` Marin David Condic @ 2000-11-16 0:00 ` Ted Dennison 2000-11-16 0:00 ` Marin David Condic 0 siblings, 1 reply; 94+ messages in thread From: Ted Dennison @ 2000-11-16 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-16 0:00 ` Ted Dennison @ 2000-11-16 0:00 ` Marin David Condic 0 siblings, 0 replies; 94+ messages in thread From: Marin David Condic @ 2000-11-16 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
[parent not found: <igh81t8b3hdrsc167do6qr0h1joa73c1jr@borpin.co.uk>]
* Re: Ada Streams usage (was Escape Sequences in Strings) [not found] ` <igh81t8b3hdrsc167do6qr0h1joa73c1jr@borpin.co.uk> @ 2000-11-18 0:00 ` Marin David Condic 2000-11-18 0:00 ` David Kristola 2000-11-19 0:00 ` Ted Dennison 0 siblings, 2 replies; 94+ messages in thread From: Marin David Condic @ 2000-11-18 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-18 0:00 ` Marin David Condic @ 2000-11-18 0:00 ` David Kristola 2000-11-19 0:00 ` Marin David Condic 2000-11-19 0:00 ` Ted Dennison 1 sibling, 1 reply; 94+ messages in thread From: David Kristola @ 2000-11-18 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-18 0:00 ` David Kristola @ 2000-11-19 0:00 ` Marin David Condic 2000-11-19 0:00 ` Marin David Condic 0 siblings, 1 reply; 94+ messages in thread From: Marin David Condic @ 2000-11-19 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Marin David Condic @ 2000-11-19 0:00 ` Marin David Condic 2000-11-20 0:00 ` Brian Orpin 0 siblings, 1 reply; 94+ messages in thread From: Marin David Condic @ 2000-11-19 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Marin David Condic @ 2000-11-20 0:00 ` Brian Orpin 2000-11-20 0:00 ` Marin David Condic 0 siblings, 1 reply; 94+ messages in thread From: Brian Orpin @ 2000-11-20 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-20 0:00 ` Brian Orpin @ 2000-11-20 0:00 ` Marin David Condic 0 siblings, 0 replies; 94+ messages in thread From: Marin David Condic @ 2000-11-20 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-18 0:00 ` Marin David Condic 2000-11-18 0:00 ` David Kristola @ 2000-11-19 0:00 ` Ted Dennison 2000-11-19 0:00 ` Marin David Condic 1 sibling, 1 reply; 94+ messages in thread From: Ted Dennison @ 2000-11-19 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Ted Dennison @ 2000-11-19 0:00 ` Marin David Condic 2000-11-19 0:00 ` Robert Dewar 2000-11-19 0:00 ` Ted Dennison 0 siblings, 2 replies; 94+ messages in thread From: Marin David Condic @ 2000-11-19 0:00 UTC (permalink / raw) To: Ted Dennison 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Marin David Condic @ 2000-11-19 0:00 ` Robert Dewar 2000-11-20 0:00 ` Marin David Condic 2000-11-20 0:00 ` Randy Brukardt 2000-11-19 0:00 ` Ted Dennison 1 sibling, 2 replies; 94+ messages in thread From: Robert Dewar @ 2000-11-19 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Robert Dewar @ 2000-11-20 0:00 ` Marin David Condic 2000-11-21 0:00 ` Robert Dewar 2000-11-20 0:00 ` Randy Brukardt 1 sibling, 1 reply; 94+ messages in thread From: Marin David Condic @ 2000-11-20 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-20 0:00 ` Marin David Condic @ 2000-11-21 0:00 ` Robert Dewar 0 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2000-11-21 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Robert Dewar 2000-11-20 0:00 ` Marin David Condic @ 2000-11-20 0:00 ` Randy Brukardt 2000-11-21 0:00 ` Ted Dennison ` (2 more replies) 1 sibling, 3 replies; 94+ messages in thread From: Randy Brukardt @ 2000-11-20 0:00 UTC (permalink / raw) 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) ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-20 0:00 ` Randy Brukardt @ 2000-11-21 0:00 ` Ted Dennison 2000-11-21 0:00 ` Randy Brukardt 2000-11-21 1:31 ` Robert Dewar 2000-11-21 1:33 ` Robert Dewar 2 siblings, 1 reply; 94+ messages in thread From: Ted Dennison @ 2000-11-21 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-21 0:00 ` Ted Dennison @ 2000-11-21 0:00 ` Randy Brukardt 0 siblings, 0 replies; 94+ messages in thread From: Randy Brukardt @ 2000-11-21 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-20 0:00 ` Randy Brukardt 2000-11-21 0:00 ` Ted Dennison @ 2000-11-21 1:31 ` Robert Dewar 2000-11-21 1:33 ` Robert Dewar 2 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2000-11-21 1:31 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-20 0:00 ` Randy Brukardt 2000-11-21 0:00 ` Ted Dennison 2000-11-21 1:31 ` Robert Dewar @ 2000-11-21 1:33 ` Robert Dewar 2000-11-21 0:00 ` Randy Brukardt 2 siblings, 1 reply; 94+ messages in thread From: Robert Dewar @ 2000-11-21 1:33 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-21 1:33 ` Robert Dewar @ 2000-11-21 0:00 ` Randy Brukardt 2000-11-22 5:00 ` Robert Dewar 0 siblings, 1 reply; 94+ messages in thread From: Randy Brukardt @ 2000-11-21 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-21 0:00 ` Randy Brukardt @ 2000-11-22 5:00 ` Robert Dewar 0 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2000-11-22 5:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Marin David Condic 2000-11-19 0:00 ` Robert Dewar @ 2000-11-19 0:00 ` Ted Dennison 2000-11-19 0:00 ` Robert Dewar 1 sibling, 1 reply; 94+ messages in thread From: Ted Dennison @ 2000-11-19 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Ada Streams usage (was Escape Sequences in Strings) 2000-11-19 0:00 ` Ted Dennison @ 2000-11-19 0:00 ` Robert Dewar 0 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2000-11-19 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 Escape Sequences in Strings Jean Cohen 2000-11-15 0:00 ` Preben Randhol 2000-11-15 0:00 ` Marin David Condic @ 2000-11-15 0:00 ` John English 2000-11-15 0:00 ` Robert Dewar 2001-01-12 13:18 ` Andrew Hately 2001-01-12 19:37 ` Escape Sequences in Strings tmoran 4 siblings, 1 reply; 94+ messages in thread From: John English @ 2000-11-15 0:00 UTC (permalink / raw) 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 ----------------------------------------------------------------- ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 ` Escape Sequences in Strings John English @ 2000-11-15 0:00 ` Robert Dewar 2000-11-15 0:00 ` Ehud Lamm 0 siblings, 1 reply; 94+ messages in thread From: Robert Dewar @ 2000-11-15 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 ` Robert Dewar @ 2000-11-15 0:00 ` Ehud Lamm 2000-11-16 0:00 ` John English 0 siblings, 1 reply; 94+ messages in thread From: Ehud Lamm @ 2000-11-15 0:00 UTC (permalink / raw) 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! ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 ` Ehud Lamm @ 2000-11-16 0:00 ` John English 2000-11-16 0:00 ` Tarjei T. Jensen 2000-11-16 0:00 ` Marin David Condic 0 siblings, 2 replies; 94+ messages in thread From: John English @ 2000-11-16 0:00 UTC (permalink / raw) 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 ----------------------------------------------------------------- ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-16 0:00 ` John English @ 2000-11-16 0:00 ` Tarjei T. Jensen 2000-11-16 0:00 ` Ken Garlington 2000-11-16 0:00 ` Marin David Condic 1 sibling, 1 reply; 94+ messages in thread From: Tarjei T. Jensen @ 2000-11-16 0:00 UTC (permalink / raw) 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, ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-16 0:00 ` Tarjei T. Jensen @ 2000-11-16 0:00 ` Ken Garlington 2000-11-16 0:00 ` Keith Thompson 2000-11-16 0:00 ` Marin David Condic 0 siblings, 2 replies; 94+ messages in thread From: Ken Garlington @ 2000-11-16 0:00 UTC (permalink / raw) "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). ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-16 0:00 ` Ken Garlington @ 2000-11-16 0:00 ` Keith Thompson 2000-11-16 0:00 ` Marin David Condic 1 sibling, 0 replies; 94+ messages in thread From: Keith Thompson @ 2000-11-16 0:00 UTC (permalink / raw) "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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-16 0:00 ` Ken Garlington 2000-11-16 0:00 ` Keith Thompson @ 2000-11-16 0:00 ` Marin David Condic 1 sibling, 0 replies; 94+ messages in thread From: Marin David Condic @ 2000-11-16 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-16 0:00 ` John English 2000-11-16 0:00 ` Tarjei T. Jensen @ 2000-11-16 0:00 ` Marin David Condic 1 sibling, 0 replies; 94+ messages in thread From: Marin David Condic @ 2000-11-16 0:00 UTC (permalink / raw) 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 ====================================================================== ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 Escape Sequences in Strings Jean Cohen ` (2 preceding siblings ...) 2000-11-15 0:00 ` Escape Sequences in Strings John English @ 2001-01-12 13:18 ` Andrew Hately 2001-01-12 20:03 ` Keith Thompson 2001-01-12 19:37 ` Escape Sequences in Strings tmoran 4 siblings, 1 reply; 94+ messages in thread From: Andrew Hately @ 2001-01-12 13:18 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-12 13:18 ` Andrew Hately @ 2001-01-12 20:03 ` Keith Thompson 2001-01-18 8:29 ` Lao Xiao Hai 0 siblings, 1 reply; 94+ messages in thread From: Keith Thompson @ 2001-01-12 20:03 UTC (permalink / raw) 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!! ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-12 20:03 ` Keith Thompson @ 2001-01-18 8:29 ` Lao Xiao Hai 2001-01-18 15:22 ` Robert Dewar 0 siblings, 1 reply; 94+ messages in thread From: Lao Xiao Hai @ 2001-01-18 8:29 UTC (permalink / raw) 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!! ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-18 8:29 ` Lao Xiao Hai @ 2001-01-18 15:22 ` Robert Dewar 2001-01-18 22:43 ` Randy Brukardt 2001-01-21 11:54 ` Dale Stanbrough 0 siblings, 2 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-18 15:22 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-18 15:22 ` Robert Dewar @ 2001-01-18 22:43 ` Randy Brukardt 2001-01-21 11:54 ` Dale Stanbrough 1 sibling, 0 replies; 94+ messages in thread From: Randy Brukardt @ 2001-01-18 22:43 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-18 15:22 ` Robert Dewar 2001-01-18 22:43 ` Randy Brukardt @ 2001-01-21 11:54 ` Dale Stanbrough 2001-01-21 22:35 ` directly accessing DOS screen memory (was: Re: Escape Sequences in Strings) Jeffrey Carter 1 sibling, 1 reply; 94+ messages in thread From: Dale Stanbrough @ 2001-01-21 11:54 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* directly accessing DOS screen memory (was: Re: Escape Sequences in Strings) 2001-01-21 11:54 ` Dale Stanbrough @ 2001-01-21 22:35 ` Jeffrey Carter 0 siblings, 0 replies; 94+ messages in thread From: Jeffrey Carter @ 2001-01-21 22:35 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2000-11-15 0:00 Escape Sequences in Strings Jean Cohen ` (3 preceding siblings ...) 2001-01-12 13:18 ` Andrew Hately @ 2001-01-12 19:37 ` tmoran 2001-01-13 1:38 ` Robert Dewar 4 siblings, 1 reply; 94+ messages in thread From: tmoran @ 2001-01-12 19:37 UTC (permalink / raw) > 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-12 19:37 ` Escape Sequences in Strings tmoran @ 2001-01-13 1:38 ` Robert Dewar 2001-01-13 6:48 ` tmoran 0 siblings, 1 reply; 94+ messages in thread From: Robert Dewar @ 2001-01-13 1:38 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-13 1:38 ` Robert Dewar @ 2001-01-13 6:48 ` tmoran 2001-01-13 18:36 ` Robert Dewar 0 siblings, 1 reply; 94+ messages in thread From: tmoran @ 2001-01-13 6:48 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Escape Sequences in Strings 2001-01-13 6:48 ` tmoran @ 2001-01-13 18:36 ` Robert Dewar 2001-01-16 3:30 ` Examples in Docs, was " peter_richtmyer 0 siblings, 1 reply; 94+ messages in thread From: Robert Dewar @ 2001-01-13 18:36 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Examples in Docs, was Re: Escape Sequences in Strings 2001-01-13 18:36 ` Robert Dewar @ 2001-01-16 3:30 ` peter_richtmyer 2001-01-16 5:42 ` Robert Dewar ` (2 more replies) 0 siblings, 3 replies; 94+ messages in thread From: peter_richtmyer @ 2001-01-16 3:30 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 3:30 ` Examples in Docs, was " peter_richtmyer @ 2001-01-16 5:42 ` Robert Dewar 2001-01-16 20:44 ` mark_lundquist 2001-01-16 16:06 ` Examples in Docs Robert C. Leif, Ph.D. 2001-01-16 20:01 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist 2 siblings, 1 reply; 94+ messages in thread From: Robert Dewar @ 2001-01-16 5:42 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 5:42 ` Robert Dewar @ 2001-01-16 20:44 ` mark_lundquist 2001-01-16 22:43 ` Larry Kilgallen 2001-01-17 2:25 ` Robert Dewar 0 siblings, 2 replies; 94+ messages in thread From: mark_lundquist @ 2001-01-16 20:44 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 20:44 ` mark_lundquist @ 2001-01-16 22:43 ` Larry Kilgallen 2001-01-17 15:06 ` mark_lundquist 2001-01-17 2:25 ` Robert Dewar 1 sibling, 1 reply; 94+ messages in thread From: Larry Kilgallen @ 2001-01-16 22:43 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 22:43 ` Larry Kilgallen @ 2001-01-17 15:06 ` mark_lundquist 0 siblings, 0 replies; 94+ messages in thread From: mark_lundquist @ 2001-01-17 15:06 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 20:44 ` mark_lundquist 2001-01-16 22:43 ` Larry Kilgallen @ 2001-01-17 2:25 ` Robert Dewar 2001-01-17 15:28 ` mark_lundquist ` (2 more replies) 1 sibling, 3 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-17 2:25 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 2:25 ` Robert Dewar @ 2001-01-17 15:28 ` mark_lundquist 2001-01-17 16:20 ` Brian Rogoff 2001-01-17 22:10 ` Matthew Woodcraft 2 siblings, 0 replies; 94+ messages in thread From: mark_lundquist @ 2001-01-17 15:28 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 2:25 ` Robert Dewar 2001-01-17 15:28 ` mark_lundquist @ 2001-01-17 16:20 ` Brian Rogoff 2001-01-17 18:04 ` Wayne Lydecker 2001-01-18 3:44 ` Robert Dewar 2001-01-17 22:10 ` Matthew Woodcraft 2 siblings, 2 replies; 94+ messages in thread From: Brian Rogoff @ 2001-01-17 16:20 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 16:20 ` Brian Rogoff @ 2001-01-17 18:04 ` Wayne Lydecker 2001-01-17 19:23 ` BSCrawford 2001-01-19 0:01 ` tmoran 2001-01-18 3:44 ` Robert Dewar 1 sibling, 2 replies; 94+ messages in thread From: Wayne Lydecker @ 2001-01-17 18:04 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 18:04 ` Wayne Lydecker @ 2001-01-17 19:23 ` BSCrawford 2001-01-18 0:15 ` Jerry Petrey 2001-01-19 0:01 ` tmoran 1 sibling, 1 reply; 94+ messages in thread From: BSCrawford @ 2001-01-17 19:23 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 19:23 ` BSCrawford @ 2001-01-18 0:15 ` Jerry Petrey 0 siblings, 0 replies; 94+ messages in thread From: Jerry Petrey @ 2001-01-18 0:15 UTC (permalink / raw) 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 ----------------------------------------------------------------------------- ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 18:04 ` Wayne Lydecker 2001-01-17 19:23 ` BSCrawford @ 2001-01-19 0:01 ` tmoran 1 sibling, 0 replies; 94+ messages in thread From: tmoran @ 2001-01-19 0:01 UTC (permalink / raw) >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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 16:20 ` Brian Rogoff 2001-01-17 18:04 ` Wayne Lydecker @ 2001-01-18 3:44 ` Robert Dewar 2001-01-18 16:45 ` Brian Rogoff 1 sibling, 1 reply; 94+ messages in thread From: Robert Dewar @ 2001-01-18 3:44 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-18 3:44 ` Robert Dewar @ 2001-01-18 16:45 ` Brian Rogoff 2001-01-18 19:53 ` Robert Dewar 0 siblings, 1 reply; 94+ messages in thread From: Brian Rogoff @ 2001-01-18 16:45 UTC (permalink / raw) 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 :-) ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-18 16:45 ` Brian Rogoff @ 2001-01-18 19:53 ` Robert Dewar 2001-01-18 22:58 ` Georg Bauhaus ` (3 more replies) 0 siblings, 4 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-18 19:53 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-18 19:53 ` Robert Dewar @ 2001-01-18 22:58 ` Georg Bauhaus 2001-01-19 16:40 ` Robert Dewar 2001-01-19 7:49 ` Learning methods Anders Wirzenius ` (2 subsequent siblings) 3 siblings, 1 reply; 94+ messages in thread From: Georg Bauhaus @ 2001-01-18 22:58 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-18 22:58 ` Georg Bauhaus @ 2001-01-19 16:40 ` Robert Dewar 0 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-19 16:40 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Learning methods 2001-01-18 19:53 ` Robert Dewar 2001-01-18 22:58 ` Georg Bauhaus @ 2001-01-19 7:49 ` Anders Wirzenius 2001-01-19 18:57 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist 2001-01-21 12:05 ` Dale Stanbrough 3 siblings, 0 replies; 94+ messages in thread From: Anders Wirzenius @ 2001-01-19 7:49 UTC (permalink / raw) "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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-18 19:53 ` Robert Dewar 2001-01-18 22:58 ` Georg Bauhaus 2001-01-19 7:49 ` Learning methods Anders Wirzenius @ 2001-01-19 18:57 ` mark_lundquist 2001-01-21 12:05 ` Dale Stanbrough 3 siblings, 0 replies; 94+ messages in thread From: mark_lundquist @ 2001-01-19 18:57 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-18 19:53 ` Robert Dewar ` (2 preceding siblings ...) 2001-01-19 18:57 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist @ 2001-01-21 12:05 ` Dale Stanbrough 2001-01-21 15:35 ` Robert Dewar 3 siblings, 1 reply; 94+ messages in thread From: Dale Stanbrough @ 2001-01-21 12:05 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-21 12:05 ` Dale Stanbrough @ 2001-01-21 15:35 ` Robert Dewar 0 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-21 15:35 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 2:25 ` Robert Dewar 2001-01-17 15:28 ` mark_lundquist 2001-01-17 16:20 ` Brian Rogoff @ 2001-01-17 22:10 ` Matthew Woodcraft 2001-01-18 3:52 ` Robert Dewar 2 siblings, 1 reply; 94+ messages in thread From: Matthew Woodcraft @ 2001-01-17 22:10 UTC (permalink / raw) 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- ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 22:10 ` Matthew Woodcraft @ 2001-01-18 3:52 ` Robert Dewar 0 siblings, 0 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-18 3:52 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* RE: Examples in Docs 2001-01-16 3:30 ` Examples in Docs, was " peter_richtmyer 2001-01-16 5:42 ` Robert Dewar @ 2001-01-16 16:06 ` Robert C. Leif, Ph.D. 2001-01-16 21:29 ` mark_lundquist 2001-01-17 2:43 ` Robert Dewar 2001-01-16 20:01 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist 2 siblings, 2 replies; 94+ messages in thread From: Robert C. Leif, Ph.D. @ 2001-01-16 16:06 UTC (permalink / raw) To: comp.lang.ada 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* RE: Examples in Docs 2001-01-16 16:06 ` Examples in Docs Robert C. Leif, Ph.D. @ 2001-01-16 21:29 ` mark_lundquist 2001-01-18 0:50 ` Randy Brukardt 2001-01-18 17:24 ` J. David Bryan 2001-01-17 2:43 ` Robert Dewar 1 sibling, 2 replies; 94+ messages in thread From: mark_lundquist @ 2001-01-16 21:29 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs 2001-01-16 21:29 ` mark_lundquist @ 2001-01-18 0:50 ` Randy Brukardt 2001-01-18 16:46 ` mark_lundquist 2001-01-18 17:24 ` J. David Bryan 1 sibling, 1 reply; 94+ messages in thread From: Randy Brukardt @ 2001-01-18 0:50 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs 2001-01-18 0:50 ` Randy Brukardt @ 2001-01-18 16:46 ` mark_lundquist 0 siblings, 0 replies; 94+ messages in thread From: mark_lundquist @ 2001-01-18 16:46 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* RE: Examples in Docs 2001-01-16 21:29 ` mark_lundquist 2001-01-18 0:50 ` Randy Brukardt @ 2001-01-18 17:24 ` J. David Bryan 1 sibling, 0 replies; 94+ messages in thread From: J. David Bryan @ 2001-01-18 17:24 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* RE: Examples in Docs 2001-01-16 16:06 ` Examples in Docs Robert C. Leif, Ph.D. 2001-01-16 21:29 ` mark_lundquist @ 2001-01-17 2:43 ` Robert Dewar 2001-01-17 21:17 ` Robert C. Leif, Ph.D. 1 sibling, 1 reply; 94+ messages in thread From: Robert Dewar @ 2001-01-17 2:43 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* RE: Examples in Docs 2001-01-17 2:43 ` Robert Dewar @ 2001-01-17 21:17 ` Robert C. Leif, Ph.D. 0 siblings, 0 replies; 94+ messages in thread From: Robert C. Leif, Ph.D. @ 2001-01-17 21:17 UTC (permalink / raw) To: comp.lang.ada 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 3:30 ` Examples in Docs, was " peter_richtmyer 2001-01-16 5:42 ` Robert Dewar 2001-01-16 16:06 ` Examples in Docs Robert C. Leif, Ph.D. @ 2001-01-16 20:01 ` mark_lundquist 2001-01-17 10:59 ` Peter Richtmyer 2 siblings, 1 reply; 94+ messages in thread From: mark_lundquist @ 2001-01-16 20:01 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-16 20:01 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist @ 2001-01-17 10:59 ` Peter Richtmyer 2001-01-19 18:55 ` mark_lundquist 0 siblings, 1 reply; 94+ messages in thread From: Peter Richtmyer @ 2001-01-17 10:59 UTC (permalink / raw) <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 " ? :-) ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-17 10:59 ` Peter Richtmyer @ 2001-01-19 18:55 ` mark_lundquist 2001-01-20 14:24 ` Robert Dewar 0 siblings, 1 reply; 94+ messages in thread From: mark_lundquist @ 2001-01-19 18:55 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-19 18:55 ` mark_lundquist @ 2001-01-20 14:24 ` Robert Dewar 2001-01-20 14:36 ` Preben Randhol ` (3 more replies) 0 siblings, 4 replies; 94+ messages in thread From: Robert Dewar @ 2001-01-20 14:24 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 14:24 ` Robert Dewar @ 2001-01-20 14:36 ` Preben Randhol 2001-01-20 15:00 ` Robert Dewar 2001-01-20 19:02 ` Stephen Leake ` (2 subsequent siblings) 3 siblings, 1 reply; 94+ messages in thread From: Preben Randhol @ 2001-01-20 14:36 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 14:36 ` Preben Randhol @ 2001-01-20 15:00 ` Robert Dewar 2001-01-21 11:24 ` Preben Randhol 0 siblings, 1 reply; 94+ messages in thread From: Robert Dewar @ 2001-01-20 15:00 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 15:00 ` Robert Dewar @ 2001-01-21 11:24 ` Preben Randhol 2001-01-22 14:47 ` Ted Dennison 0 siblings, 1 reply; 94+ messages in thread From: Preben Randhol @ 2001-01-21 11:24 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-21 11:24 ` Preben Randhol @ 2001-01-22 14:47 ` Ted Dennison 2001-01-22 20:08 ` Preben Randhol 0 siblings, 1 reply; 94+ messages in thread From: Ted Dennison @ 2001-01-22 14:47 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-22 14:47 ` Ted Dennison @ 2001-01-22 20:08 ` Preben Randhol 2001-01-22 20:14 ` Preben Randhol 0 siblings, 1 reply; 94+ messages in thread From: Preben Randhol @ 2001-01-22 20:08 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-22 20:08 ` Preben Randhol @ 2001-01-22 20:14 ` Preben Randhol 0 siblings, 0 replies; 94+ messages in thread From: Preben Randhol @ 2001-01-22 20:14 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 14:24 ` Robert Dewar 2001-01-20 14:36 ` Preben Randhol @ 2001-01-20 19:02 ` Stephen Leake 2001-01-20 19:50 ` Georg Bauhaus 2001-01-21 11:35 ` Preben Randhol 2001-01-22 23:58 ` Mark Lundquist 2001-01-27 1:43 ` Increasing the readability of Ada was RE: Examples in Docs Robert C. Leif, Ph.D. 3 siblings, 2 replies; 94+ messages in thread From: Stephen Leake @ 2001-01-20 19:02 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 19:02 ` Stephen Leake @ 2001-01-20 19:50 ` Georg Bauhaus 2001-01-21 11:35 ` Preben Randhol 1 sibling, 0 replies; 94+ messages in thread From: Georg Bauhaus @ 2001-01-20 19:50 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 19:02 ` Stephen Leake 2001-01-20 19:50 ` Georg Bauhaus @ 2001-01-21 11:35 ` Preben Randhol 1 sibling, 0 replies; 94+ messages in thread From: Preben Randhol @ 2001-01-21 11:35 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 94+ messages in thread
* Re: Examples in Docs, was Re: Escape Sequences in Strings 2001-01-20 14:24 ` Robert Dewar 2001-01-20 14:36 ` Preben Randhol 2001-01-20 19:02 ` Stephen Leake @ 2001-01-22 23:58 ` Mark Lundquist 2001-01-27 1:43 ` Increasing the readability of Ada was RE: Examples in Docs Robert C. Leif, Ph.D. 3 siblings, 0 replies; 94+ messages in thread From: Mark Lundquist @ 2001-01-22 23:58 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 94+ messages in thread
* Increasing the readability of Ada was RE: Examples in Docs 2001-01-20 14:24 ` Robert Dewar ` (2 preceding siblings ...) 2001-01-22 23:58 ` Mark Lundquist @ 2001-01-27 1:43 ` Robert C. Leif, Ph.D. 3 siblings, 0 replies; 94+ messages in thread From: Robert C. Leif, Ph.D. @ 2001-01-27 1:43 UTC (permalink / raw) To: comp.lang.ada 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/ ^ permalink raw reply [flat|nested] 94+ messages in thread
end of thread, other threads:[~2001-01-27 1:43 UTC | newest] Thread overview: 94+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2000-11-15 0:00 Escape Sequences in Strings Jean Cohen 2000-11-15 0:00 ` Preben Randhol 2000-11-15 0:00 ` Marin David Condic 2000-11-16 0:00 ` Ada Streams usage (was Escape Sequences in Strings) Marc A. Criley 2000-11-16 0:00 ` Marin David Condic 2000-11-16 0:00 ` Ted Dennison 2000-11-16 0:00 ` Marin David Condic 2000-11-16 0:00 ` Ted Dennison 2000-11-16 0:00 ` Marin David Condic [not found] ` <igh81t8b3hdrsc167do6qr0h1joa73c1jr@borpin.co.uk> 2000-11-18 0:00 ` Marin David Condic 2000-11-18 0:00 ` David Kristola 2000-11-19 0:00 ` Marin David Condic 2000-11-19 0:00 ` Marin David Condic 2000-11-20 0:00 ` Brian Orpin 2000-11-20 0:00 ` Marin David Condic 2000-11-19 0:00 ` Ted Dennison 2000-11-19 0:00 ` Marin David Condic 2000-11-19 0:00 ` Robert Dewar 2000-11-20 0:00 ` Marin David Condic 2000-11-21 0:00 ` Robert Dewar 2000-11-20 0:00 ` Randy Brukardt 2000-11-21 0:00 ` Ted Dennison 2000-11-21 0:00 ` Randy Brukardt 2000-11-21 1:31 ` Robert Dewar 2000-11-21 1:33 ` Robert Dewar 2000-11-21 0:00 ` Randy Brukardt 2000-11-22 5:00 ` Robert Dewar 2000-11-19 0:00 ` Ted Dennison 2000-11-19 0:00 ` Robert Dewar 2000-11-15 0:00 ` Escape Sequences in Strings John English 2000-11-15 0:00 ` Robert Dewar 2000-11-15 0:00 ` Ehud Lamm 2000-11-16 0:00 ` John English 2000-11-16 0:00 ` Tarjei T. Jensen 2000-11-16 0:00 ` Ken Garlington 2000-11-16 0:00 ` Keith Thompson 2000-11-16 0:00 ` Marin David Condic 2000-11-16 0:00 ` Marin David Condic 2001-01-12 13:18 ` Andrew Hately 2001-01-12 20:03 ` Keith Thompson 2001-01-18 8:29 ` Lao Xiao Hai 2001-01-18 15:22 ` Robert Dewar 2001-01-18 22:43 ` Randy Brukardt 2001-01-21 11:54 ` Dale Stanbrough 2001-01-21 22:35 ` directly accessing DOS screen memory (was: Re: Escape Sequences in Strings) Jeffrey Carter 2001-01-12 19:37 ` Escape Sequences in Strings tmoran 2001-01-13 1:38 ` Robert Dewar 2001-01-13 6:48 ` tmoran 2001-01-13 18:36 ` Robert Dewar 2001-01-16 3:30 ` Examples in Docs, was " peter_richtmyer 2001-01-16 5:42 ` Robert Dewar 2001-01-16 20:44 ` mark_lundquist 2001-01-16 22:43 ` Larry Kilgallen 2001-01-17 15:06 ` mark_lundquist 2001-01-17 2:25 ` Robert Dewar 2001-01-17 15:28 ` mark_lundquist 2001-01-17 16:20 ` Brian Rogoff 2001-01-17 18:04 ` Wayne Lydecker 2001-01-17 19:23 ` BSCrawford 2001-01-18 0:15 ` Jerry Petrey 2001-01-19 0:01 ` tmoran 2001-01-18 3:44 ` Robert Dewar 2001-01-18 16:45 ` Brian Rogoff 2001-01-18 19:53 ` Robert Dewar 2001-01-18 22:58 ` Georg Bauhaus 2001-01-19 16:40 ` Robert Dewar 2001-01-19 7:49 ` Learning methods Anders Wirzenius 2001-01-19 18:57 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist 2001-01-21 12:05 ` Dale Stanbrough 2001-01-21 15:35 ` Robert Dewar 2001-01-17 22:10 ` Matthew Woodcraft 2001-01-18 3:52 ` Robert Dewar 2001-01-16 16:06 ` Examples in Docs Robert C. Leif, Ph.D. 2001-01-16 21:29 ` mark_lundquist 2001-01-18 0:50 ` Randy Brukardt 2001-01-18 16:46 ` mark_lundquist 2001-01-18 17:24 ` J. David Bryan 2001-01-17 2:43 ` Robert Dewar 2001-01-17 21:17 ` Robert C. Leif, Ph.D. 2001-01-16 20:01 ` Examples in Docs, was Re: Escape Sequences in Strings mark_lundquist 2001-01-17 10:59 ` Peter Richtmyer 2001-01-19 18:55 ` mark_lundquist 2001-01-20 14:24 ` Robert Dewar 2001-01-20 14:36 ` Preben Randhol 2001-01-20 15:00 ` Robert Dewar 2001-01-21 11:24 ` Preben Randhol 2001-01-22 14:47 ` Ted Dennison 2001-01-22 20:08 ` Preben Randhol 2001-01-22 20:14 ` Preben Randhol 2001-01-20 19:02 ` Stephen Leake 2001-01-20 19:50 ` Georg Bauhaus 2001-01-21 11:35 ` Preben Randhol 2001-01-22 23:58 ` Mark Lundquist 2001-01-27 1:43 ` Increasing the readability of Ada was RE: Examples in Docs Robert C. Leif, Ph.D.
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox