docutils-develop

RE: [Docutils-develop] [PATCH] slovak support file (sk.py)

[Vasko M. <va...@di...>]

hi,

> Unicode escapes for the accented characters here.  See the sv.py
> Swedish-language module for an example, and
> http://docutils.sf.net/spec/howto/i18n.html (newly revised) for a
> rationale.

ok, I'll look at the doc today, thank you

> Question for you (and anyone else using Docutils with other
> languages): what about reStructuredText directive names?  Should they
> be translated into Slovak (etc.)?  Do you want to use::
>     .. contents::
> or::
>     .. obsah::
> ?  And should directive options be translated as well?

no, absolutely not. directives names and options should be in english, =
for sure
if it'll be translated, it will be total mess

thanks,
miro

RE: [Docutils-develop] [PATCH] slovak support file (sk.py)

[Vasko M. <va...@di...>]

hi,

one more thing

> I notice that the "bibliographic_fields" dict is not translated.  I
> can do this easily though, since all the terms are already in
> "labels".

I do not want to translate these fields, because I think, they have to =
be
in english for convenience and consistency between multiple languages

I think, that all these "system" fields have to be in english, *maybe*
with translation, but not only translated to local language

thank you,
miro

Re: [Docutils-develop] [PATCH] slovak support file (sk.py)

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

[David]
>> I notice that the "bibliographic_fields" dict is not translated.  I
>> can do this easily though, since all the terms are already in
>> "labels".

[Vasko]
> I do not want to translate these fields, because I think, they have
> to be in english for convenience and consistency between multiple
> languages

I do not agree with this at all.  The "bibliographic fields" feature,
if used (it's not required), is language-dependent.  For a French
document's author to have to write ":Author:" instead of ":Auteur:"
would be awkward, obtrusive, and probably quite galling.  Presumably
the rendered output of the bibliographic field list would say
"Auteur:", so why shouldn't the input also?

> I think, that all these "system" fields have to be in english,
> *maybe* with translation, but not only translated to local language

I don't understand.  Explain please?

-- 
David Goodger  <go...@py...>  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/

[Docutils-develop] language for directives etc.

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

[David]
>> Question for you (and anyone else using Docutils with other
>> languages): what about reStructuredText directive names?  Should
>> they be translated into Slovak (etc.)?  Do you want to use::
>>
>>     .. contents::
>>
>> or::
>>
>>     .. obsah::
>>
>> ?  And should directive options be translated as well?

[Vasko]
> no, absolutely not. directives names and options should be in
> english, for sure if it'll be translated, it will be total mess

[Adam]
> I think it makes sense to translate directive names, and therefore
> also the options. It simply flows naturally with the text. That's
> the way it works right now (except the option names), and I like
> it. :)

[Engelbert]
> reST is no programming language,

Here we see both sides of the argument.  I can understand both points
of view.  For people working in multiple languages, translated
directives and bibliographic fields could be a burden.  But for people
working exclusively in one (non-English) language, it would be
unreasonable to force them to use English.

[Adam]
> It is also the only way people that do not know english will be able
> to use docutils (like for example on a Zope site).

Agreed.  Docutils is meant to be a tool for everyone, not just
programmers who understand the concept of "little language".  It may
now be limited to hackers & techies, but that's just because it hasn't
matured enough.

However, all the documentation is in English, so how would people know
about translated directive names etc.?

I think all aspects of the document should be in the language of the
document, including directives (both names & options) and
bibliographic field names.  To allow for "under development" use,
English can be used as a fallback for directive names, but not
bibliographic field lists.  For those who would prefer to use English
directive names, a command-line option could be added.

-- 
David Goodger  <go...@py...>  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] language for directives etc.

[<eng...@ss...>]

On Wed, 6 Nov 2002, David Goodger wrote:

<SNIP>
>
> [Vasko]
> > no, absolutely not. directives names and options should be in
> > english, for sure if it'll be translated, it will be total mess
>
> [Adam]
> > I think it makes sense to translate directive names, and therefore
> > also the options. It simply flows naturally with the text. That's
> > the way it works right now (except the option names), and I like
> > it. :)
>
> [Engelbert]
> > reST is no programming language,

i was wrong. it is a programming language :-)
BUT: see low end.

> Here we see both sides of the argument.  I can understand both points
> of view.  For people working in multiple languages, translated
> directives and bibliographic fields could be a burden.  But for people
> working exclusively in one (non-English) language, it would be
> unreasonable to force them to use English.
>
> [Adam]
> > It is also the only way people that do not know english will be able
> > to use docutils (like for example on a Zope site).
>
> Agreed.  Docutils is meant to be a tool for everyone, not just
> programmers who understand the concept of "little language".  It may
> now be limited to hackers & techies, but that's just because it hasn't
> matured enough.

.. note:: matureing means we end where latex is.

.. note:: my first usage of a directive :-)

> However, all the documentation is in English, so how would people know
> about translated directive names etc.?

this is a bug in the documentation not in the concept.
a translation table could be generated from the source modules.
and if directives translation are code e.g.::

  'wichtig': 'important',  # Den Eintrag als wichtig markieren.

we could also include the short description. looks silly and
is not always necessary as directives should be descriptive.

better yet::

  'wichtig': 'important',  # _directives_important

which would link to the language dependend directive documentation.

> I think all aspects of the document should be in the language of the
> document, including directives (both names & options) and
> bibliographic field names.  To allow for "under development" use,
> English can be used as a fallback for directive names, but not
> bibliographic field lists.  For those who would prefer to use English
> directive names, a command-line option could be added.

can we have the fallback AND the document_language, means
in german i want to use *raw* or *unbearbeitet*.

Translation of directives
=========================

:author: gr...@us...
:date: 2002-11-07

Should directives be translated or not ?

*Yes* because it should be useable for authors in other languages.
Not only for people understanding english.

But ...
-------

as a reST document should be consumable for the reader not only the writer
and the processor we have to consider both audiences: *author* and *reader*

Considering this, directoves must be translated.

But again ...
-------------

We have a third audience, although a silent one, the processing system.

``include`` is not real a document content, but a processing directive,
if this is for the *reader* it should read ``see file``.

Arguments
---------

vasko

  no, absolutely not. directives names and options should be in english, for
sure
  if it'll be translated, it will be total mess.

right when considering processing commands: include in english is not a word
it is a verb and a noun. Know should i translate *include*-theverb or
*include*-thenoun.

Solution
--------

I am for quick starts. The fastest solution is *make it a policy*.

  There are directives to the reader, usually nouns e.g. *danger*, *hint*, ...
  and directives to the processing system, commands.

Directives to the reader must be language dependend.

* Directives must be descriptive to all audience.



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

Re: [Docutils-develop] language for directives etc.

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

[David]
>> Docutils is meant to be a tool for everyone, not just programmers
>> who understand the concept of "little language".  It may now be
>> limited to hackers & techies, but that's just because it hasn't
>> matured enough.

[Engelbert]
> .. note:: matureing means we end where latex is.

I *think* I disagree, but I'm not quite sure what you are saying so
I'll reserve judgement. ;)

>> However, all the documentation is in English, so how would people
>> know about translated directive names etc.?
> 
> this is a bug in the documentation not in the concept.
> a translation table could be generated from the source modules.

Good idea.  Added to the to-do list.

> can we have the fallback AND the document_language, means
> in german i want to use *raw* or *unbearbeitet*.

Yes, I suppose.  Currently a warning (level-2 system message) is
generated in this case.  That could be downgraded to info/level-1,
which is normally suppressed.  Unless the "--strict-language" option
was set, in which case the warning would be upgraded to an
error/level-3.

> We have a third audience, although a silent one, the processing
> system.

To the processing system, they're just identifiers.  As long as
they're unique, it doesn't care what the base language is.

> ``include`` is not real a document content, but a processing
> directive, if this is for the *reader* it should read ``see file``.

Perhaps "insert" would be a better directive name?

But I take your point.  Some directives, like "note" and "image", are
names (nouns) of constructs without native syntax, and mean "this is a
[note]" or "put an [image] here".  Others, like "include" or
"section-autonumbering" (a.k.a. "sectnum"), are more like commands,
saying "[include] that file here" or "number my sections
automatically".

>  include in english is not a word it is a verb and a noun.

"Include" is a verb.  The only time I've heard it used as a noun is by
programmers, referring to C's "#include" directive as "an include".
This is non-standard usage.  The noun form is "inclusion".

> I am for quick starts. The fastest solution is *make it a policy*.

OK.  Policy: all directives shall be translated.  English names may
also be used, but native names take precedence in case of a conflict.

-- 
David Goodger  <go...@py...>  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/