docutils-users — General discussions, questions, help requests.

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

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

[Docutils-users] Re: Another Problem with latex writer

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

David Goodger <go...@py...> writes:

>> Maybe ReST->DocBook->PDF is a better bet.
>
> Give the code in sandbox/oliverr/docbook a try.  Once it's in good shape
> (that may already be true, I don't know), it can be added to the core.

We've done some things successfully with it.  It seems to choke on
section numbering, as evidenced by this fragment:

--
--------------------------------
 A Deeper Look at Metafunctions
--------------------------------

.. section-numbering::

In this chapter we're going to take a closer look at the structure of
metafunctions, and as promised we'll begin to formalize what we mean
by "metafunction" a bit.

The Form of Metafunctions
=========================
--

...
  File "c:\src\docutils\docutils\docutils\nodes.py", line 1246, in unknown_visit
    raise NotImplementedError('visiting unknown node type: %s'
NotImplementedError: visiting unknown node type: generated

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

Re: FW: [Docutils-users] Another Problem with latex writer

[<eng...@ss...>]

> David Abrahams <da...@bo...> writes:
>
>
> The literal text fragment below:
>
>     In keeping with our quest for polymorphism, ``lambda`` is also a unary
>     metafunction returning a metafunction class.  In other words, we could
>     have written
>
>     .. parsed-literal::
>
>        template <class X>
>        struct times4
>            : twice<**typename mpl::lambda<mpl::plus<_1,_1> >::type**, X>
>        {};
>
> Comes out as:
>
> Which in turn is displayed as:
>
>     In keeping with our quest for polymorphism, lambda is also a unary
> metafunction returning a metafunction
>     class. In other words, we could have written
>     template <class X>
>     struct times4
>     : twice<\textbf{typename mpl::lambda<mpl::plus<_1,_1> >::type}, X>
>     {};
>
> Note the appearance of TeX directives in the output.

because its inside verbatim, julien used obeyspace asf. but this never worked
for me. i modified it using an mbox with ttfamily, but tt seams to have no
bold style.

in CVS.

> I'm beginning to wonder about using this toolchain to get from
> ReST->PDF.  Maybe ReST->DocBook->PDF is a better bet.

sure if you have docbook installed, why not.

i am thinking about not removing the stryle.tex but moving as much as possible
into it, so it will function like the css.


-- 
 BINGO: competently fashion progressive skills
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-users] Re: Problem (?) with inline literals

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

David Goodger <go...@py...> writes:

> What do you mean by "breaking non-space"?  Do you mean "zero-width space",
> \u200B?

No, I mean, "acts like whitespace as far as docutils parsing is
concerned, but isn't whitespace in the output"

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

Re: [Docutils-users] Re: Problem (?) with inline literals

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

David Abrahams wrote:
> Did we discuss the idea that escaped whitespace disappears?
> 
>     F(``a``\ `1`:sub:, ``a``\ `2`:sub:, ... ``a``\ `N`:sub:)

No, I don't think we have.  It's a definite possibility.  There are many
different ways to approach the problem.  This one seems to be the most
elegant so far.

Writing the roles first makes it read better::

    F(``a``\ :sub:`1`, ``a``\ :sub:`2`, ... ``a``\ :sub:`N`)

> It's unfortunate that you really want '\ ' for a  ,

I believe some people have expressed a desire for a non-breaking space in
the past.  If it was "really wanted", it would already be there. ;-)  We're
just talking now; no decisions yet.

With Unicode and encodings available (UTF-8, Latin-1, etc.), we can directly
code   as \u00A0 or \xA0.  Same with soft hyphens (­: \u00AD or
\xAD), and any other Unicode character.  This lessens (eliminates?) the need
for the "escape sequence -> concrete character" kind of character
processing.  We're left with functional character processing, which is much
more limited in scope.

> since the need for breaking non-space comes up much more often in my work.

What do you mean by "breaking non-space"?  Do you mean "zero-width space",
\u200B?

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

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

Re: [Docutils-users] Re: Problem (?) with inline literals

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

David Goodger <go...@py...> writes:

> David Abrahams wrote:
>> I'm not wedded to the syntax. ``` could work.
>
> That would be ambiguous.  Currently, to mark up a backquote as an inline
> literal, you'd use::
>
>     `````
>
> That wouldn't be possible if we adopted ``` as "squeezing" markup.
>
>>> Could you show us specific examples where you'd like to do character-level
>>> markup?
>> 
>> In a pseudocode example,
>> 
>>   F(a1, a2,... aN)
>> 
>> you might want most of the 'a's to be represented as ``code`` while
>> the numbers and the 'N' are represented in an italic variable-width
>> font (subscripted).
>
> Thanks; good example.
>
>> I think it might be enough to add a generalized escape which allows
>> arbitrary ugliness when it's absolutely needed.  That would still
>> allow the rest of our ReST to stay pretty.
>
> There is already such a generalized (although verbose) mechanism for inline
> markup: interpreted text with roles.  They could be done like this::
>
>     subscript: `1`:sub: or :sub:`1`
>     superscript: `2`:sup: or :sup:`2`

Nice!

> There's still the problem of character-level markup though: whitespace is
> required.
>
> One of the tricks listed in the To Do list is to use an escaped character:
>
>     Escaped period or quote or dash as a disappearing catalyst to
>     allow character-level inline markup?
>
> Escaped dash isn't a good choice (may be useful as a soft hyphen).  Periods
> are used as markup (explicit markup start, ".. "), so might legitimately be
> escaped without the intention of the period "disappearing".  That leaves the
> quote.  The idea was that this could be used as markup::
>
>     F(``a``\'`1`:sub:, ``a``\'`2`:sub:, ... ``a``\'`N`:sub:)
>
> Exceedingly ugly, don't you think?

Yes, but serviceable.  Did we discuss the idea that escaped
whitespace disappears?

    F(``a``\ `1`:sub:, ``a``\ `2`:sub:, ... ``a``\ `N`:sub:)

> But combining this idea with setting up a "squeeze environment", I came up
> with this::
>
>     F(\"``a`` `1`:sub:\", \"``a`` `2`:sub:\", ... \"``a`` `N`:sub:\")
>
> Here, the escaped-double-quote sequence acts as "squeeze
> delimiters".  

Icky (IMO).

> Add in escaped spaces as non-breaking spaces, and the above could be
> condensed to::
>
>     \"F(``a`` `1`:sub:,\ ``a`` `2`:sub:,\ ...\ ``a`` `N`:sub:)\"
>
> Also ugly, but less obtrusively so (maybe).  

Yes.  It's unfortunate that you really want '\ ' for a &nbsp;, since
the need for breaking non-space comes up much more often in my work.

> It's ugly, but specialized and
> obscure enough that it may not matter.  Another example::
>
>     \"*re* ``Structured`` *Text*\"
>
>>> Here's another idea: a "squeeze" directive used in a substitution::
>>> 
>>>   Here's how to make |reStructuredText| do character-level markup.
>>> 
>>>   .. |reStructuredText| squeeze::
>>> 
>>>      *re* ``Structured`` *Text*
>>> 
>>> "Squeeze" will remove whitespace from its contents.
>> 
>> The problem is that it squeezes a whole paragraph.
>
> Only the "*re* ``Structured`` *Text*" paragraph, which is inserted into the
> preceding paragraph by the substitution mechanism.  Yes, this example is a
> bit of a kludge.

Ah!  I missed the substitution mechanism.

>> Unless... maybe we could have a category of directive which embeds
>> a paragraph in the surrounding ones.
>
> Not sure what you mean.  A directive can emit a paragraph; all directives
> used in substitutions have to.

I think I just meant "substitution" ;-)

> In any case, this would be a major syntax addition that needs to be
> well thought out.

There's the rub, eh?

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

Re: [Docutils-users] Re: Problem (?) with inline literals

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

David Abrahams wrote:
> I'm not wedded to the syntax. ``` could work.

That would be ambiguous.  Currently, to mark up a backquote as an inline
literal, you'd use::

    `````

That wouldn't be possible if we adopted ``` as "squeezing" markup.

>> Could you show us specific examples where you'd like to do character-level
>> markup?
> 
> In a pseudocode example,
> 
>   F(a1, a2,... aN)
> 
> you might want most of the 'a's to be represented as ``code`` while
> the numbers and the 'N' are represented in an italic variable-width
> font (subscripted).

Thanks; good example.

> I think it might be enough to add a generalized escape which allows
> arbitrary ugliness when it's absolutely needed.  That would still
> allow the rest of our ReST to stay pretty.

There is already such a generalized (although verbose) mechanism for inline
markup: interpreted text with roles.  They could be done like this::

    subscript: `1`:sub: or :sub:`1`
    superscript: `2`:sup: or :sup:`2`

There's still the problem of character-level markup though: whitespace is
required.

One of the tricks listed in the To Do list is to use an escaped character:

    Escaped period or quote or dash as a disappearing catalyst to
    allow character-level inline markup?

Escaped dash isn't a good choice (may be useful as a soft hyphen).  Periods
are used as markup (explicit markup start, ".. "), so might legitimately be
escaped without the intention of the period "disappearing".  That leaves the
quote.  The idea was that this could be used as markup::

    F(``a``\'`1`:sub:, ``a``\'`2`:sub:, ... ``a``\'`N`:sub:)

Exceedingly ugly, don't you think?

But combining this idea with setting up a "squeeze environment", I came up
with this::

    F(\"``a`` `1`:sub:\", \"``a`` `2`:sub:\", ... \"``a`` `N`:sub:\")

Here, the escaped-double-quote sequence acts as "squeeze delimiters".  Add
in escaped spaces as non-breaking spaces, and the above could be condensed
to::

    \"F(``a`` `1`:sub:,\ ``a`` `2`:sub:,\ ...\ ``a`` `N`:sub:)\"

Also ugly, but less obtrusively so (maybe).  It's ugly, but specialized and
obscure enough that it may not matter.  Another example::

    \"*re* ``Structured`` *Text*\"

>> Here's another idea: a "squeeze" directive used in a substitution::
>> 
>>   Here's how to make |reStructuredText| do character-level markup.
>> 
>>   .. |reStructuredText| squeeze::
>> 
>>      *re* ``Structured`` *Text*
>> 
>> "Squeeze" will remove whitespace from its contents.
> 
> The problem is that it squeezes a whole paragraph.

Only the "*re* ``Structured`` *Text*" paragraph, which is inserted into the
preceding paragraph by the substitution mechanism.  Yes, this example is a
bit of a kludge.

> Unless... maybe we could have a category of directive which embeds
> a paragraph in the surrounding ones.

Not sure what you mean.  A directive can emit a paragraph; all directives
used in substitutions have to.

> That would allow nearly arbitrary markup changes
> without adding too much ugliness to the ReST language.

The processing of a directive's contents are up to the directive, so
anything goes.

>> -----------
>> 
>> Unfortunately for Docutils, I'm currenly trying to fulfill a
>> low-level need [*]_ (get a job), so I don't feel much impetus to
>> fulfill higher-level needs like writing open-source software.
> 
> Sorry to hear that; I wish I could help you.

Thanks.  Wasn't meant to be a complaint, just a warning.  Should have added:
"Therefore don't expect a quick response".

In any case, this would be a major syntax addition that needs to be well
thought out.

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

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

Re: [Docutils-users] Re: Problem (?) with inline literals

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

David Goodger <go...@py...> writes:

> [David Abrahams]
>>>> I can think of one way to beautify cases like this: introduce a kind
>>>> of quotation which removes all spaces in what it surrounds as a
>>>> postprocessing step.
>>>> 
>>>>     ''*re* ``Structured`` *Text''
>>>> 
>>>> This would be analogous to re.VERBOSE, if memory serves.
>
> [David Goodger]
>>> I'll add it to the character processing discussion in the To Do list,
>>> but I doubt the feature is worth the cost.
>
> [David Abrahams]
>> Has any progress been made in this general area?
>
> No.  I did add your idea to the To Do list, after this:
>
>   - Escaped period or quote or dash as a disappearing catalyst to
>     allow character-level inline markup?
>
> (<http://docutils.sf.net/spec/notes.html#character-processing>)
>
> I have strong reservations about the use of double-single-quotes as syntax,
> since they may be used in unrelated ways: as ''double quotes''; as empty
> strings as in text=''; or in ``TeX-style quotes'', although these have other
> problems.

I'm not wedded to the syntax. ``` could work.

>> I am finding myself with the need for much finer character
>> processing control, like the ability to switch between ``code`` and
>> normal text on character boundaries, super/subscripts, and
>> bold-italic fonts.
>
> How do you do super/subscripts in reStructuredText?

A1: You don't
A2: See below

> Could you show us specific examples where you'd like to do character-level
> markup?

In a pseudocode example,

    F(a1, a2,... aN)

you might want most of the 'a's to be represented as ``code`` while
the numbers and the 'N' are represented in an italic variable-width
font (subscripted).

>> It's very disappointing when I run up against limitations of ReST since
>> it is otherwise such a pleasure.
>
> reStructuredText is inherently limited due to its WYSIWYG nature.  To get
> past these limitations, ugly workarounds have to be added.

I think it might be enough to add a generalized escape which allows
arbitrary ugliness when it's absolutely needed.  That would still
allow the rest of our ReST to stay pretty.  Just off-the-cuff:

    ``X``..[subscript]*1*..[], ``X``..[subscript]*2*..[],...``X``..[subscript]*N*..[]

> Here's another idea: a "squeeze" directive used in a substitution::
>
>     Here's how to make |reStructuredText| do character-level markup.
>
>     .. |reStructuredText| squeeze::
>
>        *re* ``Structured`` *Text*
>
> "Squeeze" will remove whitespace from its contents.

The problem is that it squeezes a whole paragraph.  Unless... maybe
we could have a category of directive which embeds a paragraph in the
surrounding ones.  That would allow nearly arbitrary markup changes
without adding too much ugliness to the ReST language.


> -----------
>
> Unfortunately for Docutils, I'm currenly trying to fulfill a
> low-level need [*]_ (get a job), so I don't feel much impetus to
> fulfill higher-level needs like writing open-source software.

Sorry to hear that; I wish I could help you.

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

Re: [Docutils-users] Re: Problem (?) with inline literals

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

[David Abrahams]
>>> I can think of one way to beautify cases like this: introduce a kind
>>> of quotation which removes all spaces in what it surrounds as a
>>> postprocessing step.
>>> 
>>>     ''*re* ``Structured`` *Text''
>>> 
>>> This would be analogous to re.VERBOSE, if memory serves.

[David Goodger]
>> I'll add it to the character processing discussion in the To Do list,
>> but I doubt the feature is worth the cost.

[David Abrahams]
> Has any progress been made in this general area?

No.  I did add your idea to the To Do list, after this:

  - Escaped period or quote or dash as a disappearing catalyst to
    allow character-level inline markup?

(<http://docutils.sf.net/spec/notes.html#character-processing>)

I have strong reservations about the use of double-single-quotes as syntax,
since they may be used in unrelated ways: as ''double quotes''; as empty
strings as in text=''; or in ``TeX-style quotes'', although these have other
problems.

> I am finding myself
> with the need for much finer character processing control, like the
> ability to switch between ``code`` and normal text on character
> boundaries, super/subscripts, and bold-italic fonts.

How do you do super/subscripts in reStructuredText?

Could you show us specific examples where you'd like to do character-level
markup?

> It's very disappointing when I run up against limitations of ReST since
> it is otherwise such a pleasure.

reStructuredText is inherently limited due to its WYSIWYG nature.  To get
past these limitations, ugly workarounds have to be added.

Here's another idea: a "squeeze" directive used in a substitution::

    Here's how to make |reStructuredText| do character-level markup.

    .. |reStructuredText| squeeze::

       *re* ``Structured`` *Text*

"Squeeze" will remove whitespace from its contents.

-----------

Unfortunately for Docutils, I'm currenly trying to fulfill a low-level need
[*]_ (get a job), so I don't feel much impetus to fulfill higher-level needs
like writing open-source software.

.. [*] http://chiron.valdosta.edu/whuitt/col/regsys/maslow.html

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

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

Re: [Docutils-users] Another Problem with latex writer

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

David Abrahams wrote:
> I'm beginning to wonder about using this toolchain to get from
> ReST->PDF.

The code is all open & free (gratis & libre).  Patches are gratefully
accepted!

I don't know TeX well, so can't address these issues.  Engelbert Gruber
(main author of the LaTeX writer) wasn't subscribed to this list, so I
forwarded your messages.  Best to also submit a bug report on SF so it won't
be forgotten.

> Maybe ReST->DocBook->PDF is a better bet.

Give the code in sandbox/oliverr/docbook a try.  Once it's in good shape
(that may already be true, I don't know), it can be added to the core.

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

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

Re: FW: [Docutils-users] Problem with latex writer

[engelbert g. <be...@ch...>]

> I'm no LaTeX expert, but it doesn't seem to be able to handle the

me too not.
i see to it tomorrow, parbox seams to dislike verbatim.

replacing \parbox with \begin{minipage} will work in this case
but minipage has its own footnotes.

more tomorrow

> verbatim section below, citing a "runaway argument".
>
>     \begin{center}
>     \parbox{\admwidth}{\textbf{Note}
>
>     MPL's placeholders are in the \texttt{mpl::placeholders}
>     namespace.  In this book we will usually assume that you have
>     written
>     \begin{quote}
>     \begin{verbatim}
>     using namespace mpl::placeholders;
>     \end{verbatim}
>     \end{quote}
>
>     so that they can be accessed without qualification.
>     }
>     \end{center}
>
> This was generated by the following ReST:
>
>     .. Note::  MPL's placeholders are in the ``mpl::placeholders``
>        namespace.  In this book we will usually assume that you have
>        written
>        ::
>
>          using namespace mpl::placeholders;
>
>        so that they can be accessed without qualification.
>
>

-- 
engelbert gruber
email: eng...@ss...

[Docutils-users] Another Problem with latex writer

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

David Abrahams <da...@bo...> writes:


The literal text fragment below:

    In keeping with our quest for polymorphism, ``lambda`` is also a unary
    metafunction returning a metafunction class.  In other words, we could
    have written 

    .. parsed-literal::

       template <class X>
       struct times4
           : twice<**typename mpl::lambda<mpl::plus<_1,_1> >::type**, X>
       {};

Comes out as:

    In keeping with our quest for polymorphism, \texttt{lambda} is also a unary
    metafunction returning a metafunction class.  In other words, we could
    have written
    \begin{quote}
    \begin{verbatim}
    template <class X>
    struct times4
        : twice<\textbf{typename mpl::lambda<mpl::plus<_1,_1> >::type}, X>
    {};
    \end{verbatim}
    \end{quote}

Which in turn is displayed as:

    In keeping with our quest for polymorphism, lambda is also a unary metafunction returning a metafunction
    class. In other words, we could have written
    template <class X>
    struct times4
    : twice<\textbf{typename mpl::lambda<mpl::plus<_1,_1> >::type}, X>
    {};

Note the appearance of TeX directives in the output.
I'm beginning to wonder about using this toolchain to get from
ReST->PDF.  Maybe ReST->DocBook->PDF is a better bet.

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

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

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

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

[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

[Docutils-users] Problem with latex writer

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

I'm no LaTeX expert, but it doesn't seem to be able to handle the
verbatim section below, citing a "runaway argument".

    \begin{center}
    \parbox{\admwidth}{\textbf{Note}

    MPL's placeholders are in the \texttt{mpl::placeholders}
    namespace.  In this book we will usually assume that you have
    written
    \begin{quote}
    \begin{verbatim}
    using namespace mpl::placeholders;
    \end{verbatim}
    \end{quote}

    so that they can be accessed without qualification.
    }
    \end{center}

This was generated by the following ReST:

    .. Note::  MPL's placeholders are in the ``mpl::placeholders``
       namespace.  In this book we will usually assume that you have
       written
       ::

         using namespace mpl::placeholders;

       so that they can be accessed without qualification.

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

[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

[Docutils-users] Re: Problem (?) with inline literals

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

David Goodger <go...@py...> writes:

> David Abrahams wrote:
>> I can think of one way to beautify cases like this: introduce a kind
>> of quotation which removes all spaces in what it surrounds as a
>> postprocessing step.
>> 
>>     ''*re* ``Structured`` *Text''
>> 
>> This would be analogous to re.VERBOSE, if memory serves.
>
> I'll add it to the character processing discussion in the To Do list,
> but I doubt the feature is worth the cost.

Has any progress been made in this general area?  I am finding myself
with the need for much finer character processing control, like the
ability to switch between ``code`` and normal text on character
boundaries, super/subscripts, and bold-italic fonts.  It's very
disappointing when I run up against limitations of ReST since it is
otherwise such a pleasure.

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

[Docutils-users] New Product Release!

[Combatball <sa...@co...>]

<DIV align=center>
<P><A href="http://www.combatball.com" target=_blank><IMG border=0 height=300 name=Combatball src="http://www.combatball.com/advert5.gif" width=439></A></P>
<P><FONT color=#003300 face="Arial, Helvetica, sans-serif" size=2><B>The paintball simulator game that makes no mess.<BR><BR>YOUR HOME IS NOW THE FRONT LINE!</B></FONT></P>
<P>&nbsp;</P>
<P><FONT face="Arial, Helvetica, sans-serif" size=1>To unsubscribe to this e-mail - well not to this one, it's a bit late now,<BR>sorry about that - just send a blank email to <A href="mailto:lea...@co...">lea...@co...</A></FONT></P></DIV>

Re: [Docutils-users] auto-section numbering

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

David Goodger wrote:
> Brett g Porter wrote:
>=20
>>Is there any simple method to use auto-numbering, but to delay its =
start
>>point?
>=20
>=20
> Not currently, no.  But it wouldn't be difficult to add an option t=
o the
> "sectnum" directive, like the "contents" directive's "local" option=
 --
> except that there are some issues to be resolved first.  I see thes=
e
> possibilities:
>=20
> 1. Limit the auto-numbering to the current branch of the document t=
ree
>    ("start here, and auto-number until the end of this section").
>=20
>    What if another local "sectnum" directive appears in another bra=
nch?
>    Are the sequences independent and contain duplicates, or should =
they
>    know about each other and contain unique numbers?
>=20
> 2. Start auto-numbering at the directive, and continue to the end o=
f the
>    document.

For my needs, this (#2) would be more than adequate.



--=20

//  Today's Oblique Strategy (=A9 Brian Eno/Peter Schmidt):
//  Are there sections? Consider transitions
//  Brett g Porter * BgP...@ac...

Re: [Docutils-users] Removing certain elements from reSTX markup

[Morten W. P. <mo...@ni...>]

> What do you do when the user needs one more construct, that isn't 
> included in your simplified set?  Personally, I'd rather begin 
> educating with a small number of core constructs, but using the 
> full parser.  Simultaneously, give references to the full docs
> for those who are interested in going further.
> 
> We don't teach programming languages or natural languages using 
> limited subsets.  We begin with simple concepts and build from there.
> 
> >From PEP 287, Questions & Answers, #2:
> 
>    Is reStructuredText *too* rich?
> 
>    For specific applications or individuals, perhaps.  In general, no.

Exactly.  Althought I appreciate your advice, I'd like to try
out a basic markup and see if it's enough.  The idea isn't
to teach them a basic set and later teach them the whole thing;
the idea is to find a basic set that's easy to teach, and
powerful enough for most (90%+) of the things they need
to markup.

> I'd emphasize the final "or simply omitted by convention" as 
> preferable.

And what happens when the user does something that's an error
according to RST but not part of the markup he/she has learned?

> > Don't touch it, 'pass it on' in other words.
> 
> Please consider carefully: would you really be doing your users a 
> service with this approach?

I believe so, yes.  :)

> I think back to when I learned Japanese.
[...]
> Of course, reStructuredText is a much simpler language, but I believe 
> the same principles apply.

Yes, the principles might apply if the intention is to learn them 
everything, starting with a basic markup.  It isn't the intention.

>> If there are more people out there like me, maybe it would be an idea
>> to refactor a bit to make parts of docutils more like a 'markup
>> parsing framework'?  Make it easier to mix-n-match different
>> markups, which could lead to diverse markup 'dialects' of STX;
>> diverse enough to be used by common people without screwing
>> up, and diverse enough for the syntatic programmer.
> 
> I don't think encouraging dialects is a good idea.  It introduces
> incompatibilities.  This use case doesn't sufficiently justify such 
> changes to me.  'Course, patches are always welcome.

I'd like to play around with it;  if there's time, I will.  :)

Regards,

Morten W. Petersen

Technologies: Zope, Linux, Python, HTML, CSS, PHP
    Homepage: http://www.nidelven-it.no
Phone number: (+47) 45 44 00 69

Re: [Docutils-users] auto-section numbering

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

Brett g Porter wrote:
> Is there any simple method to use auto-numbering, but to delay its start
> point?

Not currently, no.  But it wouldn't be difficult to add an option to the
"sectnum" directive, like the "contents" directive's "local" option --
except that there are some issues to be resolved first.  I see these
possibilities:

1. Limit the auto-numbering to the current branch of the document tree
   ("start here, and auto-number until the end of this section").

   What if another local "sectnum" directive appears in another branch?
   Are the sequences independent and contain duplicates, or should they
   know about each other and contain unique numbers?

2. Start auto-numbering at the directive, and continue to the end of the
   document.

   Should the auto-numbering include the section the directive appears
   within?

   What if the directive appears in a subsection?  We could get weird
   numbering, like::

        Intro
        One         <-- directive appears here
            1. A    <-- or here (depending on another answer)
            2. B
        Two         <-- should this be numbered?  How?

   Perhaps the auto-numbering should always begin with a topmost section
   ("One" above).

On a related note, I'm thinking of adding a feature to "sectnum" to create
implicit hyperlink targets based on the generated section numbers, so that
we can refer to FAQ entries etc. by number.
(<http://docutils.sf.net/FAQ.html#what-s-the-standard-abbreviation-for-restr
ucturedtext> would be replaced by <http://docutils.sf.net/FAQ.html#2-3>.)
Thus the question raised in #1 above becomes important here.

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

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

[Docutils-users] auto-section numbering

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

Is there any simple method to use auto-numbering, but to delay its start 
point?

F'r example, I'm writing a spec, and I'd like to have some introductory 
material that is NOT given a section number, and then have the body of 
the spec auto-numbered, something like:


Intro
======

handwaving and other filler text here...


Heading 1
---------

blah blah blah

detail 1
.........

detail 2
.........

(&c)

would get rendered out as:

Intro

1     Heading 1
1.1   detail 1
1.2   detail 2