# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Escaping Symbols

H2: Special Characters at the Start of a Line

To escape a special character at the start of a line,
precede it with a backslash character (\).

H2: Tag Delimiters

Like special characters, any special pattern at the start of a line
can be escaped by preceding it with a backslash character (\).

Consider the following example:

E:   Important:

This paragraph has a tag called {{Important}} and has no text.
{{CMD:sdf}} will warn you if it finds an unknown tag so most
unintentional errors like this are detected. You can escape the
pattern like this:

E:   \Important:

Other workarounds are:

E:   :Important:
E:   N:Important:

!if $var{'OPT_TARGET'} ne 'hlp'

H2: Special Symbols

[[SDF]] uses a number of special symbols inside paragraphs:

* A-ZE<lt> and > - delimit {{concise}} phrases
* E<2{> and E<2}> - delimit {{verbose}} phrases
* E<2[> and E<2]> - delimit expressions (e.g. variables).

If you need to include one of these symbols in a paragraph,
use the appropriate escape as shown below.

!block verbatim
    Symbol      Escape
    <           E<lt>
    >           E<gt>
    {{          E<2{>
    }}          E<2}>
    [[          E<2[>
    ]]          E<2]>
!endblock

Note the following rules:

^ It isn't necessary to escape any symbols within:
  - paragraphs tagged with the V style or > tag
  - paragraphs given the verbatim attribute
  - paragraphs within a verbatim block

+ It is only necessary to escape a < when it appears after
  a capital letter.

+ It is only necessary to escape a > inside a concise phrase.
  In particular, > is implicitly escaped within a verbose phrase.

!endif

H2: Phrase Parsing Rules

For paragraphs which do not have the {{verbatim}} attribute set,
the parsing rules for the paragraph text are:

^ Expressions embedded in E<2[> and E<2]> are recursively expanded
+ Verbose phrases embedded in E<2{> and E<2}> are recursively expanded
  to concise phrases with a V tag.
+ Concise phrases are parsed.

#Note: These rules may be changed before the production release
#so that only a single left to right parse of the paragraph text is done.
#However, if this happens, I'll keep the semantics as close to the above as
#possible.

H2: Multi-line Macros

\!-style macros can be continued onto the next line by ending the
line with a backslash character (\). To escape this backslash,
use another one. If N backslash characters are found
at the end of a line where N is greater than 2, then that
line is terminated by N-1 backslash characters and the macro
is continued onto the next line.

H2: Embedded Expressions

As expressions embedded within text are terminated by the ]\] symbol,
expressions cannot contain this character sequence. If you need this sequence
within an expression, there is usually a simple workaround you can
use. For example:

^ use a space character (i.e. $a[$b[1]] becomes $a[$b[1] ])
+ use string concatentation (i.e. "]]" becomes "]"."]").

H2: Semi-Colons Within Attributes

If you need to include a real semi-colon within an attribute or parameter,
use two semi-colons. In general, if you need to include a sequence of
N semi-colons in an attribute expression, use N+1 semi-colons.
For example:

V:To install {{P[index="myApp;;install:myApp"]myApp}}, ...

In this case, the value of {{index}} is {{E:myApp;install:myApp}}.


!end_topic
