10. Markup of Headers

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.

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:

  % this would be a comment

10.1 Sample Header

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

  % 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/examples.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

10.2 Available Headers

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

@indentifier: information or instructions

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

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.

This is a sample header

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

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

@subtitle: The Subtitle if any

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

@subject: (whatever your subject)

@description:

@publisher:

@contributor:

@translator: [or @translated_by:]

@illustrator: [or @illustrated_by:]

@prepared_by: [or @digitized_by:]

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

@type: article

@format:

@identifier:

@source:

@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.]

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

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

@relation:

@coverage:

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

@owner:

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

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

@comment: [...]

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

@classify_loc: [Library of Congress classification]

@classify_dewey: [Dewey classification]

@classify_isbn: [ISBN]

@classify_pg: [Project Gutenberg text number]

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

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

@prefix_b:

@rcs: $Id: sisu_markup.sst,v 1.1 2008/12/11 02:50:34 ralph Exp ralph $ [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 ]

@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:)

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

@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]

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

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

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

@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.

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

@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]