Re: [Docutils-users] like ".. important::"

[Beni C. <cb...@te...>]

On 2003-03-10, David Abrahams wrote:

> David Goodger <go...@py...> writes:
>
> > David Abrahams wrote:
> >> I'd like to add a callout box to my documents that's similar to what
> >> you get by writing
> >>
> >>    .. important::
> >>
> >> but instead of "important", it should say "definition".  Is that
> >> possible?
> >
> > You could adapt the "topic" or "sidebar" directives for this; the titles are
> > author-supplied.  The problem here is that topics and sidebars cannot appear
> > just anywhere; only where sections are possible.  I.E., you can't have one
> > between two paragraphs.
> >
> > A new admonition type could be added to the current set of 9 ("attention",
> > "caution", "danger", "error", "hint", "important", "note", "tip",
> > "warning").  "Definition" seems general-purpose enough to be added to the
> > Docutils document model.  Would this increase the document model's richness
> > (a good thing), or just its bloat?
> >
> > The alternative is to add a generic admonition that could be given any title
> > desired::
> >
> >     .. admonition:: Definition
> >
> >        Definition body here.
>
> That was exactly what I was thinking would be most appropriate.
>
> > Although this would add flexibility to the document model, I'm reluctant to
> > add it.  It may be too flexible.
>
> I'm worried about your worry about flexibility (I'm a meta-worrywart).
> I'm using Docutils to write a book (so far), and I am certain that if
> it doesn't sprout more of that sort of parametrization ability I'm
> going to outgrow ReST and have to drop the comfortable input syntax
> for something awful like TeX or more-likely, DocBook.
>
I'd like to second this.  I think that any document model must be
parametrizable to be useful.  When you can't add your own element
(sub)types, you are forced to use the same element for more than one
logical element and this bad exactly for the same reasons that using
physical styles is bad.

-- 
Beni Cherniavsky <cb...@tx...>,
happy that cdrecord works in his linux - one less reason to reboot...