[m-dev.] For review: new extras module for generating tgif .obj files

[Fergus Henderson]

On 11-Mar-2001, Ralph Becket <ralphbecket at hotmail.com> wrote:
> Estimated hours taken: 3
> 
> This module is used to generate .obj files in a form suitable
> for the Tgif drawing package.  This should primarily be useful
> for generating specialized data representations and algorithm
> animations.

The log message should include the names of all the files
changed/added/deleted.

The log message should include a "Branches:" line
(see <http://www.cs.mu.oz.au/research/mercury/mailing-lists/mercury-developers/mercury-developers.0103/0030.html>).

If you add a new module in the `extras' directory,
it should be mentioned in extras/README, NEWS, and RELEASE_NOTES.

The text that you have in the log message that you posted
should also go in the source code.

> tgif/tgif.m:
> %------------------------------------------------------------------------------%
...
> % Generates simple tgif .obj files.

You should explain what `tgif' is, and include a pointer for documentation
on `tgif'.  Also you should explain that these `.obj' files are different
from the kinds of `.obj' files that you normally find on a DOS/Windows
machine.
> :- type obj
>     --->    box(colour, fill, linewidth, int, int, int, int)  % x1, y1, x2, 
> y2
>     ;       oval(colour, fill, linewidth, int, int, int, int) % x1, y1, x2, 
> y2
>     ;       circle(colour, fill, linewidth, int, int, int)    % x, y, radius
>     ;       poly(colour, fill, linewidth, coords)             % [{x, y}, 
> ...]
>     ;       line(colour, linewidth, int, int, int, int)       % x1, y1, x2, 
> y2
>     ;       arrow(colour, linewidth, int, int, int, int)      % x1, y1, x2, 
> y2
>     ;       text(colour, font, size, justification, int, int, string) % x, y
>     .

You should document what the type `obj' represents.

> :- pred write_objs(objs, io__state, io__state).
> :- mode write_objs(in, di, uo) is det.

You should document what that predicate does.

For example, does it write to the current text output
or to the current binary output?

Wouldn't it be better to provide a version of this which took a file name as
an additional argument, and handled the opening/closing of the file?

> %------------------------------------------------------------------------------%
> write_objs(Objs) -->
>     io__write_string("\
> %%TGIF 2.16-p9
> state(1,32,100,0,0,0,4,0,10,1,1,0,0,1,1,1,0,'Courier',0,17,0,0,1,10,0,0,1,1,0,16,1,0,1,1,1,1,1485,1050).

The comments here should explain what all those magic numbers there are for.

> %%
> %% @(#)$Header$
> %% %W%
> %%

$Header$ is a cvs/rcs keyword.

Genenerally our policy has been to avoid using them, since they typically cause
more trouble than they're worth (e.g. leading to spurious differences when
comparing different checked-out workspaces).  Instead we include the CVS
directories, which contain the revision numbers, in our source distributions.

Is there some particular reason why you want to include this one here?

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
                                    |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------