generic admonition versus specific admonitions

generic admonition versus specific admonitions

[Robert P. J. Day]

  as i'm sure you're all aware, reST supports a number of specific
admonition types (note, info, error, caution, ...), plus a generic
form that is used thusly:

.. admonition::

   blah blah

i was interested to see that the use of the generic admonition is
confined exclusively to a single .rst file in the profiling manual:

$ grep -r "\.\. admonition" *
profile-manual-arch.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
profile-manual-usage.rst:.. admonition:: Tying it Together
$

a few seconds research showed that, while it seems overly bland to use
a generic admonition, it has one cool advantage.

  if you use, say ".. note::", then the rendered note always has the
caption "Note" by default -- if you add a caption on that same line,
that caption becomes the first line *inside* the note box, while the
box caption continues to say simply, "Note".

  with a generic admonition, however, if you add a caption like, say,
in that profile file:

.. admonition:: Tying it Together

then that caption becomes the top-level caption of the admonition box,
which adds some emphasis to the caption.

  should there be an aesthetic standard?

rday

Re: [docs] generic admonition versus specific admonitions

[Nicolas Dechesne]

On Sat, Oct 31, 2020 at 4:14 PM Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
>
>   as i'm sure you're all aware, reST supports a number of specific
> admonition types (note, info, error, caution, ...), plus a generic
> form that is used thusly:
>
> .. admonition::
>
>    blah blah
>
> i was interested to see that the use of the generic admonition is
> confined exclusively to a single .rst file in the profiling manual:
>
> $ grep -r "\.\. admonition" *
> profile-manual-arch.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> profile-manual-usage.rst:.. admonition:: Tying it Together
> $
>
> a few seconds research showed that, while it seems overly bland to use
> a generic admonition, it has one cool advantage.
>
>   if you use, say ".. note::", then the rendered note always has the
> caption "Note" by default -- if you add a caption on that same line,
> that caption becomes the first line *inside* the note box, while the
> box caption continues to say simply, "Note".
>
>   with a generic admonition, however, if you add a caption like, say,
> in that profile file:
>
> .. admonition:: Tying it Together
>
> then that caption becomes the top-level caption of the admonition box,
> which adds some emphasis to the caption.

I added the 'tying it together' admonition, since none of the generic
ones were relevant. Otherwise we use the existing "note" or "tip" in
other places, in which case their caption is "Note" or "Tip".

>
>   should there be an aesthetic standard?

I am not sure what you are asking here. Can you please clarify?

>
> rday
>
> 
>

Re: [docs] generic admonition versus specific admonitions

[Robert P. J. Day]

On Sun, 1 Nov 2020, Nicolas Dechesne wrote:

> I added the 'tying it together' admonition, since none of the
> generic ones were relevant. Otherwise we use the existing "note" or
> "tip" in other places, in which case their caption is "Note" or
> "Tip".

  ok, that's all i wanted to know.

rday