Noi and I talked about some of the restrictions that the current HTML
generator imposes on the structure of the generated HTML. Here is a proposal
for extending the syntax of the MRL descriptions to address these shortcomings.
Before that, here is the rationale for generating the documentation directly
from the contents of the MRL file:
- Consistency 1: all documentation will have a consistent format.
- Consistency 2: when we change the MRL, the documentation will be easier to
maintain up to date.
- Ease of changing formatting conventions: in the future we might want to
change the formatting conventions, and it will involve changing the generator
only.
- Automatic generation of cross-links: the current generator automatically
generates links to the types of the attributes. In the future we can add
cross-links from an object to all the attributes that use it as a type.
- Automatic generation of indices of objects and enumerations.
- Ability to generate differently sorted documents (alphabetical, by
sub-model, etc).
- Development environment help information: in addition to the HTML-based
documentation I think it will be neat to show the help strings when the
developer is authoring an object: if they are editing attribute X, we can show
them the documentation for attribute X.
Currently the documentation is generated from the model-server information in
a fairly simple way. For each object, we output the object doc string, and for
each attribute we output its doc string. While outputing the doc string we
perform the following substitutions:
/ob{xxx} is translated into an HTML reference to object xxx.
/at{xxx} ditto for attributes.
/en{xxx} ditto for enumerations.
/em{xxx} <em>xxx</em>
The new proposal will allow more control over the documentation generation:
- Each documentation string will be in HTML source code with the additions
described below.
- Only <p>, <em>, <ul>, <li> is allowed (maybe a few more, but goal is to keep
it small).
- <ob>xxx<ob>, <at>xxx</at>, <enum>xxx</enum> will be used to refere to
objects attributes and enumerations, and the translator will substitute the
appropriate HTML.
- There will be a new markup tags to document the attributes (see examples)
Below is an example of the mrl source file. Note the following things:
- we don't use strings to mark the documentation strings. Strings cannot be
used to demark the doc strings because strings are used within the HTML source
for other things, and it would be a pain to quote them.
- we need to put the <p> between paragraphs (each body is html source).
- THe attributes documentation is not separate from the object documentation.
The new markup is the following:
<MMC></MMC> for attribute categories (MMC is short for MM Categories). It
will be translated in <H3></H3> or something similar.
<attlist> </attlist> for a list of attributes
<attdef name= "xxx"> for attribute definition. This will be translated into
the HTML for the attribute, type, multi_valued, inheritance, etc.
<attdoc> this is for the documentation string.
This is similar to the use of <DL> lists
<attlist> -- <DL>
<attdef> -- <DT>
<attdoc> -- <DD>
------------------------
// Begin MRL file:
Description Reference {
<em>References</em> provide a convenient way for specifying the layout
for replicated parts by specifying that the replications should fill a
grid, or by specifying that the replications should be laid out
according to some other replication which is already laid out (e.g.,
specifying that an icon should be placed to the right of every other
element of a list).
<P>
It is possible to specify multiple references in a replication
object. A common case is to use two references, containing a vertical
and a horizontal grid. The effect is that elements are laid out in
rows according to the vertical grid. When the columns in the vertical
grid are exhausted, the next row in the horizontal grid is used. In
general, the use of multiple references supports the specification of
a large variety of layouts.
<MMC> References </MMC>
The attributes in this category bla, bla, bla
<attlist>
<attdef name= "grid_reference">
<attdoc>
Specifies the grid on which the
layout is based. The set of parts will be placed on the grid lines
according to <at>end_condition</at> and <at>init_procedure</at> attributes.
</attdoc>
<attdef name= "replication_reference">
<attdoc>
Specifies that the set of parts should be laid out according to the
parts of another replication (e.g., to the right of each part in the
other replication).
<attdef name= "init_index">
<attdoc>
The <em>init_index</em> specifies which grid
line or replication element should be used to place the first element
in this reference, which by default is the first one.
</attlist>
<MMC> "Advanced features" </MMC>
The attributes in this category bla, bla, bla
<attlist>
<attdef name= "end_condition">
<attdoc>
The <em>end_condition</em> specifies when
to stop using this reference for placing objects (e.g., when reaching
the last column in a vertical grid).
<attdef name= "init_procedure">
<attdoc>
The <em>init_procedure<em> is an
advanced feature that provides more flexibility for specifying the
<at>init_index</at> by allowing a procedure to be called, rather than
always using the same init_index.
</attlist>
};
// End MRL file:
----------------------------------
Here is the HTML file that would get generated.
Questions:
- What do you think? This would allow more flexibility.
- One implementation for the MRL parser would be to put the whole string in
the documentation for the object, and leave the doc for the attributes empty.
- The html generator would do fairly simple text substitution.
- We lose the ability to separate the docs for the attributes.
- The other thing is that in order to generate anything for an attribute you
have to list is with an attdef. I don't think this is a big deal.
----------------------------------
<H2> <A NAME="Reference"> <EM>Object</EM> Reference</A></H2>
<EM>References</EM> provide a convenient way for specifying the layout
for replicated parts by specifying that the replications should fill a
grid, or by specifying that the replications should be laid out
according to some other replication which is already laid out (e.g.,
specifying that an icon should be placed to the right of every other
element of a list).
<P>
It is possible to specify multiple references in a replication
object. A common case is to use two references, containing a vertical
and a horizontal grid. The effect is that elements are laid out in
rows according to the vertical grid. When the columns in the vertical
grid are exhausted, the next row in the horizontal grid is used. In
general, the use of multiple references supports the specification of
a large variety of layouts.
<H3>References</H3>
The references attributes bla, bla, bla
<DL>
<DT><B><A NAME="replication_reference">replication_reference</A></B>
<DD><I>type: </I>Object<Replication>,
<EM>Rule_Like</EM>
<DD>Specifies that the set of
parts should be laid out according to the parts of another replication
(e.g., to the right of each part in the other replication).
<DT><B><A NAME="grid_reference">grid_reference</A></B>
<DD><I>type: </I>Object<Grid>,
<EM>Rule_Like</EM><DD>Specifies the grid on which the
layout is based. The set of parts will be placed on the grid lines
according to end_condition
and init_procedure attributes.
<DT><B><A NAME="init_index">init_index</A></B>
<DD><I>type: </I>Long, <EM>Rule_Like</EM><DD>The <EM>init_index</EM> specifies
which grid
line or replication element should be used to place the first element
in this reference, which by default is the first one.
</DL>
<H3>Advanced Features</H3>
These attributes bla, bla, bla
<DL>
<DT><B><A NAME="end_condition">end_condition</A></B>
<DD><I>type: </I>Object<Expression>,
<EM>Rule_Like</EM><DD>The <EM>end_condition</EM> specifies when
to stop using this reference for placing objects (e.g., when reaching
the last column in a vertical grid).
<DT><B><A NAME="init_procedure">init_procedure</A></B>
<DD><I>type: </I>Object<Expression>, <EM>
Rule_Like</EM><DD>The <EM>init_procedure</EM> is an
advanced feature that provides more flexibility for specifying the
init_index by allowing a procedure to be called,
rather than
always using the same init_index.
</DL>
<HR>
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