[docs] "Synopsis" line in the documentation

Davor Ocelic docelic at mail.inet.hr
Wed Sep 22 06:29:09 EDT 2004


This is the situation: I am still pondering how to compose the Synopsis
lines for the elements.

Of all symbol types I can think of now, their relative difficulty is:
 - pragmas: easy (pragma something value)
 - globvars: appears to be easy (Variable something simple_value)
 - config directives: (TODO) I suppose moderately-difficult
 - tags: difficult
 - functions: dificult

The problem is I'm thinking about a general synopsis element which
would be able to cover all cases. Plain <synopsis> element is not
okay: it's verbatim (preserves line breaks and puts font to monospace)
and is not flexible.
The <cmdsynopsis> element seems okay, it's not verbatim and supports
a wide range of subelements (<group>, <arg>, <replaceable>, ...).

Now, the section "Symbol type" from each item, where you had examples
how to generally use the symbol group in question was moved to 
glossary entry, so we don't repeat that in every reference page.

That also means that repeating generic elements in the Synopsis
like makes no sense:

  For example, I would prefer putting just "{ 0 | 1 }" as Synopsis
  for a global variable, because it's already known that you need
  to write "Variable var_name " in front of that.
  If you count that we'll also be providing Perl (and mvasp?) syntax
  in the same section, we can remove *a lot* of redundancy and
  duplication this way.

So the synopsis line for say, the env tag, would be
(roughly speaking):

  [ { name | arg }=<replaceable>variable_name</replaceable> ]

In this example, the enclosing [env ] is of course implied, so 
the [] brackets above are not part of ITL but indicate that
the whole block is optional (since you can do just [env]).
{ arg | name } would indicate that 'name' is an alias for
'arg' and a variable name needs to be supplied.

For Perl syntax, we would omit $Tag->name( ) and just mention
what goes in the parentheses, because only that is doubtful - 
the invocation method is always the same.

This could solve some problems, but *maybe* wouldn't be so 
easy for newbies to comprehend. But since providing examples
is an absolute must, maybe this wouldn't be a problem.

Any thoughts or completely different ideas?

More information about the docs mailing list