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/