I am writing the documentation for the presentation MRL and the following
issue came up. Some of the documentation strings are quite long, and they
contain references to other objects/enumeration/attributes defined in the MRL.
If we are thinking about generatin HTML from the documetation strings, it
would be useful if the documetation strings contain some way to generate HTML
references to other objects.
Example:
Description Color {
"\em{Color} models colors of graphical objects. All colors must be
modeled as sub-classes of \em{Color}: \ob{RGB_Color}, \ob{HSV_Color}
and \ob{Named_Color}."
};
Here I used \em to cause words to be emphasized, and \ob to refer to other
objects. The idea is that in the HTML these \xxx things will be translated
into the appropriate HTML code.
Several questions:
1- Is it a good idea to have these cross-references embedded in the text (I
think it is).
2- if the answer to 1- is yes, what should be the language to express these
references? Here are some ideas that come to mind:
-- Use HTML. So instead of \em{xxx} I would write <em>xxx</em>. I don't like
this way too much because things like \ob{xxx} become pretty horrible in HTML.
-- Use our own markup language from which we generate HTML. THis would be
easier to use, but creates the problem of having to parse the documentation
strings looking for our markup, and generating the appropriate HTML. I prefer
our own markup because it allows us to define semantic categories such as the
following:
\ob: to refer to other objects.
\att: to refer to attributes.
\enum: to refer to enumerations.
\enum_value: to refer to enumeration values.
\em: to emphasize text.
3- Question for HTML experts. Is there a way in HTML to define our own markup
keywords as macros? Example
<OB>XXX</OB>, which exapands into <A HREF="#XXX">XXX</A>.
Pedro Szekely
USC/ISI, 4676 Admiralty Way, Marina del Rey, CA 90292
Phone: 310/822-1511, Fax: 310/823-6714
URL: http://www.isi.edu/isd/szekely.html