WebDoc Syntax

WebDoc files are used for the documentation of Invenio. WebDoc syntax is based on HTML, plus some additional markup that provides the necessary features to generate basic "dynamic" pages.

1. Translations
- 1.1 Using <lang>...</lang> syntax
- 1.2 Using _(...)_ syntax
2. Variables
3. Comments
4. Page header and footer
5. Well-formdness of WebDoc files

1. Translations

The different translations of a page are all embedded in the same webdoc file. There are two ways to translate the strings of a WebDoc file:

1.1 Using <lang>...</lang> syntax

You specify the various translations using the <lang> tag, as well as the various language codes tags such as <en>, <fr>, <de>, etc.

<lang>
	<en>Thing</en>
	<fr>Bidule</fr>
	<de>Dings</de>
</lang>

When shown in German, the above code will display:

Dings

When shown in a language for which there is no translation, the system first tries to display the translation in the CFG_SITE_LANG language, and then in English if it fails.

1.2 Using _(...)_ syntax

You use the translations already existing in the po files. Simply enclose the text to be translated inside parentheses, themselves enclosed by underscores. Eg:

_(Search)_

When shown in Italian, the above code will display:

Cerca

Note that if the text is not in the po files, then the output will stay the same as the input. If the text is in the po files but the translation does not exist for the current language, then the system first tries to display the translation in the CFG_SITE_LANG language, and then in English it it fails.

This syntax is useful when displaying parts of the web interface, since there is a high probability that they have already been translated. Eg:

<form action="<CFG_SITE_URL>/search" method="get">
    <input size="20" type="text" name="p" value="" />
    <select name="f"><option value="">_(any field)_</option>
                     <option value="_(title)_">_(title)_</option>
                     <option value="_(author)_">_(author)_</option>
    </select>
    <input class="formbutton" type="submit" name="action" value="_(Search)_" />
</form>

will display:

(Change the language of the page to see the how the controls are updated)

2. Variables

You can use several special tags that will be replaced by their value at runtime.

variable	description	example
`<CFG_SITE_NAME>`	Name of the website	SSTP5
`<CFG_SITE_NAME_INTL>`	Name of the website in the current language	SSTP5
`<CFG_SITE_SUPPORT_EMAIL>`	Support email address	invenio@aipberoun.cz
`<CFG_SITE_ADMIN_EMAIL>`	Admin email address	invenio@aipberoun.cz
`<CFG_SITE_URL>`	Base URL of the website	http://managetei.manuscriptorium.com
`<CFG_SITE_SECURE_URL>`	Secured base URL of the website	https://managetei.manuscriptorium.com
`<CFG_VERSION>`	Version of Invenio	1.2.2

Variables are read-only and you can only use the one provided in this table.

3. Comments

Lines starting with # are simply removed from the output.

4. Page header and footer

The header and footer are automatically added by the system to the generated page. You also have to omit the <body> tag. However you can (and should) use the following directives at the beginning of the WebDoc file to change the properties of the header and footer:

directive	description
`<!-- WebDoc-Page-Title: _(My Title)_ -->`	Title of the page. It will be embedded in `<h1>` tag at the beginning of the page, as well as in the `<title>` tag of the header. Also used in the breadcrumb of the page ("navtrail")
`<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking Invenio</a> > <a class="navtrail" href="webstyle-internals">WebStyle Internals</a> -->`	Specified the breadcrumb of the page.
`<!-- WebDoc-Page-Keywords: some keywords -->`	Keywords that will appear in the `<meta name="keyword"/>` tag of the page.
`<!-- WebDoc-Page-Description: a page description -->`	A description that will appear in the `<meta name="description"/>` tag of the page.
`<!-- WebDoc-Page-Revision: $Id$ -->`	The version of the file (typically for CVS keyword expansion).

5. Well-formdness of WebDoc files

WebDoc files must be well-formed XML files (except for the variables specified in section 2). Failing to fulfill this requirement might lead to unexpected results.

Please make sure that the produced output is XHTML valid.

For the sake of simplicity, the HTML and the WebDoc markups use the same namespace. In rare cases the markups might then clash. Eg: <hr> tag (Croatian language code) in <lang> tags. Make sure to test your pages in a browser and avoid using potentially ambiguous tags.