README.md in sablon-0.0.10 vs README.md in sablon-0.0.11
- old
+ new
@@ -30,12 +30,12 @@
```
### Writing Templates
-Sablon templates are normal word documents (`.docx`) sprinkled with MergeFields
-to perform operations. The following section will use the notation `«=title»` to
+Sablon templates are normal Word documents (`.docx`) sprinkled with MailMerge fields
+to perform operations. The following section uses the notation `«=title»` to
refer to [Word MailMerge](http://en.wikipedia.org/wiki/Mail_merge) fields.
#### Content Insertion
The most basic operation is to insert content. The contents of a context
@@ -68,39 +68,81 @@
to insert a body of text containing different formats. If you can't decide the
format ahead of processing time (in the template) you can insert
[WordProcessingML](http://en.wikipedia.org/wiki/Microsoft_Office_XML_formats)
directly.
-The template can use a simple insertion operation like so:
+It's enough to use a simply insertion operation in the template:
```
«=long_description»
```
-The thing that changes is the context passed when processing the template:
+To insert WordProcessingML prepare the context accordingly:
```ruby
-word_processing_ml = <<-XML
+word_processing_ml = <<-XML.gsub("\n", "")
<w:p>
- <w:r w:rsidRPr="00B97C39">
- <w:rPr>
- <w:b />
- </w:rPr>
- <w:t>this is bold text</w:t>
- </w:r>
+<w:r w:rsidRPr="00B97C39">
+<w:rPr>
+<w:b />
+</w:rPr>
+<w:t>this is bold text</w:t>
+</w:r>
</w:p>
XML
+
context = {
long_description: Sablon.content(:word_ml, word_processing_ml)
}
template.render_to_file File.expand_path("~/Desktop/output.docx"), context
```
-**IMPORTANT:** This feature is very much *experimental*. Currently, this only
- works if the insertion is the only thing inside the template paragraph. Other
- content is discarded!
+IMPORTANT: This feature is very much *experimental*. Currently, the insertion
+ will replace the containing paragraph. This means that other content in the same
+ paragraph is discarded.
+##### Markdown
+
+Similar to WordProcessingML it's possible to use markdown while processing the
+tempalte. You don't need to modify your templates, a simple insertion operation
+is sufficient:
+
+```
+«=article.body»
+```
+
+To use Markdown insertion prepare the context like so:
+
+```ruby
+markdown_body = <<-MD
+This text can contain *additional formatting*
+according to the **Markdown** specification.
+MD
+context = {
+ article: { body: Sablon.content(:markdown, markdown_body) }
+}
+template.render_to_file File.expand_path("~/Desktop/output.docx"), context
+```
+
+Markdown insertion has built-in support for:
+
+* [Headers](http://spec.commonmark.org/0.17/#atx-header)
+* [Paragraphs](http://spec.commonmark.org/0.17/#paragraphs)
+* [Emphasis and strong emphasis](http://spec.commonmark.org/0.17/#emphasis-and-strong-emphasis)
+* [Hard line breaks](http://spec.commonmark.org/0.17/#hard-line-breaks)
+* [Lists](http://spec.commonmark.org/0.17/#lists)
+
+For headings and lists to function properly it is necessary that the template
+defines specific styles. Headings use styles called `Heading1`, `Heading2`,
+etc. according to the header level. Ordered lists will use the style
+`ListNumber` and unordered lists use `ListBullet`. Nested lists are not
+supported.
+
+IMPORTANT: This feature is very much *experimental*. Currently, the insertion
+ will replace the containing paragraph. This means that other content in the same
+ paragraph is discarded.
+
#### Conditionals
Sablon can render parts of the template conditonally based on the value of a
context variable. Conditional fields are inserted around the content.
@@ -134,11 +176,11 @@
```
Loops can be used to repeat table rows or list enumerations. The fields need to
be placed in within table cells or enumeration items enclosing the rows or items
to repeat. Have a look at the
-[example template](test/fixtures/sablon_sample.docx) for more details.
+[example template](test/fixtures/cv_template.docx) for more details.
#### Nesting
It is possible to nest loops and conditionals.
@@ -158,28 +200,51 @@
Have a look at [this test](test/executable_test.rb) for examples.
### Examples
-There is a [sample template](test/fixtures/sablon_template.docx) in the
+#### Using a Ruby script
+
+There is a [sample template](test/fixtures/cv_template.docx) in the
repository, which illustrates the functionality of sablon:
<p align="center">
<img
- src="https://raw.githubusercontent.com/senny/sablon/master/misc/template.png"
+ src="https://raw.githubusercontent.com/senny/sablon/master/misc/cv_template.png"
alt="Sablon Template"/>
</p>
Processing this template with some sample data yields the following
-[output document](test/fixtures/sablon_sample.docx).
+[output document](test/fixtures/cv_sample.docx).
For more details, check out this [test case](test/sablon_test.rb).
<p align="center">
<img
- src="https://raw.githubusercontent.com/senny/sablon/master/misc/output.png"
+ src="https://raw.githubusercontent.com/senny/sablon/master/misc/cv_sample.png"
alt="Sablon Output"/>
</p>
+#### Using the sablon executable
+
+The [executable test](test/executable_test.rb) showcases the `sablon`
+executable.
+
+The [template](test/fixtures/recipe_template.docx)
+
+<p align="center">
+ <img
+ src="https://raw.githubusercontent.com/senny/sablon/master/misc/recipe_template.png"
+ alt="Sablon Output"/>
+</p>
+
+is rendered using a [json context](test/fixtures/recipe_context.json) to provide
+the data. Following is the resulting [output](test/fixtures/recipe_sample.docx):
+
+<p align="center">
+ <img
+ src="https://raw.githubusercontent.com/senny/sablon/master/misc/recipe_sample.png"
+ alt="Sablon Output"/>
+</p>
## Contributing
1. Fork it ( https://github.com/[my-github-username]/sablon/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)