#453 [DOC] generic "admonition" directive also listed as specific

[jfbu]

I quite probably miss something obvious but admonition directives documentation is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).

[Günter Milde]

Thank you for reporting. You found a documentation bug.
Could you check, if the changes in [r9112] help to avoid the confusion?

Docutils uses the term "admonition" in the sense of "safety message" or "hazard statement", not as reprimand or rebuke. (The German translation in parsers/rst/languages/de.py got this wrong.
The overlap of the semantics of the specific admonitions makes translation very tricky,
a possible German translation may be "Warnhinweis".)

[jfbu]

Could you check, if the changes in [r9112] help to avoid the confusion?

Yes, looks good to me (with nits ;-). I checked this as a diff from a git checkout of commit 3c8063b4b59 with its parent and noticed some inserted whitespace:

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 14410a4ea..ab1342a1e 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -424,6 +424,9 @@ Details
 :Analogues:
     ``admonition`` has no direct analogues in common DTDs.  It can be
     emulated with primitives and type effects.
+    
+    The specific admonitions caution_, note_, tip_, and warning_ 
+    are analogous to the respective DocBook elements.

This does not show above but whitespace is at start of "empty" line underneath type effects. and there is space character after warning_.

About this other hunk:

-.. From Webster's Revised Unabridged Dictionary (1913) [web1913]:
-   Admonition
-      Gentle or friendly reproof; counseling against a fault or
-      error; expression of authoritative advice; friendly caution
-      or warning.
+Admonitions ("safety messages" or "hazard statements") can appear anywhere
+an ordinary body element can.  They contain arbitrary body elements.
+Typically, an admonition is rendered as an offset block in a document,
+sometimes outlined or shaded,

-      Syn: {Admonition}, {Reprehension}, {Reproof}.
+Docutils defines a `generic admonition`_ as well as a set of
+`specific admonitions`_.

shouldn't the comma after shaded be a full stop rather?
About

The overlap of the semantics of the specific admonitions makes translation very tricky,
a possible German translation may be "Warnhinweis".

I noticed that French has similar conundrum. Currently "admonition" is translated as... admonition but this is a litterary word that relatively little of our contemporaries under 50 years of age will understand. A more common French word (still at a level of demanding language) is admonestation but it then acquires a meaning like réprimande which is too strong. I could not find immediately a good translation but will try to program my brain to think about it during next night shift.

Reference: http://stella.atilf.fr/Dendien/scripts/tlfiv5/advanced.exe?8;s=1136435550; but I don't know if this direct link works. Else go to http://atilf.atilf.fr/tlf.htm, click the prominent button and enter admonition in the search form.

[Günter Milde]

Thanks for the "nitpicking" - fixed in [r9115].

About translating "admonition": We look for an umbrella term for the specific admonitions
(attention, caution , danger, error, hint, important, note, tip, warning) and similar block elements.

Unfortunately, the English term "admonition" has also the meaning "reproof" (fr: exhortation, de: Ermahnung). Usage in rST does certainly not "relate to moral delinquencies" with the object to "prevent further transgression".
A number of translations got this wrong.
Swedish, Russian, and Ukrainean use a term that translates also to "remark", which is a better match for our use case. Other matches would be translations to "advise", "advisory", "warning note" or similar.

[jfbu]

About translating "admonition": We look for an umbrella term for the specific admonitions
(attention, caution , danger, error, hint, important, note, tip, warning) and similar block elements.

quick (French) thoughts:

• annonce: it is very different from admonition but conveys the idea of an announcement, which in practice is what the Docutils admonitions do.
• encart: this is from press media, it designates in particular advertisements ("encart publicitaire")
• panneau: here I take inspiration from being a member of one of the last generations allowed to drive by ourselves mobile engines; this designates indications on side of roads "panneau de signalisation", "panneau routier". And inside such a "panneau" there can be "encarts" for example the name of a major city might be printed on top of a rectangular area in Green.
• cartouche: for example hieroglyphs may be written in such a cartouche; but the word also designates other things such as ammunition, see https://fr.wikipedia.org/wiki/Cartouche. I feel it is not too bad in fact although often in typography a cartouche contains not a general message but identifiers for example on subjects of a written examination at universities.

all for now.

[Günter Milde]

Thank you for the suggestions.

Looking at the examples in
https://docutils.sourceforge.io/docs/user/rst/demo.html#admonitions, I
found additionally remarque ("Anmerkung")
and avis ("avis au lecteur", "Ratschlag").

Unfortunately, conseil is already used for the specific admonition
hint (maybe this should have been indication).

encart and cartouche may be too ambiguous in the context of
documentation documents (we already use encadré for sidebar).

[Günter Milde]

The documentation is solved in Docutils 0.20.
The mistranslated localisations of the directive name "admonition" will be fixed over the next releases.