Homec4science
Diffusion invenio-infoscience (iugw2017) Browse

R3600/modules/webstyle/doc/hacking/webstyle-webdoc-syntax.webdoc
9036d847ae65iugw2017

Last Change
Raw File

webstyle-webdoc-syntax.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of Invenio.
## Copyright (C) 2008, 2010, 2011,  CERN.
##
## Invenio 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 2 of the
## License, or (at your option) any later version.
##
## Invenio 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 Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: WebDoc Syntax -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking Invenio</a> &gt; <a class="navtrail" href="webstyle-internals">WebStyle Internals</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<style type="text/css">
<!--
.codeBox {
background-color: #eee;
border: 2px dotted #999;
display: table;
padding: 5px;
}
.list th {
color: #fff;
background-color: #36c;
}
.list tr.blue {
background-color: #ffc;
}
table.list {
border: 1px solid #999;
}
-->
</style>
<p>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.</p>
<h2>Contents</h2>
<ul style="list-style-type:None">
<li><strong>1. <a href="#translation">Translations</a></strong>
<ul style="list-style-type:None">
<li>1.1&nbsp;&nbsp;<a href="#translation1">Using &lt;lang>...&lt;/lang> syntax</a></li>
<li>1.2&nbsp;&nbsp;<a href="#translation2">Using &#95;(...)&#95; syntax</a></li>
</ul>
</li>
<li><strong>2. <a href="#variables">Variables</a></strong></li>
<li><strong>3. <a href="#comments">Comments</a></strong></li>
<li><strong>4. <a href="#headerandfooter">Page header and footer</a></strong></li>
<li><strong>5. <a href="#wellformdness">Well-formdness of WebDoc files</a></strong></li>
</ul>
<h3><a name="translation">1. Translations</a></h3>
<p>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:</p>
<h4><a name="translation1">1.1 Using &lt;lang>...&lt;/lang> syntax</a></h4>
<p>You specify the various translations using the
<code>&lt;lang></code> tag, as well as the various language codes tags
such as <code>&lt;en>, &lt;fr>, &lt;de>,</code> etc.</p>
<pre class="codeBox">
&lt;lang>
&lt;en>Thing&lt;/en>
&lt;fr>Bidule&lt;/fr>
&lt;de>Dings&lt;/de>
&lt;/lang>
</pre>
<p>When shown in German, the above code will display:</p>
<pre class="codeBox">Dings</pre>
<p>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.</p>
<h4><a name="translation2">1.2 Using &#95;(...)&#95; syntax</a></h4>
<p>You use the translations already existing in the po files. Simply
enclose the text to be translated inside parentheses, themselves
enclosed by underscores. Eg: </p>
<code class="codeBox">&#95;(Search)&#95;</code>
<p>When shown in Italian, the above code will display:</p>
<pre class="codeBox">Cerca</pre>
<p>Note that if the text is not in the <code>po</code> files, then the
output will stay the same as the input. If the text is in the
<code>po</code> 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.</p>
<p>This syntax is useful when displaying parts of the web interface,
since there is a high probability that they have already been
translated. Eg:</p>
<pre class="codeBox">
&lt;form action="&lt;CFG_SITE_URL>/search" method="get">
&lt;input size="20" type="text" name="p" value="" />
&lt;select name="f">&lt;option value="">&#95;(any field)&#95;&lt;/option>
&lt;option>&#95;(title)&#95;&lt;/option>
&lt;option>&#95;(author)&#95;&lt;/option>
&lt;/select>
&lt;input class="formbutton" type="submit" name="action" value="&#95;(Search)&#95;" />
&lt;/form>
</pre>
<p>will display:</p>
<form action="<CFG_SITE_URL>/search" method="get" class="codeBox">
<nobr>
<input size="20" type="text" name="p" value="" />
<select name="f"><option value="">_(any field)_</option>
<option>_(title)_</option>
<option>_(author)_</option>
</select>
<input class="formbutton" type="submit" name="action" value="_(Search)_" />
</nobr>
</form>
<p>(Change the language of the page to see the how the controls are updated)</p>
<h3><a name="variables">2. Variables</a></h3>
<p>You can use several special tags that will be replaced by their value at runtime.</p>
<table class="list">
<tr><th>variable</th><th>description</th><th>example</th></tr>
<tr><td><code>&lt;CFG_SITE_NAME></td><td>Name of the website</td><td><CFG_SITE_NAME></td></tr>
<tr class="blue"><td><code>&lt;CFG_SITE_NAME_INTL></code></td><td>Name of the website in the current language</td><td><CFG_SITE_NAME_INTL></td></tr>
<tr><td><code>&lt;CFG_SITE_SUPPORT_EMAIL></code></td><td>Support email address</td><td><CFG_SITE_SUPPORT_EMAIL></td></tr>
<tr class="blue"><td><code>&lt;CFG_SITE_ADMIN_EMAIL></code></td><td>Admin email address</td><td><CFG_SITE_ADMIN_EMAIL></td></tr>
<tr><td><code>&lt;CFG_SITE_URL></code></td><td>Base URL of the website</td><td><CFG_SITE_URL></td></tr>
<tr class="blue"><td><code>&lt;CFG_SITE_SECURE_URL></code></td><td>Secured base URL of the website</td><td><CFG_SITE_SECURE_URL></td></tr>
<tr><td><code>&lt;CFG_VERSION></code></td><td>Version of Invenio</td><td><CFG_VERSION></td></tr>
</table>
<p>Variables are read-only and you can only use the one provided in this table.</p>
<h3><a name="comments">3. Comments</a></h3>
<p>Lines starting with <code>#</code> are simply removed from the
output.</p>
<h3><a name="headerandfooter">4. Page header and footer</a></h3>
<p>The header and footer are automatically added by the
system to the generated page. You also have to omit the
<code>&lt;body></code> 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:</p>
<table class="list">
<tr><th>directive</th><th>description</th></tr>
<tr><td><code>&lt;!-- WebDoc-Page-Title: &#95;(My Title)&#95; --></td><td>Title of the page. It will be embedded in <code>&lt;h1></code> tag at the beginning of the page, as well as in the <code>&lt;title></code> tag of the header. Also used in the breadcrumb of the page ("navtrail")</td></tr>
<tr class="blue"><td><code>&lt;!-- WebDoc-Page-Navtrail: &lt;a class="navtrail" href="&lt;CFG_SITE_URL>/help/hacking">Hacking Invenio&lt;/a> &amp;gt; &lt;a class="navtrail" href="webstyle-internals">WebStyle Internals&lt;/a> --></code></td><td>Specified the breadcrumb of the page.</td></tr>
<tr><td><code>&lt;!-- WebDoc-Page-Keywords: some keywords --></code></td><td>Keywords that will appear in the <code>&lt;meta name="keyword"/></code> tag of the page.</td></tr>
<tr class="blue"><td><code>&lt;!-- WebDoc-Page-Description: a page description --></code></td><td>A description that will appear in the <code>&lt;meta name="description"/></code> tag of the page.</td></tr>
<tr><td><code>&lt;!-- WebDoc-Page-Revision: $Id$ --></code></td><td>The version of the file (typically for CVS keyword expansion).</td></tr>
</table>
<h3><a name="wellformdness">5. Well-formdness of WebDoc files</a></h3>
<p>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.</p>
<p>Please make sure that the produced output is XHTML valid.</p>
<p>For the sake of simplicity, the HTML and the WebDoc markups use the
same namespace. In rare cases the markups might then clash. Eg:
<code>&lt;hr></code> tag (Croatian language code) in
<code>&lt;lang></code> tags. Make sure to test your pages in a browser
and avoid using potentially ambiguous tags.</p>
c4science · Help