Improvement to grammar display in the User Manual

[Timothy Lethbridge]

Hi,

I have overhauled how the 'Syntax' elements work in all the Umple user
manual pages.

Take a look at
http://cruise.eecs.uottawa.ca/umple/UmpleGrammar.html

This is the automatically-generated display of the grammar. As always, any
changes to the source grammar files will be reflected here. However, now
the display here is nicely coloured and formatted to make it much easier
to understand. Uses of rules also have links.

If you then look at other pages of the user manual, e.g.
http://cruise.eecs.uottawa.ca/umple/BasicStateMachines.html
you will see at the bottom the syntax relevant to that page.
From now on, insead of copying and pasting syntax into the @@syntax
section of the page definition, you just give the names of the rules that
are relevant. The docmentation builder will take care of inserting the
up-to-date rule definitions, with links to the master grammar.

This will be useful for Omar's thesis too, since he was criticised in his
defense for not making the grammar understadable enough. It may also be
useful for the theses of other students and for papers we publish.

Note that the syntax section now gets output after the examples. I find
that people mostly want to read examples, then look at the formal syntax.

- Tim

Timothy C. Lethbridge, PhD, P.Eng., I.S.P., CSDP
Professor of Software Engineering and Computer Science
/ Professeur Titulaire de gï¿œnie logiciel et d'informatique
Facultￜ de genie / Faculty of Engineering
University of Ottawa / Universitￜ d'Ottawa
Tel: 613-562-5800x6685 Fax: 613-562-5664 Mobile: 613-252-1850
http://www.eecs.uottawa.ca/~tcl

[Andrew Forward]

Looks great!  And I very pleased that we have continued to rely on auto-generated documentation to avoid the need for double-maintenance of the 'real' grammar, and the 'html' grammar.

andrew f

On Fri, Mar 30, 2012 at 12:44 AM, Timothy Lethbridge <t...@eecs.uottawa.ca> wrote:

Hi,

I have overhauled how the 'Syntax' elements work in all the Umple user manual pages.

Take a look at
http://cruise.eecs.uottawa.ca/umple/UmpleGrammar.html

This is the automatically-generated display of the grammar. As always, any changes to the source grammar files will be reflected here. However, now the display here is nicely coloured and formatted to make it much easier to understand. Uses of rules also have links.

If you then look at other pages of the user manual, e.g.
http://cruise.eecs.uottawa.ca/umple/BasicStateMachines.html
you will see at the bottom the syntax relevant to that page.
From now on, insead of copying and pasting syntax into the @@syntax section of the page definition, you just give the names of the rules that are relevant. The docmentation builder will take care of inserting the up-to-date rule definitions, with links to the master grammar.

This will be useful for Omar's thesis too, since he was criticised in his defense for not making the grammar understadable enough. It may also be useful for the theses of other students and for papers we publish.

Note that the syntax section now gets output after the examples. I find that people mostly want to read examples, then look at the formal syntax.

- Tim

Timothy C. Lethbridge, PhD, P.Eng., I.S.P., CSDP
Professor of Software Engineering and Computer Science

/ Professeur Titulaire de génie logiciel et d'informatique
Faculté de genie / Faculty of Engineering
University of Ottawa / Université d'Ottawa

Tel: 613-562-5800x6685   Fax: 613-562-5664    Mobile: 613-252-1850
http://www.eecs.uottawa.ca/~tcl

--
You received this message because you are subscribed to the Google Groups "Umple-Dev" group.
To post to this group, send an email to umpl...@googlegroups.com.
To unsubscribe from this group, send email to umple-dev+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/umple-dev?hl=en-GB.

--
aforward