path: root/data/doc/sisu/v2/sisu_user_txt/markup_content.txt

                                                                       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