1 files changed, 85 insertions, 21 deletions

diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
index 7db8416e..6c201951 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
@@ -30,6 +30,7 @@
 2~ Summary
 
 SiSU source documents are plaintext (UTF-8)~{ files should be prepared using UTF-8 character encoding }~ files
+={ SiSU markup:description }
 
 All paragraphs are separated by an empty line.
 
@@ -51,21 +52,8 @@ _1* linked text and images
 
 _1* paragraph actions, such as indent, bulleted, numbered-lists, etc.
 
-Some interactive help on markup is available, by typing sisu and selecting markup or sisu --help markup
-
-To check the markup in a file:
-
-_1 sisu --identify [filename].sst
-
-For brief descriptive summary of markup history
-
-_1 sisu --query-history
-
-or if for a particular version:
-
-_1 sisu --query-0.38
-
 2~ Markup Rules, document structure and metadata requirements
+={ SiSU markup:rules and requirements }
 
 minimal content/structure requirement:
 
@@ -79,12 +67,15 @@ minimal content/structure requirement:
 
 ``` code
 A~ (level A [title])
+
 1~ (at least one level 1 [segment/(chapter)])
 ```
+={ output:code markup example;SiSU markup output:code block (tic syntax);code block:tic syntax }
 
 structure rules (document heirarchy, heading levels):
 
 there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any)
+={ SiSU markup:heading levels }
 
 sisu has the fllowing levels:
 
@@ -142,8 +133,10 @@ text                    *
 ```
 
 2~ Markup Examples
+={ SiSU markup:locating examples }
 
 3~ Online
+={ SiSU markup:examples online }
 
 Online markup examples are available together with the respective outputs produced from http://www.jus.uio.no/sisu/SiSU/examples.html or from http://www.jus.uio.no/sisu/sisu_examples/
 
@@ -152,10 +145,12 @@ There is of course this document, which provides a cursory overview of sisu mark
 an alternative presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz
 
 3~ Installed
+={ SiSU markup:examples installed }
 
 With SiSU installed sample skins may be found in: /usr/share/doc/sisu/markup-samples (or equivalent directory) and if sisu-markup-samples is installed also under: /usr/share/doc/sisu/markup-samples-non-free
 
 1~headers Markup of Headers
+={ SiSU markup:headers}
 
 Headers contain either: semantic meta-data about a document, which can be used by any output module of the program, or; processing instructions.
 
@@ -166,8 +161,10 @@ code{
 % this would be a comment
 
 }code
+={ output:code markup example;SiSU markup output:code block (curly brace syntax);code block:curly brace syntax }
 
 2~ Sample Header
+={ SiSU markup:sample header}
 
 This current document is loaded by a master document that has a header similar to this one:
 
@@ -228,6 +225,7 @@ code{
 }code
 
 2~ Available Headers
+={ SiSU markup:headers available }
 
 Header tags appear at the beginning of a document and provide meta information on the document (such as the Dublin Core), or information as to how the document as a whole is to be processed. All header instructions take the form @headername: or on the next line and indented by once space :subheadername: All Dublin Core meta tags are available
 
@@ -355,8 +353,10 @@ code{
 % NOTE: headings/levels below refer to 0.38 expermental markup (a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)
 
 1~ Markup of Substantive Text
+={ SiSU markup:substantive text }
 
 2~heading_levels Heading Levels
+={ SiSU markup:heading levels }
 
 Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section headings, followed by other heading levels, and 1 -6 being headings followed by substantive text or sub-headings. :A~ usually the title :A~? conditional level 1 heading (used where a stand-alone document may be imported into another)
 
@@ -388,12 +388,13 @@ code{
 }code
 
 2~ Font Attributes
+={ SiSU markup:font attributes }
 
 !_ markup example:
 
 code{
 
-normal text,  *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
+normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
 ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
 
 normal text
@@ -448,8 +449,10 @@ _{underscore}_
 #{monospace}#
 
 2~ Indentation and bullets
+={ SiSU markup:indentation and bullets }
 
 !_ markup example:
+={ SiSU markup:indentation }
 
 code{
 
@@ -474,6 +477,7 @@ _2 indent paragraph two steps
 _9 indent paragraph nine steps
 
 !_ markup example:
+={ SiSU markup:bullets }
 
 code{
 
@@ -506,6 +510,7 @@ _# numbered list numbered list indented a., b., c., d., etc.
 }code
 
 2~ Hanging Indents
+={ SiSU markup:hanging indents;indented text:hanging }
 
 !_ markup example:
 
@@ -537,6 +542,7 @@ _0_1 *{live-build}* \\
 A collection of scripts used to build customized Debian Livesystems. /{live-build}/ was formerly known as live-helper, and even earlier known as live-package.
 
 2~ Footnotes / Endnotes
+={ SiSU markup:hanging indents;footnotes;endnotes }
 
 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
 
@@ -611,6 +617,7 @@ normal text~^ continues
 the standard and pair notation cannot be mixed in the same document
 
 2~ Links
+={ SiSU markup:links (text, images);links:images|text }
 
 3~ Naked URLs within text, dealing with urls
 
@@ -658,6 +665,7 @@ deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
 }code
 
 3~link_text Linking Text
+={ SiSU markup:links (text);links:text }
 
 To link text or an image to a url the markup is as follows
 
@@ -716,6 +724,7 @@ about { SiSU book markup examples }:SiSU/examples.html
 about { SiSU book markup examples }:SiSU/examples.html
 
 3~ Linking Images
+={ SiSU markup:links (images);links:images }
 
 !_ markup example:
 
@@ -780,9 +789,51 @@ code{
 
 { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
 
-2~ Grouped Text
+2~ Grouped Text / blocked text
+={ SiSU markup:grouped text;grouped text;blocked text;text blocks }
+
+There are two markup syntaxes for blocked text, using curly braces or using tics
+
+3~ blocked text curly brace syntax
+={ SiSU markup:grouped text;grouped text:curly brace syntax;blocked text:curly brace syntax;text blocks:curly brace syntax }
+
+at the start of a line on its own use name of block type with an opening curly brace, follow with the content of the block, and close with a closing curly brace and the name of the block type, e.g.
+
+``` code
+code{
+
+this is a code block
+
+}code
+```
+
+``` code
+poem{
+
+this here is a poem
+
+}poem
+```
+
+3~ blocked text tic syntax
+={ SiSU markup:grouped text;grouped text:tic syntax;blocked text:tic syntax;text blocks:tic syntax }
+
+code{
+
+``` code
+this is a code block
+```
+
+``` poem
+this here is a poem
+```
+
+}code
+
+start a line with three backtics, a space followed by the name of the name of block type, follow with the content of the block, and close with three back ticks on a line of their own, e.g.
 
 3~ Tables
+={ SiSU markup:tables;tables }
 
 Tables may be prepared in two either of two forms
 
@@ -818,6 +869,8 @@ column three of row two, and so on
 
 }table
 
+% ={ output:table markup example;SiSU markup output:table (curly brace syntax) }
+
 a second form may be easier to work with in cases where there is not much information in each column
 
 *{markup example:}*~{ Table from the Wealth of Networks by Yochai Benkler \\ http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler }~
@@ -870,6 +923,7 @@ No. of articles, all languages  |       25|   19,000|  138,000|  490,000|  862,0
 % }code
 
 3~ Poem
+={ SiSU markup:poem;poems }
 
 !_ basic markup:
 
@@ -935,7 +989,6 @@ poem{
                        you
                       to
                        death."'
-
 }poem
 
 }code
@@ -988,10 +1041,12 @@ poem{
                        you
                       to
                        death."'
-
 }poem
 
+% ={ output:poem markup example;SiSU markup output:poem (curly brace syntax) }
+
 3~ Group
+={ SiSU markup:group text;group text }
 
 !_ basic markup:
 
@@ -1112,8 +1167,10 @@ group{
                        death."'
 
 }group
+={ output:group block markup example;SiSU markup output:group block (curly brace syntax) }
 
 3~ Code
+={ SiSU markup:code block;code block }
 
 Code tags #{ code{ ... }code }# (used as with other group tags described above) are used to escape regular sisu markup, and have been used extensively within this document to provide examples of SiSU markup. You cannot however use code tags to escape code tags. They are however used in the same way as group or poem tags.
 
@@ -1220,10 +1277,13 @@ code{#
                        death."'
 
 }code
+={ output:code markup example;SiSU markup output:code block (curly brace syntax);code block:curly brace syntax }
 
 2~ Additional breaks - linebreaks within objects, column and page-breaks
+={ SiSU markup:breaks (page and line);breaks }
 
 3~ line-breaks
+={ SiSU markup:line break;line break }
 
 To break a line within a "paragraph object", two backslashes \\\\ \\ with a space before and a space or newline after them \\ may be used.
 
@@ -1241,12 +1301,13 @@ The html break br enclosed in angle brackets (though undocumented) is available
 To draw a dividing line dividing paragraphs, see the section on page breaks.
 
 3~ page breaks
+={ SiSU markup:page break;page break }
 
 Page breaks are only relevant and honored in some output formats. A page break or a new page may be inserted manually using the following markup on a line on its own:
 
-page new =\\= (or <:pn>) breaks the page, starts a new page.
+page new =\\= breaks the page, starts a new page.
 
-page break -\\- (or <:pb>) breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
+page break -\\- breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
 
 page break line across page -..- draws a dividing line, dividing paragraphs
 
@@ -1275,6 +1336,7 @@ code{
 }code
 
 2~ Book index
+={ SiSU markup:book index;book index }
 
 To make an index append to paragraph the book index term relates to it, using an equal sign and curly braces.
 
@@ -1343,8 +1405,9 @@ code{
 }code
 
 1~ Composite documents markup
+={ SiSU markup:composite documents;composite documents }
 
-It is possible to build a document by creating a master document that requires other documents. The documents required may be complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built from other documents), it should be named with the suffix *{.ssm}* Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document *{.sst}* regular markup file, or *{.ssi}* (insert). A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}*
+It is possible to build a document by creating a master document that requires other documents. The documents required may be complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built from other documents), it should be named with the suffix *{.ssm}* Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document *{.sst}* regular markup file, or *{.ssi}* (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}*
 
 basic markup for importing a document into a master document
 
@@ -1359,6 +1422,7 @@ code{
 The form described above should be relied on. Within the Vim editor it results in the text thus linked becoming hyperlinked to the document it is calling in which is convenient for editing.
 
 1~ Substitutions
+={ SiSU markup:substitutions;substitutions }
 
 !_ markup example: