Document :separator

mwilliamson · Nov 29, 2016 · d615287 · d615287
1 parent 7a7d1a8
commit d615287
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 0 deletions.
diff --git a/NEWS b/NEWS
@@ -8,6 +8,8 @@
 
 * Allow escape sequences in style IDs, style names and CSS class names.
 
+* Allow a separator to be specified when HTML elements are collapsed.
+
 * Add include_embedded_style_map argument to allow embedded style maps to be
   disabled.
 

diff --git a/README.md b/README.md
@@ -526,6 +526,27 @@ Modifiers must be used in the correct order:
 h1.section-title:fresh
 ```
 
+#### Separators
+
+To specify a separator to place between the contents of paragraphs that are collapsed together,
+use `:separator('SEPARATOR STRING')`.
+
+For instance, suppose a document contains a block of code where each line of code is a paragraph with the style `Code Block`.
+We can write a style mapping to map such paragraphs to `<pre>` elements:
+
+```
+p[style-name='Code Block'] => pre
+```
+
+Since `pre` isn't marked as `:fresh`,
+consecutive `pre` elements will be collapsed together.
+However, this results in the code all being on one line.
+We can use `:separator` to insert a newline between each line of code:
+
+```
+p[style-name='Code Block'] => pre:separator('\n')
+```
+
 #### Nested elements
 
 Use `>` to specify nested elements.