Date: Sat, 11 Sep 1999 11:18:02 +0100 From: Nik Clayton <nik@freebsd.org> To: John Baldwin <jobaldwi@vt.edu> Cc: doc@freebsd.org, "Jordan K. Hubbard" <jkh@zippy.cdrom.com> Subject: Re: build failure in russian books. Message-ID: <19990911111802.A59351@catkin.nothing-going-on.org> In-Reply-To: <0FHV00EQAW5T1N@gkar.cc.vt.edu>; from John Baldwin on Sat, Sep 11, 1999 at 03:15:35AM -0400 References: <0FHV00E97VAK1K@gkar.cc.vt.edu> <0FHV00EQAW5T1N@gkar.cc.vt.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
ATTENTION: Translation teams. What follows is probably a fairly good
explanation of how you extend the stylesheets to add additional support
for your language. I hope it's useful.
On Sat, Sep 11, 1999 at 03:15:35AM -0400, John Baldwin wrote:
> I committed another fix in revision 1.5 that was breaking the build.
> A </para> tag after the end of an </itemizedlist> was missing. The
> missing tag was present in the English version. The Russian FAQ now
> builds ok, but it spits out a lot of errors (warnings?) about not
> recognizing the <question> and <answer> tags. Ring any bells, Nik or
> anyone else?
Yeah.
It's all to do with the way the stylesheets handle l10n and i18n (and
if anyone can explain the precise difference between those two terms,
I'd be obliged (anyone that says "Uh, three letters" will be shot)).
Norm's DocBook stylesheets are incredibly configurable. I mean really,
outstandingly, hideously configurable. All the 'boiler plate' text
that they spit out (for example, prefixing questions with "Q:" is
changeable.
The snag with this is that if the stylesheets don't support a language
out of the box, or only support a subset of DocBook out of the box, then
you're going to have to deal with it yourself.
For example, the Russian, Spanish, and (soon to be imported) French FAQs
all print something like
/usr/local/bin/jade:/local/1/home.nik/FreeBSD-CVS/doc/es_ES.ISO_8859-1/books/faq/book.sgml:7835:0:E: Nombre de elemento no esperado: QUESTION
when you try and build them.
This is because the stylesheets have encountered the <Question> element,
and aren't exactly sure how to deal with it. Of course, the error message
will be in the appropriate language.
For these examples, assume
$ROOT = /usr/local/share/sgml/docbook/dsssl/modular
Take a look in $ROOT/html, and look at the dbl1??.dsl files. These are
the DSSSL code for the different language support. '??' is the language
code. Note that Norm's sheets have the problem we just fixed -- for
some languages a two letter language code isn't sufficient, you need to
know the encoding as well.
Look at $ROOT/html/dbl1en.dsl.
A couple of things are of interest in this file.
First, right at the top it pulls in ../common/dbl1en.ent, which are entities
for English text common to the HTML and Print stylesheets. This is a big
clue that that file should be looked at too. Also, it pulls in
../common/dbl1en.dsl, which is DSSSL code that the HTML and Print
stylesheets share.
Still in $ROOT/html/dbl1en.dsl, you see it just defines some DSSSL variables
and assigns them some literal text. If you ever wanted to override these
definitions you can just copy the code out of this .dsl file, and put it
in freebsd.dsl (in the doc/share/sgml), and then change it as necessary.
[ I should stress at this point that that's *exactly* how freebsd.dsl was
created. I know very little DSSSL, and Scheme gives me a headache --
I just cut-n-paste until it works :-) ]
$ROOT/html/dbl1en.dsl is quite small, so it's worth looking at the .ent
and .dsl file in $ROOT/common, and seeing what they do.
$ROOT/common/dbl1en.dsl is a little more involved, but it is understandable
if you take it in chunks.
Scroll down until you see lines that look like
(define en-abstract-name "&Abstract;")
(define en-answer-name "&Answer;")
(define en-appendix-name "&Appendix;")
...
This is assigning the value of some entities (which are defined in
$ROOT/common/dbl1en.ent) to some variables.
If you search for the string "question" in this file, you see it's used
in a couple of places.
1. In the function gentext-en-element-name.
As far as I can tell, this takes an element name and converts it to
its local language equivalent. Hence lines like
((equal? name (normalize "question")) en-question-name)
which use the en-question-name variable defined elsewhere.
2. In the code
(define en-question-label-title-sep " ")
This is the separator string between a question's label ("Q:", say)
and the title of that question.
This is then used (in the same way as in (1) above) in the function
gentext-en-label-title-sep.
OK. So now take a look at dbl1en.ent. You'll see a Question entity defined
to "Q:" (you'll also see similar things for the Answer entity as well).
OK, so that's the English stylesheets. What about (for example) the
Spanish?.
Well, a "grep -i question $ROOT/html/dbl1es.dsl" doesn't show anything,
and the same goes for $ROOT/common/dbl1es.dsl and $ROOT/common/dbl1es.ent.
From this we can conclude that (at least in v1.44 of the stylesheets,
which is what I'm using) that there's no support for FAQs in the Spanish
stylesheets.
To add in this support, you need to edit two files, $ROOT/common/dbl1es.ent
and $ROOT/common/dbl1es.dsl.
To $ROOT/common/dbl1es.ent you can probably just add the two lines
<!ENTITY Answer "A:">
<!ENTITY Question "Q:">
and be done with it (unless Q/A is represented differently in Spanish).
$ROOT/common/dbl1es.dsl is a little more involved. You will need at least
(define es-answer-name "&Answer")
(define es-question-name "&Question")
(define es-answer-label-title-sep " ")
(define es-question-label-title-sep " ")
and edit the gentext-es-element-name and gentext-es-label-title-sep
functions to use these new variables.
When you've done that, send patches to Norm Walsh, so that he can add them
to the next release of the stylesheets, and send a copy of them to myself
or Jun Kuriyama -- Jun maintains the textproc/dsssl-docbook-modular port
and we should add them there until they're obsoleted after Norm pulls them
in to the base distribution.
Make sense?
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990911111802.A59351>