Document sections change

CHANGES

@@ -1,3 +1,13 @@
+# 0.4.1 (May 13th, 2015)
+
+Each situation with content is now output as its own `<section>` element. Each situation with content clears the `#current-situation` id from previous situations and gives its content section that id.
+
+Writers, instead of inserting before the `.options` or at the end of the content spool, now insert at the end of the `#current-situation`. This behaviour has ramifications if you're doing strange things with Raconteur situations, but if you're using most of the features as intended this change should be transparent.
+
+The gain from this feature is significant: Situations can now be styled individually, or in groups by giving the situation a `classes` property. 
+
+The major potential pitfalls are: first, the "changeover" happens at the content-printing step of `RaconteurSituation#enter`, so if you define a "before" function in your situation and refer to the `#current-situation` that will still be the *previous* situation. Second, if you are using Undum's low-level API to write to the end of the content spool (With `system#write` for instance) and mixing that with Raconteur writers, you might have odd behaviour where text is popping up where you don't expect it. The fix is to make sure you always `writeInto` the `#current-situation` section, OR that you use `system#write` throughout that situation instead. It might be useful to create a new, empty `#current-situation` at the bottom of the content spool by entering a situation with a function that returns empty string as its content.
+
 # 0.4.0 (May 4th, 2015)
 
 - qualities.js now exports `create()` and `use()`, two functions used to

devel/js/main.js

@@ -182,7 +182,8 @@ situation('continuation', {
     that adds to the existing section, instead of writing a new one.
     `,
   optionText: 'Continuations and Sections',
-  tags: ['testing-option']
+  tags: ['testing-option'],
+  classes: ['styled-situation']
 });
 
 situation ('continuation-continue', {

docs/situation.md

@@ -8,6 +8,12 @@ RaconteurSituation's core features:
 - Built-in support for the most common types of hypertext interactions: Inserting text, replacing text, adding text, and binding custom actions to hyperlinks.
 - `content` among other properties can be defined as either a string, or a function that returns a string. This makes it very easy to refactor simple situations with static text into complex situations with dynamic text.
 
+## current-situation and sections
+
+Raconteur creates the `content` from each new situation as a new `<section>` element on the page. This enables situations to be styled, but it's important to note that Raconteur also relies on tracking which of those sections has the `#current-situation` id; whenever a new situation with content is entered, that id is applied to that situation's section and stripped from all others.
+
+Writing into this element is useful for adding content just before the options list, and it's also the default behaviour of Raconteur writers. This does mean that if you are using Undum's low-level API to write to the end of the content spool, you probably want to use `system.writeInto()` to write inside the current situation.
+
 # Exports
 
 ## situation(name, spec)
@@ -61,6 +67,16 @@ The return value from those functions is discarded. They're intended to be used
 
 A list of situation names and/or tags, used by Undum to construct a list of choices for a situation. Tags should be prefixed with `#`. This list of choices is the last thing outputted when a situation is entered, after `after()` is called.
 
+### classes :: Array
+
+A list of classes that will be added to the `class` attribute of the `<section>` element wrapping the situation's content. If the situation has no content or if its `continueSection` property is truthy, this is disregarded.
+
+The classes given are in addition to the `[situation name]-situation` class that is added to the section by default.
+
+### continueSection :: Boolean
+
+If this is a truthy value, instead of creating a new section, the `content` of this situation is appended to the end of the `#current-situation` section -- Normally, the section created by the previous situation. This can be useful if you want to use a section as a styled element and you want to expand it, for instance if you want to group some sections visually inside a box.
+
 ### content :: String or Function
 
 The main content of the situation. When the situation is entered, `before()` is called as a method on the situation (if present); then `content()` is called, if present. If `content` is a String, it'll be parsed as markdown. If it's a function, it'll be passed the following arguments: