aboutsummaryrefslogtreecommitdiffhomepage
path: root/data/doc/sisu/v3/sisu_user_txt
diff options
context:
space:
mode:
Diffstat (limited to 'data/doc/sisu/v3/sisu_user_txt')
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/configuration.txt8
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/configuration_css.txt9
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/configuration_sisurc.txt137
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/configuration_skin.txt15
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/index.txt5
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/markup.txt11
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/markup_content.txt296
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/markup_headers_metadata.txt34
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/markup_headers_processing_instructions.txt12
-rw-r--r--data/doc/sisu/v3/sisu_user_txt/markup_minimum_requirement.txt79
10 files changed, 606 insertions, 0 deletions
diff --git a/data/doc/sisu/v3/sisu_user_txt/configuration.txt b/data/doc/sisu/v3/sisu_user_txt/configuration.txt
new file mode 100644
index 00000000..1f122d56
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/configuration.txt
@@ -0,0 +1,8 @@
+ index.txt
+%% configuration ---------------------------------------------------------------
+
+configuration_sisurc.txt
+
+configuration_skin.txt
+
+configuration_css.txt
diff --git a/data/doc/sisu/v3/sisu_user_txt/configuration_css.txt b/data/doc/sisu/v3/sisu_user_txt/configuration_css.txt
new file mode 100644
index 00000000..17fb2e97
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/configuration_css.txt
@@ -0,0 +1,9 @@
+ index.txt
+ configuration.txt
+%% css ------------------------------------------------------------------------
+
+the default css may be replaced for the site or particular processing
+directories
+
+[provide information]
+
diff --git a/data/doc/sisu/v3/sisu_user_txt/configuration_sisurc.txt b/data/doc/sisu/v3/sisu_user_txt/configuration_sisurc.txt
new file mode 100644
index 00000000..62a2ce02
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/configuration_sisurc.txt
@@ -0,0 +1,137 @@
+ index.txt
+ configuration.txt
+%% config, sisurc.yml ----------------------------------------------------------
+
+There are default configuration settings within the program many of which can
+be modified in sisurc.yml
+
+sisurc.yml can be located in one of the following locations:
+/etc/sisu/sisurc.yml ~/.sisu/sisurc.yml and ./_sisu/sisurc.yml
+
+if sisu versions 1 and 2 are both in use, the v2 sisurc.yml can be placed a the
+following locations:
+/etc/sisu/v2/sisurc.yml ~/.sisu/v2/sisurc.yml and ./_sisu/v2/sisurc.yml
+
+# Name: SiSU - Simple information Structuring Universe
+# Author: Ralph@Amissah.com
+# Description: Site wide envionment defaults set here
+# system environment info / resource configuration file, for sisu
+# License: GPL v3 or later
+# site environment configuration file
+# this file should be configured and live in
+# /etc/sisu #per environment settings, overridden by:
+# ~/.sisu #per user settings, overridden by:
+# ./_sisu #per local markup directory settings
+#% #image source directory, main path and subdirectories
+#image:
+# path: 'sisu_working'
+# public: '_sisu/image'
+#% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name)
+#webserv:
+# url_root: 'http://www.your.url' #without dir stub
+# path: '/var/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
+# images: '_sisu/image'
+# man: 'man'
+# cgi: '/usr/lib/cgi-bin'
+# feed: 'feed'
+# sqlite: 'sisu/sqlite'
+# webrick_url: true
+#show_output_on: 'filesystem' #for -v and -u url information, alternatives: 'filesystem','webserver','remote_webserver','local:8111','localhost','localhost:8080','webrick','path'
+#show_output_on: 'local:8111'
+#webserv_cgi:
+# host: localhost
+# base_path: ~
+# port: '8081'
+# user: ~
+show_output_on: 'filesystem_url'
+#texinfo display output
+#texinfo:
+# stub: 'texinfo'
+##% processing directories, main path and subdirectories (appended to $HOME), using defaults set in sysenv
+#processing:
+# path: '~'
+# dir: '.sisu_processing~'
+# metaverse: 'metaverse'
+# tune: 'tune'
+# latex: 'tex'
+# texinfo: 'texinfo'
+# concord_max: 400000
+#% flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding colour and verbosity as default)
+flag:
+ color: true # making colour default -c is toggle, and will now toggle colour off
+ default: '-NhwepoabxXyYv' # -m run by default; includes verbose
+ i: '-hwpoay' # -m run by default
+ ii: '-NhwepoabxXy' # -m run by default
+ iii: '-NhwepoabxXyY' # -m run by default
+ iv: '-NhwepoabxXYDy --update' # -m run by default
+ v: '-NhwepoabxXYDyv --update' # -m run by default; includes verbose
+#% papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal
+default:
+ papersize: 'A4,letter'
+ #text_wrap: 78
+ #emphasis: 'bold' #make *{emphasis}* 'bold', 'italics' or 'underscore', default if not configured is 'bold'
+ #digest: 'sha' #sha is sha256, default is md5
+ #multilingual: false
+ #language_file: 2
+ #language: 'English'
+#% markup, make *{emphasis}* 'bold' or 'italics', default if not configured is 'bold'
+#% settings used by ssh scp
+#remote:
+# -
+# user: '[usrname]'
+# host: '[remote.hostname]'
+# path: '.' #no trailing slash eg 'sisu/www'
+# -
+# user: '[usrname]'
+# host: '[remote.hostname]'
+# path: '.' #no trailing slash eg 'sisu/www'
+#% webrick information
+#webrick:
+# port: '8081'
+#% sql database info, postgresql and sqlite
+#db:
+# share_source: false # boolean, default is false
+# postgresql:
+# port: # '[port (default is 5432)]'
+# host: # '[if not localhost, provide host tcp/ip address or domain name]''
+# user: # '[(if different from user) provide username]'
+# password: # '[password if required]'
+# sqlite:
+# path: ~ # './sisu_sqlite.db'
+# port: "**"
+#% possible values ~, true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'.
+#will only ignore if value set to false, absence or nil will not remove program as should operate without rc file
+#ie in case of ~ will ignore and use hard coded defaults within program), true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'
+#on value true system defaults used, to change, e.g. editor specify
+permission_set:
+ zap: false
+ css_modify: false
+# remote_base_site: true
+program_set:
+ rmagick: false
+# wc: true
+# editor: true
+# postgresql: true
+# sqlite: true
+# tidy: true
+# rexml: true
+# pdflatex: true
+#program_select:
+# editor: 'gvim -c :R -c :S'
+# pdf_viewer: 'evince'
+# web_browser: 'firefox' #'iceweasel' #'epiphany' #'galeon' #'konqueror' #'kazehakase'
+# console_www_browser: 'links2' #'elinks'
+# odf_viewer: 'oowriter' #'abiword'
+# xml_viewer: 'xml-viewer'
+# man: 'nroff -man' #'groff -man -Tascii' # 'nroff -man'
+#promo: sisu_icon, sisu, sisu_search_libre, open_society, fsf, ruby
+#search:
+# sisu:
+# flag: true
+## action: http://localhost:8081/cgi-bin/sisu_pgsql.cgi
+# action: http://search.sisudoc.org
+# db: sisu
+# title: sample search form
+# hyperestraier:
+# flag: true
+# action: http://search.sisudoc.org/cgi-bin/estseek.cgi?
diff --git a/data/doc/sisu/v3/sisu_user_txt/configuration_skin.txt b/data/doc/sisu/v3/sisu_user_txt/configuration_skin.txt
new file mode 100644
index 00000000..2695dda8
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/configuration_skin.txt
@@ -0,0 +1,15 @@
+ index.txt
+ configuration.txt
+%% skin ------------------------------------------------------------------------
+
+skins can be used to modify the appearance of output
+
+[provide information]
+
+%% css ------------------------------------------------------------------------
+
+the default css may be replaced for the site or particular processing
+directories
+
+[provide information]
+
diff --git a/data/doc/sisu/v3/sisu_user_txt/index.txt b/data/doc/sisu/v3/sisu_user_txt/index.txt
new file mode 100644
index 00000000..3e66cb19
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/index.txt
@@ -0,0 +1,5 @@
+%% Summary ---------------------------------------------------------------------
+
+markup.txt
+
+configuration.txt
diff --git a/data/doc/sisu/v3/sisu_user_txt/markup.txt b/data/doc/sisu/v3/sisu_user_txt/markup.txt
new file mode 100644
index 00000000..4ab55606
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/markup.txt
@@ -0,0 +1,11 @@
+ index.txt
+%% Summary ---------------------------------------------------------------------
+
+markup_minimum_requirement.txt
+
+markup_content.txt
+
+markup_headers_metadata.txt
+
+markup_headers_processing_instructions.txt
+
diff --git a/data/doc/sisu/v3/sisu_user_txt/markup_content.txt b/data/doc/sisu/v3/sisu_user_txt/markup_content.txt
new file mode 100644
index 00000000..326fabe1
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/markup_content.txt
@@ -0,0 +1,296 @@
+ index.txt
+ markup.txt
+%% The Gory Details ------------------------------------------------------------
+
+%% comments --------------------------------------------------------------------
+
+Comments in sisu are a percentage sign at the start of a line followed by a
+space and then the comment
+
+% this would be a comment
+
+%% headings --------------------------------------------------------------------
+
+There are two sets of docment heading markers :A~ and an optional :B~ & :C~ and
+beneath that 1~, 2~, 3~. These markers are placed at the start of the
+line/paragraph, and followed by the heading
+
+There is usually one :A~ top level heading, which is the document title,
+sometimes including the author. This is such a common occurrence that there is
+a shortcut where metadata headers are provided for @title: and @creator
+:author:, instead of rewriting the title and author's name, you may write :A~
+@title @author
+
+If you have a document/manuscript that has subsections above the level of
+chapter, such as multiple books, parts, section, two additional top level
+headings are available :B~ and :C~
+
+At the main division level, usually chapter heading level 1~ begins, followed
+by 2~ and 3~ if the chapter has subheadings. Because the html and epub
+segmented output breaks level 1~ into separate files it is possible to provide
+the filename, e.g. 1~prologue Prologue
+
+Where names are provided following the heading tilde, these become tagged
+points within the document which can where the output format permits be
+(hyper-)linked to.
+
+%% font effect, modified font including emphasis -------------------------------
+
+Whithin normal text it is possible to modify the font effect of a word or
+phrase using the following markers:
+
+!{ bold }!
+
+/{ italics }/
+
+_{ underscore }_
+
+*{ emphasis }* (how emphasis is represented in output text can be defined in
+the header @make: section of a document or in the sisurc.yml config file, and
+this may be as bold, italics or underscore, the default being bold)
+
+^{ superscript }^
+
+,{ subscript },
+
++{ inserted text }+
+
+_{ strikethrough }_
+
+An exclamation mark followed by an underscore at the start of a line will bold
+that line until the first line-break
+
+!_ this line would be bold
+
+It is also possible to define in the header section under the @make: section
+which words or patterns should automatically be made bold or italics.
+
+@make:
+ :bold: /Gnu|Linux|Debian|Fedora|Ruby|SiSU/
+ :italics: /inter alia/
+
+%% indent ----------------------------------------------------------------------
+
+_1 a paragraph that is indented one level
+
+_2 a paragraph that is indented two steps
+
+%% bullet ----------------------------------------------------------------------
+
+_* bulleted text
+
+_1* bulleted indented text
+
+%% auto-numbering -------------------------------------------------------------
+
+Some auto-numbering occurs in the building of sisu documents, either by default
+or when requested through configuration options
+
+%% auto-numbering document objects ---------------------------------------------
+
+Document objects are automatically given sequential object numbers, object
+citation numbers (ocn). If there is text that for some reason should not be
+regarded as substantive objects, it is possible to prevent a document number
+being given by adding ~# to the end of the object (paragraph/heading, etc.) ~#
+
+A variation used for headings that are added to provide document structure that
+should where possible not be included in output is -# a heading that is marked
+with -# is un-numbered and may be excluded from document outputs.
+
+%% auto-numbering headings -----------------------------------------------------
+
+Note auto-numbering of headings may be specified in the header @make: :num_top:
+by providing the heading level from which numbering is to start, this is
+usually at the chapter level (1~).
+
+@make:
+ :num_top: 1
+
+numbering continues three levels down, level 1 being numbered 1, 2, 3 ...
+level 2: 1.1, 1.2, 1.3 and so on
+level 3: 1.1.1, 1.1.2, 1.1.3
+
+It is also possible to make an auto-numbered list
+
+# numbered list numbered list 1., 2., 3, etc.
+
+_# indented lettered list sub-level of previous list number a., b., c., d., etc.
+
+%% line breaks -----------------------------------------------------------------
+
+<:br> line break
+
+In paper/ page oriented outputs, such as LaTeX/pdf the following are avaiable
+
+<:pb> page or column break
+
+<:pn> new page
+
+in the header section under @make: :breaks: new and break set a page break or
+new page at the levels indicated, e.g.
+
+@make:
+ :breaks: new=C; break=1
+
+%% footnotes / endnotes --------------------------------------------------------
+
+This paragraph contains a footnote~{ a footnote or endnote }~ which would be
+automatically numbered
+
+Footnotes and endnotes are marked up at the location where they would be
+indicated within a text. They are automatically numbered. The output type
+determines whether footnotes or endnotes will be produced
+
+In addition to regular footnotes/endnotes there are astrisk and plus sign
+numbered and unnumbered footnotes.
+
+normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
+
+%% tag points ------------------------------------------------------------------
+
+Tag points are markers within the document which may be used within the
+document for (internal document) linking where the output format permits. Tag
+names should use alphanumeric characters and underscores [a-z0-9_]+.
+
+There are different types of tag point, some automatically provided by sisu,
+such as each ocn (object citation number)
+
+Manual tags may be provided either:
+
+(a) with headings where a name is added to the heading level after the tilde:
+
+1~prefix [heading]
+
+(b) a tag marker can be added to a paragraph using an asterisk tilde and the
+name *~tag_marker
+
+%% links and urls --------------------------------------------------------------
+
+Urls found within text are marked up automatically, and where the output type
+permits is autmatically hyperlinked to inself and decorated with angled braces
+(unless contained in a code block, or escaped by a preceeding underscore).
+
+To link text or an image to a url the markup is as follows
+
+{ this is the linked section of text}http://url.org
+
+Where it is wished to include the url for the linked text in a footnote, the
+long form of markup would be:
+{ SiSU }http://www.jus.uio.no/sisu/ ~{ http://www.jus.uio.no/sisu/ }~
+
+A short form is provided for achieving the same:
+ {~^ SiSU }http://www.jus.uio.no/sisu/
+
+%% images ----------------------------------------------------------------------
+
+Images are placed in the directory beneath the location of the document to be
+processed _sisu/image
+
+The following are examples of links to images
+
+{ tux.png 64x80 }image
+
+{tux.png 64x80 "Gnu/Linux - a better way" }http://www.jus.uio.no/sisu/
+
+{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.jus.uio.no/sisu/
+
+The 64x80 in the first example is the image dimension, (width x height). This
+may be omitted if imagemagick or graphicsmagick are installed, as they will
+determine the image dimensions
+
+As with other linked text, the following markup
+
+{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
+
+maps to
+
+{ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ ~{ http://www.ruby-lang.org/en/ }~
+
+%% grouped text ----------------------------------------------------------------
+
+%% group -----------------------------------------------------------------------
+
+The start and end of text that is grouped are tagged. Grouped text retains its
+line breaks, and is treated as a unit, getting a single ocn
+
+group{
+
+License: GPL 3 or later:
+
+SiSU, a framework for document structuring, publishing and search
+
+Copyright (C) Ralph Amissah
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <http://www.gnu.org/licenses/>.
+
+If you have Internet connection, the latest version of the GPL should be
+available at these locations:
+<http://www.fsf.org/licensing/licenses/gpl.html>
+<http://www.gnu.org/licenses/gpl.html>
+
+}group
+
+%% poem ------------------------------------------------------------------------
+
+The start and end of a poem are tagged. Each verse in a poem is given an object
+number. Verses retain their line breaks.
+
+poem{
+
+verse here
+declare
+
+another verse
+here
+
+}poem
+
+%% table -----------------------------------------------------------------------
+
+{table~h 24; 12; 12; 12; 12; 12; 12;}
+ |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
+Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
+Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
+Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
+No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
+No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
+
+
+table{ c3; 40; 30; 30;
+
+This is a table
+this would become column two of row one
+column three of row one is here
+
+And here begins another row
+column two of row two
+column three of row two, and so on
+
+}table
+
+a second form may be easier to work with in cases where there is not much information in each column
+
+%% code ------------------------------------------------------------------------
+
+code{
+
+code lines here
+
+and so on
+
+}code
+
diff --git a/data/doc/sisu/v3/sisu_user_txt/markup_headers_metadata.txt b/data/doc/sisu/v3/sisu_user_txt/markup_headers_metadata.txt
new file mode 100644
index 00000000..c24789c8
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/markup_headers_metadata.txt
@@ -0,0 +1,34 @@
+ index.txt
+ markup.txt
+%% headers ---------------------------------------------------------------------
+
+%% header metadata -------------------------------------------------------------
+
+@title: SiSU
+ :subtitle: Markup
+
+@creator:
+ :author: Amissah, Ralph
+
+@rights:
+ :copyright: Copyright (C) Ralph Amissah 2007, part of SiSU documentation
+ :license: GPL 3 or later
+
+@classify:
+ :type: information
+ :topic_register: electronic documents:SiSU:document:markup;SiSU:document:markup;SiSU:document:markup;SiSU:manual:markup;electronic documents:SiSU:manual:markup
+ :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
+
+@date:
+ :created: 2002-08-28
+ :issued: 2002-08-28
+ :available: 2002-08-28
+ :published: 2008-05-22
+ :modified: 2010-05-25
+
+@links:
+ { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/
+ { Book Samples and Markup Examples }http://www.jus.uio.no/SiSU/examples.html
+ { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
+ { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
+ { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
diff --git a/data/doc/sisu/v3/sisu_user_txt/markup_headers_processing_instructions.txt b/data/doc/sisu/v3/sisu_user_txt/markup_headers_processing_instructions.txt
new file mode 100644
index 00000000..b2c559c1
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/markup_headers_processing_instructions.txt
@@ -0,0 +1,12 @@
+ index.txt
+ markup.txt
+%% header processing instructions, @make: --------------------------------------
+
+Some document processing parameters can be set in the @make: section of the header
+
+@make:
+ :num_top: 1
+ :breaks: new=C; break=1
+ :skin: skin_sisu_manual
+ :bold: /Gnu|Debian|Ruby|SiSU/
+
diff --git a/data/doc/sisu/v3/sisu_user_txt/markup_minimum_requirement.txt b/data/doc/sisu/v3/sisu_user_txt/markup_minimum_requirement.txt
new file mode 100644
index 00000000..27b5b774
--- /dev/null
+++ b/data/doc/sisu/v3/sisu_user_txt/markup_minimum_requirement.txt
@@ -0,0 +1,79 @@
+ index.txt
+ markup.txt
+%% Summary ---------------------------------------------------------------------
+
+sisu takes an ASCII (UTF-8) document and abstracts the document into its
+structure and smaller constituent parts, objects. This abstraction is then used
+in subsequent processing to reconstitute the document into disparate document
+representations, many quite different from one another, e.g. HTML, ODF, LaTeX
+and to populate SQL
+
+SiSU identifies the document structure (headings and their levels) and pulls
+the document apart in to its constituent parts, objects (paragraphs, headings,
+tables, images etc.) to which it assigns an object number if substantive
+content.
+
+From the marked up document SiSU need to be able to determine a documents
+structure, and the objects that a document contains
+
+The first line of a SiSU marked up document can identify itself with
+
+%% Identify SiSU Document ------------------------------------------------------
+
+% SiSU
+
+%% The Basic SiSU Markup Document ----------------------------------------------
+
+SiSU documents are divided into two parts, (i) the document header and (ii)
+substantive content.
+
+(i) the document header, which contains (a) metadata and (b) processing
+instructions if any. Document headers take the form of a tag and the related
+related information. The Document header, metadata, should contain at least:
+
+@title:
+
+@creator:
+ :author:
+
+Processing instructions are grouped under the @make: tag. In the absence of any
+program (or configured) defaults will be used.
+
+(ii) for the substantive content the document structure must be defined, here
+structure equates to the headings and their relative levels (this can be done
+either by explicit markup where each heading occurs, or in the header @make:
+section of the, or both).
+
+The basic document objects are headings and paragraphs. Paragraphs are
+identified automatically, and headings must be defined (with respect to
+document structure), so sisu is able to determine the basic objects without
+anything further.
+
+sample_1.sst
+
+%% Document Structure (heading levels) -----------------------------------------
+
+Document structure (heading levels) are determined from information provided in
+the markup of the document. There are two ways to identify document structure:
+(i) manual markup of headings with their level; (ii) in the sisu header, under
+@make: :heading: provide a regex, in the manner understood by sisu, that
+identifies what to look for in headings of various levels.
+
+Document structure is the different headings in a document, and their relative
+levels.
+
+There are two sets of docment level markers :A~ and an optional :B~ & :C~ and
+beneath that 1~, 2~, 3~.
+
+For the first set of document level markers the document Title being the top
+level in the hierarchy; beneath that book titles if the document contains more
+than one book followed by sections
+
+%% Document Objects (paragraphs, headings, tables, verse etc.) -----------------
+
+Document objects are units of text that are identified, stored and processed as
+a block. The most usual document objects would be paragraphs and headings. A
+more complete list of objects includes: paragraphs; headings; tables; code
+blocks; verse (the poem is identified, but each verse is an object); grouped
+text...
+