Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Nick Roberts <nick.roberts@acm.org>]

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