Sections

Sections are named entities (or variables if you like) that may change their content on a per-directory basis. When you include a .section(name) placeholder in your template it means you ask to include the content of name section from the same directory containing your current content file into template when producing target file. Each section itself may include other sections, so before inserting it into the template it is processed to resolve all other sections that are defined in it. Sections are stored in _sections.xml file in each directory where you have content files. Each content file may issue a .replace(s1,s2) command that replaces the contents of s1 section with the contents of s2 section. This replacement is only effective for that particular content file.

See the Appendix B: Flow of commands resolution in Commands Reference for an explanation of how nested sections are processed.

In this primer we use sections to define sidebar menu. Since we only have one directory with our pages we will use a single _sections.xml file where we will define all our sections and all their possible variations. There are two sections defined in the template file: description with the main menu and footer with page footer. Naturally they must be declared in our sections file. Let's look at it a bit closer:

<sections>


<!--     Main sections from the template     -->


<section name="description">
  <![CDATA[&.section(home);
  :: &.section(download);
  :: &.section(start);
  :: &.section(tutorial);
  :: &.section(reference);
  :: &.section(support);
  :: &.section(links);
  ]]>
</section>

<section name="footer">
  <![CDATA[&copy; 2007 <a href="http://stas.trefilov.googlepages.com/">Stas Trefilov</a>]]>
</section>


<!--     Menu sections defined in sidebar     -->


<section name="home">
  <![CDATA[<a href="&.root;/">Home</a>]]>
</section>

<section name="download">
  <![CDATA[<a href="http://sourceforge.net/project/showfiles.php?group_id=42851">Download</a>]]>
</section>

<section name="start">
  <![CDATA[<a href="start.html">Introduction</a>]]>
</section>
<section name="start-a">Introduction</section>

<section name="tutorial">
  <![CDATA[<a href="tutorial.html">Tutorial</a>]]>
</section>
<section name="tutorial-a">Tutorial</section>

<section name="reference">
  <![CDATA[<a href="reference.html">Reference</a>]]>
</section>
<section name="reference-a">Reference</section>

<section name="support">
  <![CDATA[<a href="support.html">Support</a>]]>
</section>
<section name="support-a">Support</section>

<section name="links">
  <![CDATA[<a href="links.html">Links</a>]]>
</section>
<section name="links-a">Links</section>

</sections>

Note for the attentive reader: home-a and download-a sectiona are missing since the corresponding pages are not handled by OSB. Homepage is handled by GPC and download page is on sourceforge.net.

First you may notice the definition of our main sections. The description section includes other sections for each menu position, namely home, download, start, tutorial, reference, support and links. Each of these sections describe a concrete menu position and they are defined in the same file right with their "active" versions that do not contain links (like tutorial-a) which will be used on a corresponding page to emphasize the current position in the menu. Just for a reminder, XML requires us to encode HTML special characters like < and > to their corresponding < and > forms if they do not form XML tags in the file. Or alternatively we may use <![CDATA[your tags here]]> format where you may use any symbol from the file codepage.

Now we will use the .replace() commands in content files (like .replace(tutorial,tutorial-a) in tutorial.src file) to indicate which menu position must be active in the sidebar of the page.

In Content file structure and commands in Commands Reference you will find more information on this command.

See below for a way of handling the content files.