diff options
Diffstat (limited to 'data/doc/sisu/v2/sisu_user_txt/markup_content.txt')
| -rw-r--r-- | data/doc/sisu/v2/sisu_user_txt/markup_content.txt | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_content.txt b/data/doc/sisu/v2/sisu_user_txt/markup_content.txt new file mode 100644 index 00000000..326fabe1 --- /dev/null +++ b/data/doc/sisu/v2/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 + |