- Expanded the markup allowed in l10n format strings

* doc/xslt/C/translating.xml:
* i18n/STYLESHEETS.xhtml:
* xslt/docbook/html/Makefile.am:
* xslt/docbook/html/db2html.xsl:
* xslt/docbook/html/db2html-l10n.xsl:
- Expanded the markup allowed in l10n format strings

1 files changed, 44 insertions, 10 deletions

diff --git a/i18n/STYLESHEETS.xhtml b/i18n/STYLESHEETS.xhtml
index 103791c..e5f7b99 100644
--- a/i18n/STYLESHEETS.xhtml
+++ b/i18n/STYLESHEETS.xhtml
@@ -391,11 +391,11 @@ msgstr ""
     Redundant <tt class="sgmltag-element">msgid</tt> elements are sometimes used even
     when neither plural forms nor roles are being used.  In those cases,
     the sole translatable string is placed in a <tt class="sgmltag-element">msgstr</tt>
-    element with no attributes.</p></div><div class="section"><a name="translating-formats"/><h2 class="section title"><span class="title"><span class="label">4. </span>Format Strings</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The Gnome documentation stylesheets can translate more than simple
-    strings using specialized format strings.  These are similar in principle
-    to format strings used in C programs, except that XML is used to insert
-    named parameters, rather than special format tokens being used to insert
-    positional parameters.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">For instance, DocBook provides the <tt class="sgmltag-element">quote</tt> element,
+    element with no attributes.</p></div><div class="section"><a name="translating-formats"/><h2 class="section title"><span class="title"><span class="label">4. </span>Format Strings</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Using specialized format strings, the Gnome documentation stylesheets
+    can translate more than just simple strings.  These format strings are
+    similar in principle to format strings used in C programs, except that
+    XML is used to insert named parameters, rather than special format tokens
+    being used to insert positional parameters.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">For instance, DocBook provides the <tt class="sgmltag-element">quote</tt> element,
     used to mark inline quotations. How to render an inline quotation depends
     on the typographic conventions of the language.  In U.S. English, they are
     rendered inside “double inverted-comma” quotation marks.  In Serbian, they
@@ -419,11 +419,45 @@ msgstr ""
     These arguments should be documented in the translator comments that
     accompany the string.  Note that the default translation may not make
     use of all the available arguments.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">In addition to marker elements in format strings, translators
-    may also use simple inline formatting markup.  Currently, the only
-    supported elements are <tt class="sgmltag-element">i</tt> for italics,
-    <tt class="sgmltag-element">b</tt> for bold, and <tt class="sgmltag-element">tt</tt> for
-    monospace.  This may be expanded to include all of PangoMarkup
-    in the future.</p></div><div class="section"><a name="translating-types"/><h2 class="section title"><span class="title"><span class="label">5. </span>Common Formatter Types</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">There are a number of common types of format strings that are
+    may also use simple inline formatting markup.  Any content can be
+    wrapped in a <tt class="sgmltag-element">span</tt> element with certain attributes
+    to control formatting.  The attributes are a subset of CSS properties.
+    For HTML output, they are converted directly into the corresponding
+    CSS.  The list of allowed attributes is as follows:</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-element">font-family</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute sets the font family.  Specifying
+        exact font is generally a not advisable.  Rather, this should be
+        used to provide a generic family: serif, sans-serif, cursive,
+        fantasy, or monospace.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-style</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute can be used to italicize the text.
+        The allowed values are italic, oblique, and normal.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-variant</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute can be used to set the text in small
+        caps.  Small caps prints lowercase letters with smaller versions of
+        the uppercase glyphs.  The allowed values are small-caps and normal.
+        </p></dd><dt><span class="term"><tt class="sgmltag-element">font-weight</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute can be used to mark the text bold.
+        CSS allows any number from 100 to 900, with normal text being 400
+        and bold being 700.  In addition to numerical values, you can use
+        one of bold, bolder, lighter, or normal to use pre-defined values.
+        Only bold and normal should generally be needed.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-stretch</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute can be used to stretch or condense
+        the font.  CSS allows a number of keywords to specify by exactly
+        how much to stretch the font.  In practice, only wider, narrower,
+        and normal should generally be used.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-size</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute sets the size of the font.  CSS
+        allows both absolute font sizes using keywords or numeric lenghts,
+        as well as relative font sizes using keywords or percentages.
+        Generally, only larger, smaller, and normal should be used for
+        this attribute.  Better, use the <tt class="sgmltag-element">big</tt> and
+        <tt class="sgmltag-element">small</tt> convenience elements described below.
+        They are defined to respect the size scales used throughout the
+        stylesheets.</p></dd><dt><span class="term"><tt class="sgmltag-element">text-decoration</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute can set various effects on the text.
+        The allowed values are none, underline, overline, line-through,
+        and blink.  Don't use blink.</p></dd></dl></div></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Additionally, extra inline elements are provided for convenience.
+    The formatting done by these elements could also be done using the
+    <tt class="sgmltag-element">span</tt> element.  Using these elements is just easier
+    for common formatting tasks.</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-element">big</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text larger.  This is preferred over using
+        the <tt class="sgmltag-element">font-size</tt> attribute, because it is defined to
+        use the size scale used throughout the stylesheets.</p></dd><dt><span class="term"><tt class="sgmltag-element">small</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text smaller.  This is preferred over using
+        the <tt class="sgmltag-element">font-size</tt> attribute, because it is defined to
+        use the size scale used throughout the stylesheets.</p></dd><dt><span class="term"><tt class="sgmltag-element">sub</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Render the text as a subscript.</p></dd><dt><span class="term"><tt class="sgmltag-element">sup</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Render the text as a superscript.</p></dd><dt><span class="term"><tt class="sgmltag-element">b</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text bold.  This is equivalent to setting
+        the <tt class="sgmltag-element">font-weight</tt> attribute to bold.</p></dd><dt><span class="term"><tt class="sgmltag-element">i</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text italic.  This is equivalent to setting
+        the <tt class="sgmltag-element">font-style</tt> attribute to italic.</p></dd><dt><span class="term"><tt class="sgmltag-element">tt</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text monospace.  This is equivalent to setting
+        the <tt class="sgmltag-element">font-family</tt> attribute to monospace.</p></dd><dt><span class="term"><tt class="sgmltag-element">u</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Underline the text.  This is equivalent to setting the
+        <tt class="sgmltag-element">text-decoration</tt> attribute to underline.</p></dd></dl></div></div></div><div class="section"><a name="translating-types"/><h2 class="section title"><span class="title"><span class="label">5. </span>Common Formatter Types</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">There are a number of common types of format strings that are
     marked for translation in the stylesheets.  DocBook contains a lot
     of structural markup, and many of the same sorts of formatting tasks
     have to be performed on different elements.  For example, chapters,