SiSU - Markup,
Ralph Amissah

  1

SiSU Markup

  2

2. Markup of Headers

2. Markup of Headers

  25

Headers consist of semantic meta-data about a document, which can be used by any output module of the program; and may in addition include extra processing instructions.

  26

Note: the first line of a document may include information on the markup version used in the form of a comment. Comments are a percentage mark at the start of a paragraph (and as the first character in a line of text) followed by a space and the comment:

  27

  % this would be a comment

  28

2.1 Sample Header

  29

This current document has a header similar to this one (without the comments):

  30

  % SiSU 0.57

  @title: SiSU

  @subtitle: Markup

  @creator: Ralph Amissah

  @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3

  @type: information

  @subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search

  @date.created: 2002-08-28

  @date.issued: 2002-08-28

  @date.available: 2002-08-28

  @date.modified: 2007-09-16

  @date: 2007-09-16

  @level: new=C; break=1; num_top=1

  % comment: in this @level header num_top=1 starts automatic heading numbering at heading level 1 (numbering continues 3 levels down); the new and break instructions are used by the LaTeX/pdf and odf output to determine where to put page breaks (that are not used by html output or say sql database population).

  @skin: skin_sisu_manual

  % skins modify the appearance of a document and are placed in a sub-directory under ./_sisu/skin ~/.sisu/skin or /etc/sisu/skin. A skin may affect single documents that request them, all documents in a directory, or be site-wide. (A document is affected by a single skin)

  @bold: /Gnu|Debian|Ruby|SiSU/

  @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/
  { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/2.html
  { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
  { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/
  { SiSU @ Ruby Application Archive }http://raa.ruby-lang.org/project/sisu/
  { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
  { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
  { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html

  31

2.2 Available Headers

  32

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 either the form @headername: or 0~headername. All Dublin Core meta tags are available

  33

@indentifier: information or instructions

  34

where the "identifier" is a tag recognised by the program, and the "information" or "instructions" belong to the tag/indentifier specified

  35

Note: a header where used should only be used once; all headers apart from @title: are optional; the @structure: header is used to describe document structure, and can be useful to know.

  36

This is a sample header

  37

% SiSU 0.38 [declared file-type identifier with markup version]

  38

@title: [title text] This is the title of the document and used as such, this header is the only one that is mandatory

  39

@subtitle: The Subtitle if any

  40

@creator: [or @author:] Name of Author

  41

@subject: (whatever your subject)

  42

@description:

  43

@publisher:

  44

@contributor:

  45

@translator: [or @translated_by:]

  46

@illustrator: [or @illustrated_by:]

  47

@prepared_by: [or @digitized_by:]

  48

@date: 2000-08-27 [ also @date.created: @date.issued: @date.available: @date.valid: @date.modified: ]

  49

@type: article

  50

@format:

  51

@identifier:

  52

@source:

  53

@language: [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bul garian ) [however, encodings are not available for all of the languages listed.]

  54

[@language.original: original language in which the work was published]

  55

@papersize: (A4|US_letter|book_B5|book_A5|US_legal)

  56

@relation:

  57

@coverage:

  58

@rights: Copyright (c) Name of Right Holder, all rights reserved, or as granted: public domain, copyleft, creative commons variant, etc.

  59

@owner:

  60

@keywords: text document generation processing management latex pdf structured xml citation [your keywords here, used for example by rss feeds, and in sql searches]

  61

@abstract: [paper abstract, placed after table of contents]

  62

@comment: [...]

  63

@catalogue: loc=[Library of Congress classification]; dewey=[Dewey classification]; isbn=[ISBN]; pg=[Project Gutenberg text number]

  64

@classify_loc: [Library of Congress classification]

  65

@classify_dewey: [Dewey classification]

  66

@classify_isbn: [ISBN]

  67

@classify_pg: [Project Gutenberg text number]

  68

@prefix: [prefix is placed just after table of contents]

  69

@prefix_a: [prefix is placed just before table of contents - not implemented]

  70

@prefix_b:

  71

@rcs: $Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ [used by rcs or cvs to embed version (revision control) information into document, rcs or cvs can usefully provide a history of updates to a document ]

  72

@structure: PART; CHAPTER; SECTION; ARTICLE; none; none;
optional, document structure can be defined by words to match or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used within text instead, without this header tag, and may be used to supplement the instructions provided in this header tag if provided (@structure: is a synonym for @toc:)

  73

@level: newpage=3; breakpage=4
[paragraph level, used by latex to breakpages, the page is optional eg. in newpage]

  74

@markup: information on the markup used, e.g. new=1,2,3; break=4; num_top=4 [or newpage=1,2,3; breakpage=4; num_top=4] newpage and breakpage, heading level, used by LaTeX to breakpages. breakpage: starts on a new page in single column text and on a new column in double column text; newpage: starts on a new page for both single and double column texts.
num_top=4 [auto-number document, starting at level 4. the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level]
num_extract [take numbering of headings provided (manually in marked up source document), and use for numbering of segments. Available where a clear numbering structure is provided within document, without the repetition of a number in a header.] [In 0.38 notation, you would map to the equivalent levels, the examples provided would map to the following new=A,B,C; break=1; num_top=1 [or newpage=A,B,C; breakpage=1; num_top=1] see headings]

  75

@bold: [regular expression of words/phrases to be made bold]

  76

@italics: [regular expression of words/phrases to italicise]

  77

@vocabulary: name of taxonomy/vocabulary/wordlist to use against document

  78

@skin: skin_doc_[name_of_desired_document_skin]
skins change default settings related to the appearance of documents generated, such as the urls of the home site, and the icon/logo for the document or site.

  79

@links: { SiSU }http://www.jus.uio.no/sisu/;
{ FSF }http://www.fsf.org

  80

@promo: sisu, ruby, search_libre_docs, open_society
[places content in right pane in html, makes use of list.yml and promo.yml, commented out sample in document sample: free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst]

  81

Output generated by SiSU 0.59.0 2007-09-23 (2007w38/0)
SiSU Copyright ^© Ralph Amissah 1997, current 2007. All Rights Reserved.
SiSU is software for document structuring, publishing and search,
www.jus.uio.no/sisu and www.sisudoc.org
w3 since October 3 1993 ralph@amissah.com

SiSU using:
Standard SiSU markup syntax,
Standard SiSU meta-markup syntax, and the
Standard SiSU object citation numbering and system, (object/text positioning system)
Copyright ^© Ralph Amissah 1997, current 2007. All Rights Reserved.

SiSU is released under GPLv3 or later, <http://www.gnu.org/licenses/gpl.html>

SiSU, developed using Ruby on Debian/Gnu/Linux software infrastructure, with the usual GPL (or OSS) suspects.
Better - "performance, reliability, scalability, security & total cost of ownership" [not to mention flexibility & choice] use of and adherence to open standards (where practical and fair) and it is software libre.
Get With the Future Way Better!