Suggestion: Conditionals

[GoogleCodeExporter]

Since there are hardly any issues left, I figured I would dig out some good
ideas for things that could be implemented. I have been digging around on a
"certain website"[1] and looking at what their users have suggested.

One idea is "conditionals" (based on this suggestion[2]):
While the original commenter's idea probably not the best choice (at least
implementation-wise), it made me remember that doxygen allows for
"conditional sections" (particularly the "internal" section). With this in
mind, here is my suggestion:

Extend the language to include (very) simple if/else statements, so you can
have an "internal" and a "external" representation of the same system based
on the same graph. Something like this

if INTERNAL
   /* Last week this involved a coffee break, but the "suits" decided a
dressingroom was better... 10 bugs says we have to change it again next
week. */
   T->dressingroom [ label="Dress up for the Iberian Dance" ]
   dressingroom->"Iberian Dance Task" [label="IbFandangoReq", URL="\ref
IbFandangoReq"];
else 
   /* The user does not need to know about the dressing room - the external
API is stable, which sadly cannot be said about the internal API. */
   T->"Iberian Dance Task" [label="IbFandangoReq", URL="\ref IbFandangoReq"];
endif

Also:

if implemented
   mscgen->doxygen [ label="Notify of new awesome feature" ];
   doxygen->doxygen [ label="New release supporting new awesome feature" ];
endif

These "variables" would be given as a command line argument (e.g. using
-D<variable> like most C-compilers) or alternatively via an environment
variable. Personally I think that both approaches should be supported for
now. If cmd-line arguments are present, the environment will be ignored -
otherwise the environment would be used.

The reason for this is simple: It would allow a new version of doxygen to
pass these values on to mscgen without knowing if it supports it (using the
environment). This way doxygen developer(s) do not have to worry about
"breaking" old setups where mscgen has not been upgraded and can (some what
easily) be able to provide this new feature. 

Of course, judging from the default "Doxyfile" they might just implement a
"MSCGEN_ARGS" or a "MSCGEN_SUPPORTS_CONDITIONALS" variable instead...[3]

To be honest, I am not sure how doxygen handles "if"s inside "msc" sections
- it may already be a feature when using doxygen. Nevertheless, I suggest
that the syntax would be identical, since if doxygen is actually already
parsing ifs inside "msc" sections, then we do not confuse doxygen - and if
it isn't, at least the user needs to learn one less "if-syntax".

Disadvantages: The parser/scanner may require substantial changes, since we
are no longer dealing with an "arclist" but an "arctree". The rest of the
code may not require (a lot of) change(s) - if the tree is flattened into a
list (discarding the unreachable branches) directly after the parser is done.

~Niels

[1] Shame on me: http://www.websequencediagrams.com/
[2]
http://websequencediagrams.uservoice.com/pages/9445-general/suggestions/251525-j
oin-command
[3] No ill intention ... They just have a lot of options in that file!

Original issue reported on code.google.com by NThykier@gmail.com on 18 Jul 2009 at 11:06

[GoogleCodeExporter]

I have examined the doxygen manual for the "conditional syntax". I believe it is
possible to keep all of the conditional handling inside the lexer/scanner - 
behaving
similarly to a C-preprocessor[1].

For better:
 * No modifications to the parser nor will a tree have to be flattened to a list
after parsing.
and for worse:
 * The other branches are not checked neither for syntax nor semantics. 

~Niels

[1] Except a real C-preproccesor allows for more advanced conditionals and is
probably implemented using a parser as well.

Original comment by NThykier@gmail.com on 25 Jul 2009 at 8:52

[GoogleCodeExporter]

Original comment by Michael....@gmail.com on 26 Jul 2009 at 2:46

• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

I think the C preprocessor can be used to do this already:

  cpp -DBG input.msc -o- | mscgen -i- -Tpng -o out.png

Any of the output lines which start with a # will be ignored by mscgen, so 
there's no problem there.

Additionally, Doxygen includes a C pre-processor which I guess could also be 
used to modify mscgen output in the case that it's used in that context.

Since other well-defined and effective pre-processors already exist, I think 
I'm going to try to follow the Unix mantra and make mscgen do one thing and do 
it well!

Original comment by Michael....@gmail.com on 18 Aug 2010 at 1:06

• Changed state: WontFix