Permalink
Browse files

Fix README for github

  • Loading branch information...
1 parent 3739e25 commit 2df614d3f14d129b356be4fa022825dd8476f4ee @blambeau committed Jan 13, 2012
Showing with 23 additions and 32 deletions.
  1. +23 −32 README.md
View
55 README.md
@@ -46,6 +46,7 @@ instantiation *context* (data provided through a Ruby Hash or a yaml file for
example) and you would like to instantiate the template with that data.
Example: a template.whtml as follows
+
<html>
<head>
<title>${title}</title>
@@ -77,29 +78,29 @@ the template is straightforward:
* Include text files on the fly
- <<{my_file.html}
+ <<{my_file.html}
* Instantiate sub-templates on the fly, passing data as arguments
- <<+{my_sub_template.whtml using who: 'wlang'}
+ <<+{my_sub_template.whtml using who: 'wlang'}
* Load data from yaml or ruby files on the fly
- <<={resources.yaml as resources}{
- *{resources as r}{ ${r} }
- }
+ <<={resources.yaml as resources}{
+ *{resources as r}{ ${r} }
+ }
* WLang instrospection (basic example)
- context = {:varname => 'who', :who => 'wlang'}
- "Hello ${${varname}}!".wlang(context) # => Hello wlang!
+ context = {:varname => 'who', :who => 'wlang'}
+ "Hello ${${varname}}!".wlang(context) # => Hello wlang!
* Generate a wlang template and instantiate it after that
- dialect = 'wlang/active-string'
- tpl = "Hello $(${varname})!" # => Hello $(${varname})
- tpl = tpl.wlang(:varname => 'who') # => Hello $(who)!
- tpl = tpl.wlang({:who => 'wlang'}, dialect, :parentheses) # => Hello wlang!
+ dialect = 'wlang/active-string'
+ tpl = "Hello $(${varname})!" # => Hello $(${varname})
+ tpl = tpl.wlang(:varname => 'who') # => Hello $(who)!
+ tpl = tpl.wlang({:who => 'wlang'}, dialect, :parentheses) # => Hello wlang!
## Roadmap
@@ -119,56 +120,46 @@ the template is straightforward:
## Terminology
-_wlang_ comes with a well-defined terminology for the underlying abstractions. As
+* _wlang_ comes with a well-defined terminology for the underlying abstractions. As
the documentation uses it, you'll probably be happy to learn about the main abstractions
and associated terms.
-
-_template_ : Source code respecting the wlang grammar, and attached to a given <em>wlang
+* _template_ : Source code respecting the wlang grammar, and attached to a given <em>wlang
dialect</em>. Asbtraction implemented by WLang::Template.
-
-_dialect_ : Basically, <em>dialect</em> is used as a synonym for (programming) <em>language</em>.
+* _dialect_ : Basically, <em>dialect</em> is used as a synonym for (programming) <em>language</em>.
However _wlang_ uses a tree of dialects, allowing specializations: <tt>sql/sybase</tt>
for example is the qualified name of a sub-dialect 'sybase' of the 'sql' dialect.
Dialects come with associated _encoders_. Abstraction implemented by WLang::Dialect.
-
-_wlang dialect_ : When we talk about a <em>wlang dialect</em>, we are actually refering to some
+* _wlang dialect_ : When we talk about a <em>wlang dialect</em>, we are actually refering to some
specialization of the wlang tag-based grammar: <tt>wlang/xhtml</tt> for example
is the templating language _wlang_ proposes to generate xhtml pages. An
example of source code in that dialect has been shown before.
In addition to its encoders a <em>wlang dialect</em> comes with its sets of _tags_
and associated _rules_. Abstraction implemented by WLang::Dialect as well as
WLang::EncoderSet and WLang::RuleSet.
-
-_encoder set_ : Reusable set of <em>encoders</em>, attached to a dialect. Abstraction
+* _encoder set_ : Reusable set of <em>encoders</em>, attached to a dialect. Abstraction
implemented by WLang::EncoderSet.
-
-_encoder_ : Text transformation (algorithm) applying some encoding conventions of a portion
+* _encoder_ : Text transformation (algorithm) applying some encoding conventions of a portion
of a the target language generated by a dialect. HTML entities-encoding, SQL's back-quoting
are examples of encoders. Encoders are accessible through their qualified name:
xhtml/entities-encoding and sql/back-quoting in the examples. Abstraction implemented by
WLang::Encoder.
-
-_ruleset_ : Reusable set of <em>tags</em> associated to <em>rule</em>s. Abstraction
+* _ruleset_ : Reusable set of <em>tags</em> associated to <em>rule</em>s. Abstraction
implemented by WLang::RuleSet.
-
-_wlang tag_ : Special tags in the template, starting with wlang symbols and a number of wlang
+* _wlang tag_ : Special tags in the template, starting with wlang symbols and a number of wlang
blocks. A tag is associated with a wlang rule. Examples: <tt>${...}</tt> is a
tag with only one block, while <tt>?{...}{...}{...}</tt> is another tag but with
three blocks.
-
-_rule_ : Transformation semantics of a given <em>tag</em>. When wlang instantiates a
+* _rule_ : Transformation semantics of a given <em>tag</em>. When wlang instantiates a
template it simply replaces <em>wlang tags</em> by some <em>replacement value</em>
(which is always a string). This value is computed by the rule attached to
the tag. Rule definition explicitly describes the number of blocks it expects, in which dialect they
are parsed and instantiated and the way the replacement value is computed.
Example: <tt>^{wlang/active-string}{...}</tt> (also known as 'encoding')
instantiates #1, looking for an encoder qualified name. Instantiates #2 in
the current dialect. Encode #2's instantiation using encoder found in (#1)
-
-_context_ : Some rules allow code to be executed in the <em>hosting language</em> (the
+* _context_ : Some rules allow code to be executed in the <em>hosting language</em> (the
definition explicitly announce it by putting <tt>wlang/hosted</tt> in the corresponding
block). When doing so, this code is in fact executed in a given context that
provides the execution semantics. Abstraction implemented in WLang::Parser::Context.
-
-_hosting language_ : language (or framework) that executes wlang. In this case, it will be
+* _hosting language_ : language (or framework) that executes wlang. In this case, it will be
<tt>ruby</tt>.

0 comments on commit 2df614d

Please sign in to comment.