From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,81054609038e88e3 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news2.google.com!fu-berlin.de!uni-berlin.de!not-for-mail From: Nick Roberts Newsgroups: comp.lang.ada Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse Date: Sat, 09 Oct 2004 22:47:22 +0100 Message-ID: <2sr4jaF1od20uU1@uni-berlin.de> References: <2sqmccF1oit5sU1@uni-berlin.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Trace: news.uni-berlin.de WEGviYpvSP50RNFhW8DhMQ7ERET7OtGA3wwz4OAJf6tzngUH0= User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.2) Gecko/20040803 X-Accept-Language: en-us, en In-Reply-To: Xref: g2news1.google.com comp.lang.ada:4966 Date: 2004-10-09T22:47:22+01:00 List-Id: Pascal Obry wrote: > I'm just worried that the original source code instrumented with "-- " > (unindented), "--+ " and "--- " plus the ${} macros would not be really easy > to read. Do you have small example of an instrumented code ? This is my idea of what the beginning of a package specification might look like after being reformatted. I've not shown the expansion of "gmgpl.txt" but I'm sure you can imagine the usual message. ~~~ ----------------------------------------------------------------------------------------------- -- {Titian.Color} package specification -- Copyright (C) 2004 Nicholas James Roberts (South Croydon, Surrey, UK). --+gmgpl.txt ----------------------------------------------------------------------------------------------- -- =####= Color =####= -- Titian uses a color system which accomodates the fact that many computer display systems can -- only show a limited number of different colors at a time, whilst others can show an -- unlimited number. For the former kind of display systems, the set of colors which can be -- displayed is generally called a 'palette'. The latter display systems are often described -- as 'true color' systems; the Titian term for them is that they have *'direct color'. -- Titian ensures that the programmer has the choice of using direct color values or colors -- selected from a palette, for all drawing operations. The former option will be slightly -- more efficient for direct color contexts, and may be more convenient regardless of the -- context. The latter option will be more efficient for contexts which do not have direct -- color (but will be reasonably efficient for contexts that do). For maximum efficiency with -- all possible contexts, the programmer could program two different algorithms for contexts -- with and without direct color. -- The basic color definitions are collected in this package ({Titian.Color}). Other -- color-related packages are {Titian.Color.CMYK} and {Titian.Color.HSL}. The -- color-related graphics context primitive operations are declared in the package -- {Titian.Raster_IO}. -- The term *'palette' is used for any set of distinct colors, as well as for the particular -- set of colors associated with a graphics context. -- Dealing with color in a way which will be suitable for the widest range of devices presents -- bit of a challenge: different devices have widely varying ways of supporting color (e.g. -- from those which have no colors at all, to video adapters which support a plethora of -- different modes, each with its own combination of bit-planes, palette sizes, and so on). I -- think there is a necessity to support the sophisticated color options many devices provide -- - it would surely be a shame not to allow programs to take full advantage of them - but not -- to the extent that overly complicates life for the poor beleaguered application programmer. -- Furthermore, the facilities provided by the proposed binding for color manipulation must be -- reasonably efficient. To this end, I have devised a system which hopefully allows -- programmers the best of both worlds. -- I hope the term direct color (defined just above) will be considered reasonably neutral. -- I need help with the color systems. Also, I am completely in the dark as to the ins and -- outs of color correction: I would appreciate help in this area. ----------------------------------------------------------------------------------------------- with ???; ----------------------------------------------------------------------------------------------- package Titian.Color is pragma Pure; ----------------------------------------------------------------------------------------------- -- =###= The {Color_Error} Exception =###= -- There is one color-related exception, {Color_Error}. Color_Error: exception; -- The {Color_Error} exception is raised if: -- * an attempt to engage a color in a palette fails (normally because the palette doesn't -- have enough free slots); -- * an attempt is made to use a color selector for an invalid slot (one which is neither -- fixed nor has been engaged); -- * an attempt is made to release fixed colors; -- * a color conversion cannot be effected, either because the calculation would be too -- difficult (or slow), or because the destination type cannot hold a color value -- corresponding (closely enough) to the color being converted. ----------------------------------------------------------------------------------------------- -- =###= Basic Color Descriptor =###= -- The type {Basic_Color} holds color values in the familiar Red-Green-Blue, or *'RGB', system -- of color representation, with the addition of an *'alpha value', which can be used to -- control the extent to which the background of an image is allowed to show through. The RGB -- system with alpha values can be termed the *'RGBA' color system. type Light_Level is delta 1.0/2**32 range 0.0 .. 1.0; -- implementation defined delta type Alpha_Level is delta 1.0/2**32 range 0.0 .. 1.0; -- implementation defined delta for Light_Level'Size use 32; -- implementation defined for Alpha_Level'Size use 32; -- implementation defined type Basic_Color is record Red, Green, Blue: Light_Level; Alpha: Alpha_Level := 1.0; end record; for Basic_Color'Size use 32*4; -- implementation defined ~~~ I think my idea for macro substitution (${...}) is not so clever, and could be dropped. Maybe =###= could be used to delimit titles. Possibly --- at the beginning of a line could be expanded to a line across. There would have to be special logic to avoid trying to word-wrap lines across! The lone * represents a bullet (for a list item). The form *'foo' is intended to enter the word foo into a cross-index. Obviously this is only a tiny example. The syntax of the macros (if I keep them), would perhaps need to be $LINE{...} where the ... is replaced by the correct value. The idea behind the macros was so that you could write something like: if Error_Detected then Put_Line (Current_Error, "Error in $LINE{} $FILE{}"); else ... If the Put_Line happened to be on line 234 of the file "wibble.adb", then the above would be expanded to: if Error_Detected then Put_Line (Current_Error, "Error in $LINE{234} $FILE{wibble.adb}"); else ... I'm not quite sure if this would be worth it. -- Nick Roberts