docutils-users

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

[David A. <da...@bo...>]

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?

TIA,
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

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

[David G. <go...@py...>]

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.

Although this would add flexibility to the document model, I'm reluctant to
add it.  It may be too flexible.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

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

[David A. <da...@bo...>]

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.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

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

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

[Martin B. <bl...@ir...>]

On Tuesday 11 March 2003 03:25, David Abrahams wrote:
> David Goodger <go...@py...> writes:
> > David Abrahams wrote:
> > Although this would add flexibility to the document model, I'm reluct=
ant
> > 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.

it seems to me that the mere concept of docutils has an implicit=20
contradiction:  on the one hand, it tries to extract structure from input=
=20
without using markup, and on the other hand, ... well, markup is provided=
 for=20
more advanced structures.

IMHO careful judgement about how and what features to add to it will be=20
tantamount to its success--i.e. if tons of non-generic features creep int=
o it=20
i'd rather use something that is made for the specific task i'm writing f=
or. =20
in other words, if it strays away too much from simple text without marku=
p, i=20
think people will not be interested in learning another ML.

that's just my opinion, but i think at some point it will be required to =
set=20
and just accept limitations on what it can and cannot do.  for example,=20
sometimes i find myself needing some special feature which is not provide=
d,=20
well, tough luck, my document still conveys all the information i want it=
 to,=20
without a little bit of extra pizazz, and i accept it, otherwise i'll use=
=20
something else.  i don't think reST should be made to replace every other=
=20
format that's out there.  if it answer 90% of the basic needs of everyone=
,=20
it's already doing a damn good job.

personally i'm worried more about the adding of new features rather than =
the=20
reluctancy...

just my 2c.
cheers,

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

[David G. <go...@py...>]

Martin Blais wrote:
 > it seems to me that the mere concept of docutils has an implicit
 > contradiction: on the one hand, it tries to extract structure from
 > input without using markup, and on the other hand, ... well, markup
 > is provided for more advanced structures.

True: implicit markup versus explicit markup.

 > IMHO careful judgement about how and what features to add to it will
 > be tantamount to its success--

Time will tell.  All I can go by is advice, experience, careful
thought, and gut-feeling instinct.

 > that's just my opinion, but i think at some point it will be
 > required to set and just accept limitations on what it can and
 > cannot do.

Agreed.  But limitations change over time.  Gotta change with the
times; grow or die.

 > personally i'm worried more about the adding of new features rather
 > than the reluctancy...

I hear you. I think that any language-like project -- be it a
programming language, markup language, whatever -- gets to the point
where it nears completion and it becomes harder to add new features.
The reluctance I feel is a useful check on creeping featurism.  That's
healthy, but on the other hand, the project may never really be
finished.  With directives the threshold for acceptance is relatively
low, since they add richness without adding syntax or intrinsic
complexity.  They're like a new library module in Python: if it serves
a useful and general-purpose function, it ought to be included.

So don't worry.  Nothing gets in without plenty of careful
consideration.  Part of that is the advice given on these lists;
please keep it coming.

It's useful for myself and all concerned to re-read the
reStructuredText goals once in a while:
<http://docutils.sf.net/spec/rst/introduction.html#goals>.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

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

[Brett g P. <bgp...@ac...>]

David Abrahams wrote:
> David Goodger <go...@py...> writes:
> I'm worried about your worry about flexibility (I'm a meta-worrywar=
t).
> 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.
>=20

FWIW, I'm with David Abrahams -- I'm starting to use rST as my domina=
nt=20
writing tool. Right now I'm working on the documentation for a large =
SDK=20
that we're writing, and also gearing up to rewrite our programming st=
yle=20
guide. I'm starting to bump up against minor annoyances.

I don't know what the right answer is.

Here's an example of what I would love to be able to do for the style=
=20
guide, for instance:

I need to be able to include language-specific example code, and I wo=
uld=20
love to have a richer style-specification model, so I could create a=
=20
stylesheet entry that displays C++ examples against a light blue=20
background, Java against a different color (black text on a black bg=
=20
would be my personal choice there) , etc, etc, etc.
--
//  Today's Oblique Strategy (=A9 Brian Eno/Peter Schmidt):
//  Don't be afraid of things because they're easy to do
//  Brett g Porter * BgP...@ac...

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

[<po...@or...>]

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.

I'm not sure what this means. I've placed sidebars between two
paragraphs with no problem. What am I misunderstanding?

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

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

[David G. <go...@py...>]

[David Goodger]
>> 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.

[Patrick K. O'Brien]
> I'm not sure what this means. I've placed sidebars between two
> paragraphs with no problem. What am I misunderstanding?

Sorry, my mistake.  It should have been: topics and sidebars can only appear
at the top level of sections, not within other body elements.  For example,
you can't have a topic or sidebar inside a list or table.  Admonitions *can*
occur within lists & tables etc.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv