docutils-develop

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[jfbu <jf...@us...>]

---

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

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Wed Jul 27, 2022 09:53 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

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.
A possible German translation may be "Warnhinweis" but the overlap of the semantics of the specific admonitions makes translation very tricky.)


---

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

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Wed Jul 27, 2022 09:53 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[jfbu <jf...@us...>]

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

~~~diff
-.. 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.



---

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

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Thu Jul 28, 2022 11:09 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

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.


---

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

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Thu Jul 28, 2022 12:20 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] Re: #453 [DOC] generic "admonition" directive also listed as specific

[jfbu <jf...@us...>]

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




---

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

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Thu Jul 28, 2022 05:08 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] Re: #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

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`).


---

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

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Sat Jul 30, 2022 07:09 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed



---

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

**Status:** open-fixed
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Sat Jul 30, 2022 07:09 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

- **status**: open-fixed --> closed-fixed
- **Comment**:

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



---

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

**Status:** closed-fixed
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Wed Sep 07, 2022 11:12 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) 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).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.