docutils-develop

[Docutils-develop] internationalization

[<gr...@us...>]

Docutils can be adapted to languages in two sections:

1. directives: This gives a mapping from directives as in the document
   to standard names used inside docutils.

   see ``docutils/parsers/rst/languages``

2. labels, bibliographic fields and author_separators:

   e.g.::

      s = languages.get_language("sv").labels["date"]
      # s is now swedish for date

   see ``docutils/languages``

Attention:

  For usage of languages also the directinves module has to be present.

Question:

  casesensitivity on directives and or field namings ?
  Should languages.labels become a function which tries, exact case
  all lower and if both fails returns the passed text ?


-- 
 BINGO: work smarter
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] internationalization

[David G. <go...@us...>]

Engelbert Gruber wrote:
> Docutils can be adapted to languages in two sections:

So far, yes.

> casesensitivity on directives and or field namings ?

No.  Directive names and field names are converted to the canonical
key form -- lowercase -- before lookup.  The original case doesn't
matter.

> Should languages.labels become a function which tries, exact case
> all lower and if both fails returns the passed text ?

No.  This is another case of "errors should never pass silently".  If
the label is missing from the language module, it's a bug.  If the
``labels`` dict of a language module is being accessed, it's either
because the "official" text for a bibliographic field is needed (in
which case the ``bibliographic_fields`` dict must have already been
accessed), or because some boilerplace text (such as "!DANGER!")  is
needed.  In either case, a missing entry means the dict is not up to
date, or there's some other bug in the code.  Such a bug should
definitely cause a traceback.

We currently have English and Swedish directives [*]_
(docutils/parsers/rst/languages/) and English, Swedish, and German
labels (docutils/languages/).  Only the English labels module is up to
date.  Patches/updates welcome!

.. [*] I notice you've just added a German de.py as well.  Great,
   thanks!  Unfortunately, even the en.py file it was based on isn't
   up to date. :-(  I'll fix it, probably tomorrow.  I think even
   this is an example of a "silently passing" exception.  I'll add
   some warnings.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] internationalization

[<gr...@us...>]

On Tue, 15 Oct 2002, David Goodger wrote:

> > casesensitivity on directives and or field namings ?
>
> No.  Directive names and field names are converted to the canonical
> key form -- lowercase -- before lookup.  The original case doesn't
> matter.

i recognized, that there is some forth and back, ok.


> > Should languages.labels become a function which tries, exact case
> > all lower and if both fails returns the passed text ?
>
> No.  This is another case of "errors should never pass silently".  If
> the label is missing from the language module, it's a bug.  If the
> ``labels`` dict of a language module is being accessed, it's either
> because the "official" text for a bibliographic field is needed (in
> which case the ``bibliographic_fields`` dict must have already been
> accessed), or because some boilerplace text (such as "!DANGER!")  is
> needed.  In either case, a missing entry means the dict is not up to
> date, or there's some other bug in the code.  Such a bug should
> definitely cause a traceback.

ok. i thought about the function, because i check with has_key
to avoid the traceback.

but maybe a function label() which does not only give a traceback but
a real error with description.


> We currently have English and Swedish directives [*]_
> (docutils/parsers/rst/languages/) and English, Swedish, and German
> labels (docutils/languages/).  Only the English labels module is up to
> date.  Patches/updates welcome!
>
> .. [*] I notice you've just added a German de.py as well.  Great,
>    thanks!  Unfortunately, even the en.py file it was based on isn't
>    up to date. :-(  I'll fix it, probably tomorrow.  I think even
>    this is an example of a "silently passing" exception.  I'll add
>    some warnings.

I had to because i could not use labels in writer without,
guess "-l de" tries to switch the rst part to, so therefore it is needed,
otherwise one gets the traceback (hate it).

could you make sense of the documentation part ?

-- 
 BINGO: Hoeren Sie auf zu mosern!
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] internationalization

[David G. <go...@us...>]

[Engelbert]
>>> Should languages.labels become a function which tries, exact case
>>> all lower and if both fails returns the passed text ?

[David]
>> No.  This is another case of "errors should never pass silently".
>> If the label is missing from the language module, it's a bug.

[Engelbert]
> but maybe a function label() which does not only give a traceback
> but a real error with description.

No!  The "real error" here is that some data is missing from the
mapping, or that the wrong key is being accessed.  A traceback is
*absolutely* appropriate.  If a traceback occurs, it means there's a
bug in the *code* that needs to be fixed.  Docutils Reporter
warnings/errors indicate problems in the *input*.  They're completely
different (and incompatible) things.

>> .. [*] I notice you've just added a German de.py as well.  Great,
>>    thanks!  Unfortunately, even the en.py file it was based on
>>    isn't up to date. :-(  I'll fix it, probably tomorrow.  I think
>>    even this is an example of a "silently passing" exception.  I'll
>>    add some warnings.

This is done now.

> I had to because i could not use labels in writer without, guess "-l
> de" tries to switch the rst part to, so therefore it is needed,
> otherwise one gets the traceback (hate it).

If you hate tracebacks so much, please help get rid of them.  Please
help fix the cause (at least submit a bug report), instead of fixing
the symptom.  What you describe above is a symptom-fix only.  In this
case, fixing the cause is much easier!

> could you make sense of the documentation part ?

OK.  See http://docutils.sf.net/spec/howto/i18n.html .

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] internationalization

[<gr...@us...>]

On Wed, 16 Oct 2002, David Goodger wrote:

> [Engelbert]
> >>> Should languages.labels become a function which tries, exact case
> >>> all lower and if both fails returns the passed text ?
>
> [David]
> >> No.  This is another case of "errors should never pass silently".
> >> If the label is missing from the language module, it's a bug.
>
> [Engelbert]
> > but maybe a function label() which does not only give a traceback
> > but a real error with description.
>
> No!  The "real error" here is that some data is missing from the
> mapping, or that the wrong key is being accessed.  A traceback is
> *absolutely* appropriate.  If a traceback occurs, it means there's a
> bug in the *code* that needs to be fixed.  Docutils Reporter
> warnings/errors indicate problems in the *input*.  They're completely
> different (and incompatible) things.

ok, This means, the specification says access language.labels directly
without checking for existance of the element.

i still think this should be put into code not documentation.

def label(self,internal_name):
	return self.labels[internal_name)

gives consistant behaviour over all accesses, because i would not
have read this specification, and definately checked for existance.

>
> >> .. [*] I notice you've just added a German de.py as well.  Great,
> >>    thanks!  Unfortunately, even the en.py file it was based on
> >>    isn't up to date. :-(  I'll fix it, probably tomorrow.  I think
> >>    even this is an example of a "silently passing" exception.  I'll
> >>    add some warnings.
>
> This is done now.

i see into de.

-- 
 BINGO: professionally create virtual services
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] internationalization

[David G. <go...@us...>]

gr...@us... wrote:
> ok, This means, the specification says access language.labels
> directly without checking for existance of the element.

The specification doesn't (or didn't, until spec/howto/i18n.txt) say
anything about this.  The code does.  It's just an implementation
detail.

> i still think this should be put into code not documentation.
> 
> def label(self,internal_name):
>     return self.labels[internal_name)

I don't see the difference.  It looks like unnecessary indirection to
me.

> gives consistant behaviour over all accesses, because i would not
> have read this specification, and definately checked for existance.

I disagree.  Let's move on.

From this and previous discussions, it's obvious to me that we have
different philosopies of programming, or we're misunderstanding each
other.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/