This plugin allows the definition of several documents into one XML file.

Usage:

$ stog --package stog.multi-doc ...
Example

Suppose we have the following XML document in the file smallposts.html at the root of a Stog directory:

<multi sets="smallposts">
  <smallpost id="post1" title="First post" date="2014/01/21">
    The first post ...
  </smallpost>
  <smallpost id="post2" title="Second post" date="2014/01/22">
    The second post ...
  </smallpost>
  <contents type="page" title="My small posts">
    This is the body of the document "/smallpost".
    We can list our small posts here:
    <documents type="smallpost" set="smallposts"/>
  </contents>
</multi>

The muti node at the root of the document indicates that several documents are defined. The whole document is first read as any other document: it can have attributes specified for the multi node, and the body is the contents under this node.

The multi-doc plugin adds a level -10 to cut the documents of type "multi". To do so, each root node of the body is read as if it was in its own file. Here we declare two documents of type "smallpost", with titles, dates and bodies. The <contents> node contains the body of the document "/smallposts". The two other documents are named "/smallposts/post1" and "/smallposts/post2", from the path of the document and their respective ids, using a default separator "/". The <contents> node must have a type attribute.

All documents share the definitions appearing in the original "multi" document, here sets="smallposts".

The paths of the created documents are forged from the path of the "multi" document, the id attribute of each "sub" document and a separator. The default separator is "/" but it can specified with the path-sep attribute:

<multi path-sep="-" ...>
  <smallpost id="post1" ...>...</smallpost>
  <smallpost id="post2" ...>...</smallpost>
  <contents type="...">...</contents>
</multi>

With the code above, the two "smallpost" documents will have paths "/smallposts-post1" and "/smallposts-post2". They can be refered to for example with <doc> rule:

<doc href="/smallposts-post1"/>
Using <with-contents/>

As any other document, one can use the with-contents="true" attribute to indicate that the body of the document is included in a <contents> node. Here is an example using with-contents="true" for the multi document, for the rest of the definition of this documents and for one of the "smallpost" documents:

<multi sets="smallposts"
  with-contents="true"
>
  <!-- definition of a rule, shared by all documents -->
  <st foo=""><strong><contents/></strong></st>
  <!-- body of the "multi" document -->
  <contents>
    <smallpost id="post1" title="First post" date="2014/01/21">
      The first post, with path = "<doc-path/>".
    </smallpost>

    <!-- this document defines a new rule <name>, using with-contents="true"
      and a <contents> node. The new rule is available in this "smallpost"
      document only.
    -->
    <smallpost id="post2" title="Second post" date="2014/01/22"
      with-contents="true">
      <name foo="">Name: <st defer_="1"><contents/></st></name>
      <contents>
        The second post, with path = "<doc-path/>".
        <name>James Bond</name>
      </contents>
    </smallpost>

  <!-- The body of the final document with path "smallposts".
    We use again with-contents="true" do define a new rule
    <hello> for this document only.
  -->
  <contents type="page" title="My small posts"
    with-contents="true">
    <hello name="">Hello <if name=""><dummy_>world</dummy_><name/></if> !</hello>
    <contents>
      <hello name="dear reader"/>
      This is the body of the document "<doc-path/>".
      We can list our small posts here:
      <documents type="smallpost" set="smallposts"/>
    </contents> <!-- contents of the body of the "main" document" -->
  </contents> <!-- contents of the "main" document -->
 </contents> <!-- contents of the multi document -->
</multi>

The result is visible here.