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