Commits

Maytag Metalark committed 28c6bcd

Some work on tutorial.

-Added reST TOC to rest.itmpl.
-Added several new sections to tutorial.

Comments (0)

Files changed (4)

         % invoking the reST macro.
         {glue 
             {\n} {$ :tline} {\n} {ete {$ :pageTitle}} {\n} {$ :tline} {\n} {\n}
+"
+.. contents:: Contents
+    :depth: 2
+"
             {$ :bodyContent }
+
+            {section "Complete Contents" {'
+"
+.. contents::
+    :depth: 10
+"
+            }}
+
         }
 
         %end reST macro body.
-{dont
-    Block comments are good for long comments,
-    Because they can span multiple lines.
-    {
-        They need to be well-formed, but not necessarily valid code.
-    }
-    {dont
-        You can nest them as well, which is helpful for commenting out large
-        blocks of code, even if the block already includes comments.
-    }
-    % For malformed code, like if you have an extra } or {, for instance,
-    % you can also include end-of-line comments in block comments.
-}
+{str {' foo bar}}

templ/tutorial.css

     padding: 9px 12px;
     font-family: Monaco,"Courier New",monospace;
 }
+
+.contents p.topic-title
+{
+    font-size: 16pt;
+    font-weight: bold;
+}
+.contents ul
+{
+    padding-left: 15px;
+    list-style-type: disc;
+}
+

templ/tutorial.templ

 
                     }
 
-                }} % end section - 
+                }} % end section "Quoted Strings" 
+
+                % TODO: XXX: Lists. The nil function, the list function.
+
             }} % end section - "Basic Data Types"
 
-
         }} % end section "Hello, ..."
 
         {section "The temple Processing Routine" {'
 }"
             }
 
-            {p {'
-                {implode <<<A few general suggestions on formating your code:>>>}
-                {ul {'
-                    {implode                    
-<<<Keep the first element of a list (the one that specifies the executable to be invoked)
-on the same line as the opening curly brace, generally with no space separating it from the brace. This makes it much
-more obvious what is being invoked.>>>
+            {section "Code Formatting" {'
+                {p {'
+                    {implode <<<A few general suggestions on formating your code:>>>}
+                    {ul {'
+                        {implode                    
+    <<<Keep the first element of a list (the one that specifies the executable to be invoked)
+    on the same line as the opening curly brace, generally with no space separating it from the brace. This makes it much
+    more obvious what is being invoked.>>>
+                        }
+
+                        {implode
+    <<<Indent all subsequent elements of the list relative to the opening brace. This helps establish sematic scope for the reader.>>>
+                        }
+
+                        {implode
+    <<<Don't ever use tabs, use spaces. Tabstops may be set differently by different users and in different editors, so things that are
+    nicely aligned with tabs in one circumstance may look horrendous in another. The standard indentation level is 4 spaces. Three is
+    also acceptable but kind of weird. Two in somewhat common, and econimical, but is not as visually helpful as a larger indent. More
+    than 4 is excessive and will quickly lead to lines that don't have available width. If you want to use tabs because you can't handle
+    the extra couple of backspaces, either stop being lazy or get a better editor.>>>
+                        }
+
+                        {implode
+    <<<Put the closing brace on a new line, aligned in the same column as the opening brace. This make it obvious where
+    the List ends, and therefore what is included in it.>>>
+                        }
+
+                    }}
+                }}
+            }} % end section "Code Formatting"
+
+
+        {section "Output Values" {'
+
+            {p
+<<<Remember that {templ} is, first and foremost, a template processing language; its main goal in life is to
+process input and produce output. Therefore, when the {templ} processor finishes evaluating a top level
+expression, it assumes that the result of that expression is intended as output.>>>
+            }
+
+            {p
+<<<That's all fine and good when the resulting value is a String, {templ} will just write the String value to
+the output stream. But {templ} can't write a List or an executable to the output stream, so if a top level
+expression ever evaluates to something other than a String, {templ} will err.>>>
+            }
+
+            {p
+<<<The fact that top level String values are written directly to the output stream means a lot of our examples
+above which used the {code echo} function, didn't actually need to use it. If we were already invoking a
+function that results in a String, such as the {code glue} function, we could simply make that our top level
+expression and {templ} will output the resulting String to the output stream, just like the {code echo}
+function does.>>>
+            }
+
+            {EXAMPLE-TEMPLATE "text"
+
+                {implode
+<<<In the following template, we simply did away with the {code echo} function from our previous template, and
+left the call to the {code glue} function as the top level expression.>>>
+                }
+
+                {implode
+<<<You can see that the output is the same, because {templ} writes the result of calling the {code glue}
+function directly to the output stream.>>>
+                }
+
+"{glue
+    {glue h e \"l\"l\"o\"}
+    ,
+    \" \"
+    {glue 
+        {glue 
+            te mp 
+            {glue l e}
+        }
+        !
+    }
+}"
+            }
+
+            {p
+<<<You may be wondering why you would ever need to use the {code echo} function, if {templ} will just echo
+your top level Strings automatically. There are times where you will want to write to the output stream from
+somewhere other than the top level, for instance inside a loop. In times like this, the {code echo} function
+comes in very useful.>>>
+            }
+
+            {section "The str Function" {'
+                % TODO: Add examples, including Lists. Basic list functions are introduced in the Basic types
+                % section above.
+                {p
+<<<For convenience, {templ} does provide a builtin {code str} function, which is used to convert any value
+into a String. Simply pass in any value, and a String representation of that value will result.>>>
+                }
+
+            }} % end section "...str..."
+
+
+            {section "Null Values and the void Function" {'
+                {p
+<<<Actually, there's one other type besides Strings that {templ} can write directly to the output stream: the
+Null type. This is a special type which only has one value (called the Null value) which generally represents
+the absense of a value. If a top level expression evaluates to the Null value, the output for that expression
+is simply an empty string (or more accurately, there is no output).>>>
+                }
+
+                {p
+<<<Note, however, that this is only a special case for the top level processor. Otherwise, a Null value is {em
+not} the same thing as an empty string, they just happen to result in the same output at the top level.
+Specifically, passing a Null value to the {code str} function does {em not} result in any empty string, it
+results in the String value {code "\"NULL\""}.>>>
+                }
+
+                {p
+<<<To produce a Null value, you can use the {code void} function. the {code void} function can take up to 1
+argument, which {em is} evaluated  but the result of the {code void} expression is always a Null value. You
+can also invoke it without any arguments, in which case it simply results in a Null value.>>>
+                }
+
+                {p
+<<<The {code void} function is a useful way to supress the result of a top level expression. Actually it's no
+longer a top level expression because you're wrapping it up in a {code void} expression, but that's the whole
+point: the original expression is evaluated as desired, but the {code void} ensures that whatever
+type that expression results in, the top level output will be a nice safe Null value that won't err and won't
+effect your output.>>>
+                }
+
+                {p
+<<<A lot of {templ} functions have {em aliases}, which are just different symbols you can use to invoke them.
+The void function has a very nice alias, which is simply the single character {code v}. You are likely to see
+the function referenced with this alias a lot more often than with the gratuitous {code void} symbol.>>>
+                }
+
+                {EXAMPLE-TEMPLATE "text"
+
+                    {implode
+<<<The following very simple macro shows the {code void} function at work (using the common {code v}
+alias).>>>
                     }
 
                     {implode
-<<<Indent all subsequent elements of the list relative to the opening brace. This helps establish sematic scope for the reader.>>>
+<<<And the output:>>>
                     }
 
-                    {implode
-<<<Don't ever use tabs, use spaces. Tabstops may be set differently by different users and in different editors, so things that are
-nicely aligned with tabs in one circumstance may look horrendous in another. The standard indentation level is 4 spaces. Three is
-also acceptable but kind of weird. Two in somewhat common, and econimical, but is not as visually helpful as a larger indent. More
-than 4 is excessive and will quickly lead to lines that don't have available width. If you want to use tabs because you can't handle
-the extra couple of backspaces, either stop being lazy or get a better editor.>>>
-                    }
+"Null output: {v}
+A Null value, as a String: {str {v}}
+The void function, to supress output: Foo{v \"---\"}Bar"
 
-                    {implode
-<<<Put the closing brace on a new line, aligned in the same column as the opening brace. This make it obvious where
-the List ends, and therefore what is included in it.>>>
-                    }
+                }
 
-                }}
-            }}
+            }} % end section "...null...void..."
+
+
+        }} %end section "Output Values"
+
         }} % end section "...Processing Routine"
 
         {section "Comments" {'
 
         {p
 <<<It wouldn't be much of a programming language without a way to store and recall data. {templ} uses a structure
-called {em the stack} to store what are effectively variables. We'll see more about this later, but >>>
+called {em the stack} to store what are effectively variables. Essentially, the stack acts like a dictionary
+which maps data to String values called {em symbols}. These symbols are the {templ} equivalent of
+variables.>>>
         }
 
-    '}}
+        {p
+<<<Because the symbols which are used to map stored values in the stack are just ordinary String values, using
+them in a {templ} expression has no special effect: it still just evaluates to the String itself, not to the
+stored value. To get the stored value of a symbol from the stack, you can use the {code getset} function,
+passing in the symbol you want to lookup.
+>>>
+        }
+
+        {EXAMPLE-TEMPLATE "text"
+            {implode
+<<<As its name implies, the {code getset} function can also be used for setting the value of a symbol in the
+stack. To do so, simply pass in two arguments to the {code getset} function: the symbol, and then the value to
+store at that symbol. Both uses of {code getset} are shown in the following example template:>>>
+            }
+
+            {implode
+<<<On the first line of the template, {code getset} is used in its "setting" form, with two arguments. The
+symbol is first, "FOOBAR", and then the value, which is a self referential String. On the second line, it's
+used in its "getting" form with just one argument, the symbol to lookup. One thing to notice is that this
+template output the value twice. This is because the {code getset} function always results in the value of the
+specified symbol, even when setting it.>>>
+            }
+
+"{getset FOOBAR \"The value of \\\"FOOBAR\\\".\"}
+{getset FOOBAR}"
+
+        }
+
+    }}
         
 }}{#
 
 
- vim: set ft=templ:
+ vim: set ft=templ tw=110:
 }
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.