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 ----+