Conference vaxuum::document_ft

212.0. "Syntax Notation Using <TAG>" by ZENSNI::DCHAVEZ (Dale C. - CXO3 Colo Spgs) Tue Apr 07 1987 12:53

Greetings,

I'm currently writing a software manual that discusses syntax notation, and 
I'm having problems trying to format the examples.

An example:

    <result_buffer>    ::=  <clumplet...>
                            <termination_byte>

    <clumplet>         ::=  <type> <length> <value>

       <type>          ::=  unsigned word
       <length>        ::=  unsigned word
       <value>         ::=  byte...

    <termination_byte> ::=  unsigned byte


I've tried <codexample>,<syntax>,<literal>,<line_art> and DOCUMENT/TEX 
tries to interpret each example as a tag.

Then I tried using <tag> along with <align_char> within a <codexample>. 
This worked better, but DOCUMENT 'threw out' my spaces, and the alignment 
was wrong.

<ALIGN_CHAR>(#)

<codexample>
    <tag>(result_buffer)####::=  <tag>(clumplet...)
                                 <tag>(termination_byte)

    <tag>(clumplet)#########::=  <tag>(type) <tag>(length) <tag>(value)

       <tag>(type)##########::=  unsigned word
       <tag>(length)########::=  unsigned word
       <tag>(value)#########::=  byte...

    <tag>(termination_byte)#::=  unsigned byte
<endcodexample>
<ENDALIGN_CHAR>


Can anyone suggest something better?

Thanks in advance.

Dale

    What was wrong with using <literal> ... <endliteral> to surround
    the entire example?
    
    <code_example><literal>
    .
    .
    .
    <endliteral><endcode_example>
    
    That says "don't try to interpret anything in this code example
    as a tag."   If you actually put some tags in the example, you'll
    have to break up the literal into two or more literals in order
    to get you real tags to appear outside the <literal> ... <endliteral>
    sequences.
    
    Another alternative is to define a one character tag that will give
    you a literal "<".  then you would write all your examples as
    
      <a>mumbledy>  :== <a>foo>  <a>bar>             
    
    the define would look like:
    
    <define>(a\|<literal>(<)&)
    
    Try that on the front of your file and see if you can tolerate coding
    the left angle bracket as <a> instead of just <.

RE:< Note 212.1 by VAXUUM::KOHLBRENNER >

Your first suggestion worked great!

Thanks,
Dale