[mercury-users] Custom declarations and preprocessors.

[Tomas By]

Robert Ernst Johann JESCHOFNIK writes:
> Literate programming addresses a different issue.

Literate programming addresses all these issues and more.

Some LP tools can make indexes automatically. (some can not...)

Tyson Dowd writes:
> Good for writing descriptive text, e.g. tutorials and papers.
> 
> Not so good for generating summary tables of predicate names, types
> modes, determinisms, short descriptions of their function, etc.

Some LP tools do this.

There is a trade-off here. If the tool understands the langauge syntax
you can generate tables but you can (typically) only do it for one
language, and the tool might mess up your formatting or require some
specific style. With a language independent tool you have complete
control over the output code source files and you can mix languages.

And what has this got to do with `doc' declarations? To retrieve all
the information you list above the tool has to parse the code, surely?
(except the `short description' which comes from the doc declaration,
I suppose)

Tyson Dowd also writes:
> There's not much difference between writing a nice formal bit of
> TeX/HTML/whatever in a literate program and writing a :- doc that
> can be turned into the same.

I disagree. In my literate programs many procedures have no
documentation at all. Some procedures might have a couple of pages
including (Latex) figures and stuff. This reflects the fact that some
things are obvious and others are not.

The main difference, as I see it, between LP and everything else that
has been mentioned is that LP gives you (much) better aesthetic
control over the resulting human readable document. It is prefectly
possible to actually write coherent text and present the code where it
fits in and makes sense.

One thing I'm currently experimenting with is using a home-brewed
combination of LP-tool macros and Latex definitions to collect all
information about each specific error message in one place.

| \begin{error}
|
| @$@<Error term: doc not found@>==@{doc_not_found(string)@}
|
| @$@<Error code: doc not found@>==@{@-
| fof_msg2string(doc_not_found(Name),Str) :-
|   format("document not found: [%s]",[s(Name)],Str).
| @}
|
| @$@<Msgentry (error): doc not found@>==@{@-
| @<Message@>@(
| @"document not found: <replaceable>name</replaceable>@" @,
| @"There is no document with the specified external id.@" @,
| @"fof@" @,
| @"error@" @)
| @}
|
| \end{error}

The two first pieces are Mercury code and the last one is expanded to
(a xxxxload of) SGML Docbook code. In the printed literate program
this is surrounded by a box so that it stands out nicely.

Doing it this way makes it easy to keep the error message string in
the software and the error message quoted in the manual synchronised,
and, since the whole `error' block is close to the code that generates
the error, it helps in keeping the description close to actual fact.

<end of digression>

But, come to think of it, as long as you don't make the `doc'
declaration required, I can't see any problem with it, for me
personally.

Go right ahead. :-)

/Tomas
--------------------------------------------------------------------------
mercury-users mailing list
post:  mercury-users at cs.mu.oz.au
administrative address: owner-mercury-users at cs.mu.oz.au
unsubscribe: Address: mercury-users-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-users-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------