features.en.yhtml2
author Volker Birk <vb@pep.foundation>
Thu, 21 Sep 2017 07:36:27 +0200
changeset 14 d937e9d7c4fe
parent 0 76005e62091d
child 44 4e5f42d51cc4
permissions -rw-r--r--
Version 2.5.6
0
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     1
include homepage.en.yhtml2
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     2
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     3
page "The Features" {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     4
    h2 id=text > Text
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     5
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     6
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     7
        To output text nodes (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax character data¬),
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     8
        write literals. There are integer literals, floating point literals and text literals.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
     9
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    10
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    11
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    12
        Literals are written
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    13
        ¬http://docs.python.org/reference/lexical_analysis.html#id7 like in Python¬,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    14
        that means, text literals are in single or double quotes, or multiline
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    15
        in triple double quotes:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    16
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    17
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    18
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    19
            "text" 'also text' """some more text"""
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    20
            42 "an integer and" 42.23 "a floating point literal"
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    21
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    22
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    23
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    24
        Literals are being output by the ¬#textfunction text function¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    25
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    26
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    27
    h2 id=functioncalls > Function Calls
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    28
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    29
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    30
        The main idea of YML scripts is calling functions which then generate
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    31
        XML tags (¬http://www.w3.org/TR/2008/REC-xml-20081126/#syntax Markup¬).
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    32
        Functions are generating single tags, lists or trees of tags.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    33
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    34
    
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    35
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    36
        To call a function, write the name of the function, followed by a comma separated list
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    37
        of function parameters (C like syntax) or just «attribute=value» pairs. Unlike C, you don't
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    38
        need to insert the parameter list into parentheses. A simple function call can be terminated
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    39
        by a semicolon «;» or by a period «.»
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    40
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    41
    
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    42
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    43
        It does not matter, if you're calling your function using parentheses or brackets or without.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    44
        So these statements are equal:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    45
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    46
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    47
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    48
            foo "hello, world";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    49
            foo "hello, world".
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    50
            foo("hello, world");
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    51
            foo["hello, world"];
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    52
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    53
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    54
    h3 id=subtree > Subtrees
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    55
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    56
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    57
        If you omit the tailing semicolon, you're creating a Subtree; YML Subtrees can also be
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    58
        opened and closed with braces:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    59
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    60
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    61
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    62
            foo {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    63
                bar {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    64
                    something;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    65
                }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    66
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    67
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    68
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    69
    p > If a Subtree only consists of one single subelement, then you may omit the braces:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    70
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    71
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    72
            foo
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    73
                bar;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    74
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    75
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    76
    h3 id=named > Named Parameters
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    77
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    78
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    79
        To generate ¬http://www.w3.org/TR/2008/REC-xml-20081126/#attdecls attributes¬ by calling
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    80
        a function, you can use Named Parameters.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    81
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    82
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    83
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    84
        For that case, assign literals or symbols to attribute names like the following.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    85
        The name of the parameter then will be used as the name of the generated attribute.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    86
        An example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    87
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    88
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    89
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    90
            div id=sample {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    91
                "this is a " a href="#sample" "link sample"
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    92
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    93
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    94
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    95
    p > This generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    96
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    97
    Code | <div id="sample">this is a <a href="#sample">link sample</a></div>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    98
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
    99
    h3 > Unnamed Parameters
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   100
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   101
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   102
        Unnamed Parameters prepare values for predefined attributes. The following example is
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   103
        equivalent to the sample above:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   104
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   105
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   106
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   107
            decl a(href);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   108
            decl div(id);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   109
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   110
            div "sample" {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   111
                "this is a " a "#sample" "link sample"
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   112
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   113
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   114
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   115
    p > If no predefined attribute can be allocated, the value of the parameter is added to the body.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   116
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   117
    h3 > Calling with &
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   118
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   119
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   120
        Especially if you have a ¬#defaultbody default body¬ for your function, calling with
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   121
        a leading «&» can be sensible: then the tag itself is omitted and only the body is being output:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   122
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   123
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   124
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   125
            decl something { tag1; tag2; };
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   126
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   127
            list {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   128
                &something;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   129
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   130
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   131
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   132
    p > results in:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   133
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   134
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   135
            <list>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   136
              <tag1/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   137
              <tag2/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   138
            </list>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   139
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   140
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   141
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   142
        This has the same result as ¬#alias aliasing¬ «something» to «-».
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   143
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   144
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   145
    h3 id=funclist > Function Lists
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   146
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   147
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   148
        Function Lists are a feature of YML to simulate a more C like syntax. Let's have some
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   149
        examples. You can have a list of functions whereever you can have a function. Function
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   150
        Lists are comma separated:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   151
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   152
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   153
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   154
            x i, j, k
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   155
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   156
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   157
    p > compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   158
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   159
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   160
            <x>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   161
              <i/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   162
              <j/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   163
              <k/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   164
            </x>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   165
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   166
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   167
    h3 id=paramlists > Parameter Lists
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   168
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   169
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   170
        A sample together with ¬#descending Descending Attributes¬:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   171
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   172
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   173
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   174
            decl Interface @name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   175
            decl attr @type @name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   176
            decl func @type @name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   177
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   178
            Interface Icecream {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   179
                attr color flavour;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   180
                attr long number;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   181
                func int getPrice();
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   182
                func void addFlavour(in color flavour, in long number);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   183
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   184
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   185
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   186
    p > compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   187
    
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   188
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   189
            <Interface name="Icecream">
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   190
              <attr type="color" name="flavour"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   191
              <attr type="long" name="number"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   192
              <func type="int" name="getPrice"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   193
              <func type="void" name="addFlavour">
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   194
                <parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   195
                  <in/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   196
                  <color/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   197
                  <flavour/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   198
                </parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   199
                <parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   200
                  <in/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   201
                  <long/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   202
                  <number/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   203
                </parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   204
              </func>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   205
            </Interface>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   206
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   207
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   208
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   209
        Note the «parm» tags – they're generated by default, if you write a Parameter List
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   210
        behind a Function Call. That differs from calling the function with parameters –
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   211
        ¬#functioncalls calling¬ means using ¬#text text¬ values.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   212
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   213
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   214
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   215
        The «parm» tags are emitted, because the «_parm» function is called each time
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   216
        such a parameter will be emitted.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   217
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   218
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   219
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   220
        If you want to have the «_parm» function doing other things, just ¬#decl declare¬
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   221
        it in another way.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   222
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   223
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   224
    h3 id=generics > Generic Declarations
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   225
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   226
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   227
        Using Generic Declarations is just like using ¬#paramlists Parameter Lists¬ – use angle brackets
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   228
        instead of parentheses. For Generic Declarations, the «_generic» function is called each
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   229
        time such a Generic Declaration will be emitted, generating «generic» tags as the default:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   230
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   231
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   232
    Code | max<int>(x, y)
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   233
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   234
    p > compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   235
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   236
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   237
            <max>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   238
              <generic>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   239
                <int/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   240
              </generic>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   241
              <parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   242
                <x/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   243
              </parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   244
              <parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   245
                <y/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   246
              </parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   247
            </max>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   248
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   249
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   250
    h3 id=contentfc > The «content» function
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   251
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   252
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   253
        The «content;» Function Call has a special meaning (only in a ¬#defaultbody default body¬):
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   254
        it does not generate a tag, but instead
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   255
        the tags of a supplied body in a call will be inserted at each place where the «content;»
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   256
        function call is existing in the ¬#defaultbody default body¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   257
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   258
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   259
    h3 id=textfunction > The «text» function
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   260
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   261
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   262
        There is a special YML function named «text». Usually, it's just ¬#alias aliased¬ to «-» (and 
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   263
        therefore outputting nothing). The «text» function is called each time a text literal will be
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   264
        output.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   265
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   266
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   267
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   268
        If you ¬#decl declare¬ the «text» function, you can overload that behaviour. For example,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   269
        ¬yslt YSLT¬ is declaring «text» like this:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   270
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   271
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   272
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   273
            decl text alias xsl:text;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   274
            
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   275
            "test"
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   276
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   277
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   278
    p > generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   279
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   280
    Code | <xsl:text>test</xsl:text>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   281
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   282
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   283
        The «text» function is not called, if you give text as a value for an attribute:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   284
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   285
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   286
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   287
            decl text alias xsl:text;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   288
            
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   289
            a "test"
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   290
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   291
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   292
    p > generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   293
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   294
    Code | <a>test</a>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   295
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   296
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   297
        But it is called using the quoting operators:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   298
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   299
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   300
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   301
            decl text alias xsl:text;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   302
            
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   303
            a > test
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   304
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   305
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   306
    p > generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   307
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   308
    Code | <a><xsl:text>test</xsl:text></a>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   309
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   310
    h3 id=declfunction > The «decl», «define» and «operator» functions
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   311
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   312
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   313
        The «decl», «define» and «operator» functions are not defined, so they cannot be used
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   314
        accidentally by having a syntax error i.e. in a «decl» statement. If you want to use such
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   315
        a function, i.e. «decl()», you have to ¬#decl declare it explicitely¬:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   316
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   317
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   318
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   319
            decl decl;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   320
            decl();
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   321
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   322
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   323
    p > will result in:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   324
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   325
    Code | <decl/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   326
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   327
    h2 id=decl > Declaring Functions: decl
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   328
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   329
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   330
        As default, each Function Call generates one XML tag, which has the same name. To be exact,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   331
        the XML tag has dashes in it's name where the YML function has underscores.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   332
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   333
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   334
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   335
        To define, how tags and attributes look like, which are created by a Function Call, you
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   336
        can use the «decl» statement.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   337
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   338
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   339
    h3 > Trivial Declarations
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   340
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   341
    p > In a trivial declaration, you're just declaring the Function Name and so the XML tag name:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   342
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   343
    Code | decl html, head, title, body, p, a;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   344
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   345
    p > As seen in the example, multiple declarations can be done in a comma separated list.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   346
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   347
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   348
        Because trivial declarations are done automatically, if you're using a function for the
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   349
        first time, you usually don't need to declare this way.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   350
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   351
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   352
    h3 > Specifying Unnamed Parameters
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   353
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   354
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   355
        To specifiy Unnamed Parameters, give the parameter list comma separated in parentheses
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   356
        or provide one or more brackets with parameter lists in them:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   357
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   358
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   359
    Code | decl a(href), img[src];
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   360
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   361
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   362
        If you're using the corresponding functions a() and img() together with an unnamed parameter
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   363
        in a call, then these attributes are used for applying the values, respectively:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   364
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   365
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   366
    Code | a "http://www.ccc.de" "The Club Homepage" img "logo.png";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   367
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   368
    p > These Function Calls generate:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   369
    
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   370
    Code | <a href="http://www.ccc.de">The Club Homepage</a><img src="logo.png"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   371
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   372
    h3 id=defaultattr > Giving Default Values for parameters
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   373
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   374
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   375
        To give default values for generating XML attributes, assign a literal to each named parameter
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   376
        in the declaration parentheses or brackets. Two examples, which do the same:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   377
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   378
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   379
    Code
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   380
        ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   381
        decl img(src, alt="picture");
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   382
        decl img[src][alt="picture"];
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   383
        ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   384
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   385
    h3 id=alias > Aliasing: using different YML functions for the same XML tag for different tasks
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   386
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   387
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   388
        Sometimes tags are used in different ways to do different things. For this case, you can
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   389
        use aliasing. Aliasing means, the YML function name and the XML tag name differ. For example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   390
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   391
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   392
    Code | decl a(href), target(name) alias a;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   393
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   394
    p > Both defined YML functions then generate «<a />» tags – but the Unnamed Parameter differs.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   395
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   396
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   397
        The alias name «-» has a special meaning: it omits the tag in the output. That is especially
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   398
        sensible if you have a ¬#defaultbody default body¬. Then an alias to «-» has the same meaning
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   399
        as starting the function call with the «&» character: only the body is emitted.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   400
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   401
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   402
    h3 id=descending > Specifying Descending Attributes
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   403
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   404
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   405
        Maybe you want to write something like this:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   406
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   407
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   408
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   409
            Module ERP {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   410
                Interface Customer {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   411
                    // ...
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   412
                }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   413
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   414
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   415
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   416
    p > Without any extras, this compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   417
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   418
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   419
            <Module>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   420
                <ERP>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   421
                    <Interface>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   422
                        <Customer />
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   423
                    </Interface>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   424
                </ERP>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   425
            </Module>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   426
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   427
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   428
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   429
        For this case, it would be practical, if «ERP» would not be interpreted as extra tag
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   430
        but as value for an attribute «name». This you can achive with Descending Attributes:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   431
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   432
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   433
    Code | decl Module @name, Interface @name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   434
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   435
    p > With this declaration, the code sample above is compiling to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   436
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   437
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   438
            <Module name="ERP">
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   439
                <Interface name="Customer" />
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   440
            </Module>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   441
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   442
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   443
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   444
        Descending attributes can also be used this way:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   445
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   446
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   447
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   448
            decl module +name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   449
            decl element +name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   450
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   451
            module Some {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   452
                element {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   453
                    one;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   454
                    two;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   455
                    three;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   456
                }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   457
                element {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   458
                    four; five; six
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   459
                }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   460
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   461
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   462
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   463
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   464
        The above generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   465
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   466
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   467
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   468
            <?xml version='1.0' encoding='UTF-8'?>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   469
            <module name="Some">
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   470
              <element name="one"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   471
              <element name="two"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   472
              <element name="three"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   473
              <element name="four"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   474
              <element name="five"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   475
              <element name="six"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   476
            </module>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   477
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   478
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   479
    h3 id=descending_pointer > Specifying Descending Pointers
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   480
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   481
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   482
        Like with descending attributes, you can use descending ¬#pointer pointers¬. Instead of preceding the
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   483
        name of an attribute with a «+» sign (like with ¬#descending descending attributes¬), precede it with an asterisk «*».
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   484
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   485
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   486
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   487
        Like with ¬#pointer pointers¬ in general, it's a good idea to combine that with a ¬#defaultbody default body¬:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   488
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   489
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   490
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   491
            decl f *p { some tags with *p };
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   492
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   493
            f value;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   494
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   495
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   496
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   497
        This generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   498
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   499
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   500
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   501
            <?xml version='1.0' encoding='UTF-8'?>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   502
            <f>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   503
              <some>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   504
                <tags>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   505
                  <with>value</with>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   506
                </tags>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   507
              </some>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   508
            </f>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   509
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   510
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   511
    h3 id=defaultbody > Supplying a Default Body
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   512
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   513
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   514
        Additionally, you can supply a Default Body for each tag. For that case, add a YML function
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   515
        block in braces to your declaration:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   516
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   517
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   518
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   519
            decl pageContent alias body {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   520
                a name=top;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   521
                include heading.en.yhtml2;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   522
                div id=entries
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   523
                content;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   524
            };
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   525
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   526
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   527
    p > The sample above is used for generating this homepage, for example.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   528
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   529
    p > See the ¬#contentfc content function¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   530
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   531
    h3 id=inheritance > Inheritance
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   532
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   533
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   534
        Declarations can ¬http://en.wikipedia.org/wiki/Inheritance_(computer_science) inherit¬
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   535
        information from previous declarations. For that case, there is the
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   536
        possibility to use an «is» clause to give a function name to inherit from.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   537
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   538
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   539
    p > The following is an example from the YSLT specification:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   540
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   541
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   542
            decl stylesheet(version="1.0", xmlns:xsl="http://www.w3.org/1999/XSL/Transform");
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   543
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   544
            decl estylesheet is stylesheet (
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   545
                xmlns:exsl='http://exslt.org/common',
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   546
                xmlns:math='http://exslt.org/math',
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   547
                xmlns:func='http://exslt.org/functions',
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   548
                xmlns:str='http://exslt.org/strings',
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   549
                xmlns:dyn='http://exslt.org/dynamic',
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   550
                xmlns:set='http://exslt.org/sets',
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   551
                extension-element-prefixes='exsl func str dyn set math'
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   552
            );
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   553
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   554
            decl textstylesheet is estylesheet {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   555
                output "text";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   556
                const "space", !"'" + " " * 200 + "'"!;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   557
                param "autoindent", 4;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   558
                content;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   559
            }, tstylesheet is textstylesheet;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   560
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   561
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   562
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   563
        Here «estylesheet» inherits the tag name and the Default Values from «stylesheet»,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   564
        while «textstylesheet» inherits all from «estylesheet» again. «estylesheet» then adds
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   565
        a Default Body, and «tstylesheet» does exactly the same as «textstylesheet».
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   566
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   567
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   568
    p > All of these YML functions output «stylesheet» XML tags, but with different defaults.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   569
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   570
    h3 id=shapes > Shapes
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   571
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   572
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   573
        Shapes are comparable to ¬#inheritance inheritance¬. Declaring a shape inherits
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   574
        every property beside the name.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   575
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   576
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   577
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   578
            decl coords(x=0, y=0);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   579
            decl point <coords> (name);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   580
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   581
            point "origin";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   582
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   583
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   584
    p > compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   585
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   586
    Code | <point y="0" x="0" name="origin"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   587
  
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   588
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   589
        It's possible to have more than one shape, too. Multiple shapes
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   590
        are patching each other in the sequence they're listed:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   591
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   592
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   593
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   594
            decl coords(x=0, y=0);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   595
            decl named +name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   596
            decl point <coords, named>;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   597
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   598
            point origin;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   599
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   600
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   601
    p > compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   602
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   603
    Code | <point y="0" x="0" name="origin" />
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   604
            
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   605
    h3 > Namespaces
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   606
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   607
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   608
        ¬http://www.w3.org/TR/xml-names/ XML namespaces¬ can be used just by providing an
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   609
        «alias» clause. Additionally, they can be used by an «in» clause; these two lines
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   610
        are equivalent:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   611
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   612
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   613
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   614
            decl apply(select) alias xsl:apply-templates;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   615
            in xsl decl apply(select) alias apply-templates;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   616
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   617
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   618
    p > «in» clauses also can be used with a block of declarations in braces:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   619
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   620
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   621
            in xsl {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   622
                decl template(match);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   623
                decl apply(select) alias apply-templates;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   624
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   625
                decl function(name) alias template;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   626
                decl call(name) alias call-template;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   627
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   628
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   629
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   630
    h3 id=pointer > Pointers
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   631
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   632
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   633
        In some situations, it is good to have information in a Function Call, which then
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   634
        changes the way XML tags are generated. For this case, there are Pointers.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   635
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   636
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   637
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   638
        The name should not mislead you; I took it because I chose the «*» symbol to declare them,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   639
        and that is the meaning of this symbol in the programming language C. The concept behind
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   640
        is very easy.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   641
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   642
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   643
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   644
        For example, it could be a good idea to generate a small HTML document containing some
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   645
        content. For this case, the title of the page is a good case for using pointers:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   646
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   647
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   648
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   649
            decl page(*title) alias html {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   650
                head {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   651
                    title *title;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   652
                }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   653
                body {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   654
                    h1 *title;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   655
                    content;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   656
                }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   657
            };
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   658
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   659
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   660
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   661
        In the example above, calling «page('My Page') { p 'hello, world'; }» will result in
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   662
        this XML output:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   663
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   664
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   665
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   666
            <html>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   667
                <head>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   668
                    <title>My Page</title>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   669
                </head>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   670
                <body>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   671
                    <h1>My Page</h1>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   672
                    <p>hello, world</p>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   673
                </body>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   674
            </html>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   675
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   676
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   677
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   678
        Pointers can be referenced in any place in the Default Body of a «decl» statement, also for
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   679
        generating extra tags. Then the value for a Pointer will be the tag name.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   680
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   681
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   682
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   683
        Additionally, you can insert the value of a pointer as text by calling it with two leading
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   684
        asterisks, i.e. if the pointer is defined as «*x», you can insert its value as text using: «**x».
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   685
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   686
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   687
    h4 id=pwt > Pointers without tags
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   688
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   689
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   690
        To give a literal a name, you can define pointers to literals.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   691
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   692
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   693
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   694
            define *answer = 42;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   695
            something *answer;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   696
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   697
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   698
    p > will compile to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   699
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   700
    Code | <something>42</something>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   701
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   702
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   703
        The «define» keyword as well as the asterisk «*» can be omitted. So this is
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   704
        equivalent to the statements above:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   705
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   706
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   707
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   708
            answer = 42;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   709
            something *answer;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   710
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   711
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   712
    h4 > The pointer *_debug_trace
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   713
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   714
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   715
        If you're calling ¬toolchain#processor yml2proc¬ with ¬toolchain#debug --debug¬, then this pointer is filled
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   716
        with tracing info text, otherwise it's an empty string.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   717
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   718
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   719
    h3 id=macros, "Macros";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   720
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   721
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   722
        Macros are a way to generate values for attributes with variable content. Macros can be set
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   723
        like any other parameters; they're used for a text search & replace in the values of attributes
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   724
        when attributes are generated.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   725
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   726
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   727
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   728
        Parameters, which represent macros, are determined with a preceding «%» sign. They're
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   729
        accounted for before any other parameter is accounted for in a function call, even if
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   730
        they were defined after other parameters.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   731
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   732
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   733
    p > An example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   734
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   735
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   736
            decl foo(%macro, myAttr="something %macro for testing");
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   737
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   738
            testing
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   739
                foo "nice";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   740
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   741
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   742
    p > This generates:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   743
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   744
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   745
            <testing>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   746
              <foo myAttr="something nice for testing"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   747
            </testing>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   748
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   749
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   750
    h3 id=nullfunction > The Null Function
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   751
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   752
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   753
        The function with the name «_» (underscore) is called Null Function. If you define this
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   754
        function, then you're switching off the default behaviour, that trivial declares are done
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   755
        automatically.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   756
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   757
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   758
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   759
        Instead, unknown functions now call the Null Function. This can be very sensible together
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   760
        with ¬#descending Descending Attributes¬:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   761
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   762
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   763
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   764
            decl _ +type +name alias func;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   765
            decl interface +name;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   766
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   767
            interface Testcase {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   768
                void f(in string input);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   769
                long getOptions();
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   770
            }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   771
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   772
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   773
    p > compiles to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   774
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   775
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   776
            <interface name="Testcase">
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   777
              <func type="void" name="f">
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   778
                <parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   779
                  <in/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   780
                  <string/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   781
                  <input/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   782
                </parm>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   783
              </func>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   784
              <func type="long" name="getOptions"/>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   785
            </interface>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   786
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   787
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   788
    h2 id=quoting > Quoting Operators
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   789
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   790
    p > Five different quoting operators implement different functionality:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   791
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   792
    h3 id=quote > Quote >
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   793
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   794
    p > The «>» operator quotes into text nodes, doing XML escaping of text. An example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   795
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   796
    Code | > this text will be put into a text node and these angle brackets <> will be quoted
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   797
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   798
    p > Additionally, it can be used to implement an indention system, see ¬yslt YSLT¬ below.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   799
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   800
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   801
        Then an integer literal can be the first part of the operator; it gives the indention
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   802
        level. For example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   803
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   804
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   805
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   806
            0> this text is indented to the actual level and then output,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   807
             >  followed by this text.\\n
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   808
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   809
            1> this text is indented one indention level\\n
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   810
            2> two levels\\n
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   811
            1> one level again\\n
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   812
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   813
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   814
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   815
        Quote text is being output by the ¬#textfunction «text» function¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   816
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   817
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   818
    h3 id=blockquote > Block Quote >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   819
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   820
    p {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   821
        > To include more lines of text into a single quoted area, use double «>>». The lines 
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   822
        > are concatenated together then. An example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   823
    }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   824
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   825
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   826
            p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   827
                This generates a text paragraph for HTML. All this text, which you can find in
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   828
                these lines, is being concatenated together to one single text node, and then put
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   829
                into the body of the <p> ... </p> tag.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   830
                >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   831
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   832
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   833
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   834
        Block quote text is being output by the ¬#textfunction «text» function¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   835
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   836
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   837
    h3 > Line Quote |
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   838
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   839
    p > The «|» operator does the same as the «>» operator, adding a newline character to the text node.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   840
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   841
    p > Additionally, it can be used to implement an indention system, see ¬yslt YSLT¬ below.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   842
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   843
    p > Then it's used together with additional «>» symbols showing the grade of indention:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   844
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   845
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   846
            | not indented
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   847
            |> single indent
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   848
            |>> double indent
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   849
            (...)
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   850
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   851
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   852
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   853
        Line quote text is being output by the ¬#textfunction «text» function¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   854
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   855
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   856
    h3 > Block Line Quote ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   857
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   858
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   859
        The «||» operator opens and closes a block of lines, which then are handled like if each of
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   860
        them would be preceeded with a Line Operator «|».
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   861
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   862
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   863
    p > Sample:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   864
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   865
    Code {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   866
        | ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   867
        ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   868
        this is code being quoted through
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   869
        this is the second line
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   870
        ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   871
        | ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   872
    }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   873
     
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   874
    p > is equivalent to:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   875
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   876
    Code {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   877
        ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   878
        | this is code being quoted through
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   879
        | this is the second line
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   880
        ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   881
    }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   882
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   883
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   884
        Block line quote text is being output by the ¬#textfunction «text» function¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   885
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   886
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   887
    h3 > Inserting Commands
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   888
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   889
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   890
        Just like with a ¬http://en.wikipedia.org/wiki/Shell_(computing)#Unix_shells Unix shell¬,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   891
        you can insert statements into text by using backticks:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   892
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   893
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   894
    Code ] | Click `a href="http://fdik.org/yml/" "this link"`, please!
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   895
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   896
    p {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   897
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   898
        Being in a Block Line Quote «||», you additionally can use the Line Command operator
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   899
        (two backquotes,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   900
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   901
        ]  ``).
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   902
    }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   903
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   904
    p > This is very interesting to have in YSLT, for example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   905
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   906
    Code {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   907
        | ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   908
        | some code
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   909
        ] ``
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   910
        > apply "myTemplate";\n
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   911
        | some other code
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   912
        | ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   913
    }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   914
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   915
    h3 id=userop > User defined in-text Operators
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   916
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   917
    p > You can define short cuts for inserting commands into text by defining operators.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   918
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   919
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   920
        Therefore, you need a ¬http://en.wikipedia.org/wiki/Regular_expression regular expression¬
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   921
        for matching text and YML text for replacing with. Here an example, how this is used by YSLT:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   922
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   923
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   924
    Code ] define operator "«(.*?)»" as value "%1";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   925
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   926
    p > The RegEx have ¬http://docs.python.org/library/re.html Python syntax¬.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   927
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   928
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   929
        In this example all matches to the RegEx will be replaced by the YML text in the «as» clause.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   930
        The text of the first group in the RegEx will replace the «%1» in the resulting YML text. You
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   931
        can do that for more than one group – just use «%2» for the second group, «%3» for the third
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   932
        one and so on.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   933
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   934
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   935
    p > The «define» keyword can be omitted.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   936
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   937
    h3 id=quotethrough > Quote Through ]
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   938
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   939
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   940
        The ¬http://en.wikipedia.org/wiki/Apple_II_series Apple ][¬ prompt operator just quotes
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   941
        through directly into XML what it gets.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   942
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   943
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   944
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   945
        If the first character of a command is a «<», then quote through is applied
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   946
        automatically.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   947
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   948
    
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   949
    p > This is the preferred way to output XML tags directly in YML:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   950
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   951
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   952
            <output me="directly" />
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   953
            
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   954
            ] <!--
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   955
            ]     add some comment, which then appears in XML
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   956
            ] -->
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   957
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   958
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   959
    h2 id=including > Including YML files
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   960
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   961
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   962
        You can include a second YML script file into an existing YML script file
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   963
        at any place using one of the following:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   964
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   965
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   966
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   967
            include something.yml2
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   968
            include "something else.yml2"
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   969
            include 'anything addionally.yml2'
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   970
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   971
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   972
    a name="ymlpath";
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   973
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   974
        If you're not starting the filename with '.' or '/' as in the example above, then
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   975
        if the «YML_PATH» environment variable is set to a colon separated list of directories,
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   976
        these directories are being searched for the given filename. Otherwise, the local
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   977
        directory is searched.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   978
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   979
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   980
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   981
        Filename ¬http://en.wikipedia.org/wiki/Glob_(programming) globbing¬ using «*» and «?»
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   982
        placeholders is supported to include more than one file at a time:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   983
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   984
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   985
    Code | include part*.yml2
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   986
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   987
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   988
        Filename globbing also can be used reverted; that means, the files are included in reverse
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   989
        order:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   990
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   991
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   992
    Code | include reverse part*.yml2
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   993
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   994
    p > If there are the files part1.yml, part2.yml and part3.yml, part3.yml is included first now.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   995
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   996
    p > To include plain text as text nodes, you can use:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   997
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   998
    Code | include text some.txt
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
   999
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1000
    p > To include ready made XML, use:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1001
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1002
    Code | include xml some.xml
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1003
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1004
    h2 id=python > Escaping into Python – the Escape Operator !
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1005
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1006
    p > You can insert a Python command at any place by using the «!» operator:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1007
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1008
    Code | !class X(str): pass
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1009
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1010
    h3 > Python script Operator !!
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1011
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1012
    p > You can use the double «!!» to include more than one line of Python code:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1013
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1014
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1015
            !!
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1016
            def fak(n):
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1017
                if n == 0:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1018
                    return 1
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1019
                else:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1020
                    return n * fak(n - 1)
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1021
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1022
            def getName(id):
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1023
                return SQL("select name from customers where id='"+str(id)+"';")[0]
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1024
            !!
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1025
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1026
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1027
    h3 > Python generated parameters in Function Calls
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1028
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1029
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1030
        You may use Python expressions to generate names and/or values in Function Calls.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1031
        To do so, embed the Python expression in «! ... !»:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1032
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1033
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1034
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1035
            f x=!fak(5)!;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1036
            customer name=!getName(42)!;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1037
            tag !getNextAttributeName()!=42;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1038
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1039
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1040
    h3 > Python generated Function Calls
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1041
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1042
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1043
        You can generate text with a Python expression, which represents an YML Function Call.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1044
        The resulting YML function is then executed. Also here, embed the Python expression
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1045
        in «! ... !»:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1046
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1047
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1048
    Code | !getTagName() + " " + getAttrib() + "='" + getValue() + "'"!
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1049
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1050
    h3 > Using Pointers as values in Python function calls
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1051
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1052
    p   >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1053
        Sometimes it is useful to call a generating Python function using information of a
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1054
        YML Function Call. For that case, there is the «python» statement in YML. You can
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1055
        call there a single Python function using YML Pointers as parameters.
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1056
        >>
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1057
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1058
    p > This is used in the YSLT specification, for example:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1059
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1060
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1061
            decl apply(select, *indent=1) alias apply-templates {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1062
                python withIndent(*indent);
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1063
                content;
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1064
            };
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1065
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1066
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1067
    h2 id=comments > Comments //, /* */
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1068
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1069
    p > Comments are written like in Java or C++:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1070
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1071
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1072
            // this is a comment
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1073
            something() { // this is a comment after a tag
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1074
            /* this is some comment, too */
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1075
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1076
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1077
    p > After Quoting Operators, comments are not possible. Instead, they're quoted through:
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1078
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1079
    Code    ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1080
            // the following line you'll find in the output document
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1081
            > this text is being output // and this too
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1082
            ||
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1083
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1084
    div id=bottom {
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1085
        > ¬programming << Using YML 2¬ 
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1086
        > ¬#top ^Top^¬ 
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1087
        > ¬yslt >> show me YSLT¬ 
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1088
        > ¬features.en.yhtml2 (source)¬
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1089
    }
76005e62091d initial commit
Volker Birk <vb@pep-project.org>
parents:
diff changeset
  1090
}