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

Re: [Docutils-users] Using blockquote element for quotes

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

Paul Moore wrote:
> I'm trying to generate a list of quotes, something like this::
> 
>     This software is great!!!
>     -- A happy user
> 
>     I agree
>     -- Another user
> 
> I'd like the quotes themselves to be in one style (probably italic)
> and the names to be in another style (probably normal, or bold).

This is very similar to what Brett just asked.  I'll give you the same 
answer I just gave him: use the line-block directve.  If you want more 
semantic information, a new directive would be in order.

In this case, I think you do want a directive.  Such a directive could 
recognize "-- " at the beginning of the last line of a paragraph and 
mark up accordingly.

> But, I can't get the line break between the quote and the user name. I
> don't want a space, so making two paragraphs doesn't work. What I
> really want is the equivalent of HTML's <br> tag, but I can't find it.
> 
> Have I missed something?

We don't have a <br> equivalent.  The Unicode line separator character 
(\u2028) may work, but I somehow doubt it.

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

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

[Docutils-users] Using blockquote element for quotes

[Paul M. <gu...@mo...>]

I'm trying to generate a list of quotes, something like this::

    This software is great!!!
    -- A happy user

    I agree
    -- Another user

I'd like the quotes themselves to be in one style (probably italic)
and the names to be in another style (probably normal, or bold).

I can get most of the way there with stylesheets, with the source like
this::

    Running text...

        This software is great!!!
        `-- A happy user`

Plus a stylesheet::

    blockquote {
        font-style: italic;
    }

    blockquote cite {
        font-style: normal;
        font-weight: bold;
    }

But, I can't get the line break between the quote and the user name. I
don't want a space, so making two paragraphs doesn't work. What I
really want is the equivalent of HTML's <br> tag, but I can't find it.

Have I missed something?

Paul.
-- 
This signature intentionally left blank

Re: [Docutils-users] Idiomatic way to create a bibliography?

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

David Goodger wrote:
> Brett g Porter wrote:
> 
>> I'm trying to add a bibliography to the end of a doc that I'm 
>> creating, and I'm not sure what the most idiomatic way to mark that up 
>> is.
> 
> ...
> 
>> Any suggestions?
> 
> 
> A simple way to do it would be to use the line-block directive::
> 

That's more than adequate. Serves me right for not looking outside the 
"Quick rST" doc...

Thanks!

BgP

Re: [Docutils-users] Idiomatic way to create a bibliography?

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

Brett g Porter wrote:
> I'm trying to add a bibliography to the end of a doc that I'm creating, 
> and I'm not sure what the most idiomatic way to mark that up is.
...
> Any suggestions?

A simple way to do it would be to use the line-block directive::

     .. line-block::

         Design Patterns: Elements of Reusable Object-Oriented Software
         By Gamma, Erich et. al.
         395 Pages
         Published by Addison Wesley
         Date Published: 09/1994
         ISBN: 0201633612

Perhaps in combination with a definition list? ::

     Design Patterns: Elements of Reusable Object-Oriented Software
         .. line-block::

            By Gamma, Erich et. al.
            395 Pages
            Published by Addison Wesley
            Date Published: 09/1994
            ISBN: 0201633612

If you want more semantic information than that (none ;-), a new 
directive would be in order.  I wouldn't be averse to adding a 
bibliography element set to the Docutils document model.

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

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

[Docutils-users] Idiomatic way to create a bibliography?

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

I'm trying to add a bibliography to the end of a doc that I'm creatin=
g,=20
and I'm not sure what the most idiomatic way to mark that up is. I wa=
nt=20
it to end up rendered like:

Design Patterns : Elements of Reusable Object-Oriented Software
By Gamma, Erich et. al.
395 Pages
Published by Addison Wesley
Date Published: 09/1994
ISBN: 0201633612

Literate Programming
By Knuth, Donald Ervin
Published by CSLI Publishing
Date Published: 05/1992
ISBN: 0521073806

I'm not crazy abou tany of the three possibilities that have popped i=
nto=20
my head:

1) Separate the lines in the rST source so eash is rendered as a=20
separate graf

2) Use field lists

3) Use a literal block

Any suggestions?



--=20
//  Today's Oblique Strategy (=A9 Brian Eno/Peter Schmidt):
//  How would you have done it?
//  Brett g Porter * BgP...@ac...

RE: [Docutils-users] Strange section structure

[Moore, P. <Pau...@at...>]

From: David Goodger [mailto:go...@py...]

> See <http://docutils.sourceforge.net/FAQ.html>, question 3.4.

Got it. Thanks.

>> I can't see the logic from the "Quick reST" document, or from the
>> specification.

> It's a writer (output format) issue, unrelated to reStructuredText,
> therefore not in the scope of the spec or quickref. If you don't like
> the way it works, you're welcome to roll your own HTML writer.

Hmm, OK. I can see that. Actually, the reason I noticed it was because
I was doing a "quick" conversion from another format, and was surprised
when everything went "up a level". Fiddling with the stylesheet is an
easy enough answer for me.

I still think it's not "obvious" in some subtle sense, but that's
probably just a matter of remembering that "easy to read" is a more
important design goal than "easy to write". (That's not a criticism,
even though I can't find a way of stating it which doesn't have that
feel to it...)

Paul.

Re: [Docutils-users] Strange section structure

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

On Thu, 17 Apr 2003, David Goodger wrote:

> Moore, Paul wrote:
> > I don't understand.
>
> See <http://docutils.sourceforge.net/FAQ.html>, question 3.4.
>
> In conjunction with the "<body>-only HTML writer" discussions, there
> have been suggestions of a runtime setting for the first section's <Hx>
> level (x = 1 .. 6).

AFAIR: this was to mimmic zope-stx that started with h3
if we give this option, the title-transform might give::

  h2 class=title
  h2
  h3

right ?

> > I can't see the logic from the "Quick reST" document, or from the
> > specification.
>
> It's a writer (output format) issue, unrelated to reStructuredText,
> therefore not in the scope of the spec or quickref.  If you don't like
> the way it works, you're welcome to roll your own HTML writer.

see sandbox/bbum for a "plain HTML writer" or maybe someother stuff in the
sandbox before rolling.

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

Re: [Docutils-users] Strange section structure

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

Moore, Paul wrote:
> I don't understand.

See <http://docutils.sourceforge.net/FAQ.html>, question 3.4.

In conjunction with the "<body>-only HTML writer" discussions, there 
have been suggestions of a runtime setting for the first section's <Hx> 
level (x = 1 .. 6).

> I can't see the logic from the "Quick reST" document, or from the
> specification.

It's a writer (output format) issue, unrelated to reStructuredText, 
therefore not in the scope of the spec or quickref.  If you don't like 
the way it works, you're welcome to roll your own HTML writer.

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

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

RE: [Docutils-users] Strange section structure

[Moore, P. <Pau...@at...>]

From: Moore, Paul=20
> I don't understand. I created a document like this::
[...]
> Now, I'd expect this to be translated into a H1 heading, some text,
> then a H2 subsection. But it doesn't::
[...]
> Note that "a sub" is in H1 style!!!!!

> Why is this?

Hmm, I think I found it. Is this what the bit about the "DocTitle
transform" is describing? If so, I can't get what I want.

Basically, with a document::

    This is the document title
    =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D

    blah blah blah

    This is section 1
    -----------------

    rhubarb rhubarb

    Section 2
    ---------

    custard custard

I would like a HTML output with a *single* H1 section, containing
*two* H2 sections. Ideally, the HTML <title> tag should contain the
text of the H1 heading, but that shouldn't affect the structure of
the document. Specifically, I don't want the ``----`` underlined
headings "promoted" to H1 elements.

How do I achieve this?

Adding an extra "overall" title (duplicating the document title, but
with a "stronger" decoration) doesn't work either, as the ``---``
sections get bumped *up* to H1s. This seems like a bug to me...

Example::

    =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D
    This is the document title
    =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D

    This is the document title
    =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D

    blah blah blah

    This is section 1
    -----------------

    rhubarb rhubarb

    Section 2
    ---------

    custard custard

Paul.

PS The doctitle transform is worrying, in that it gives highly non-
   intuitive results (to me, at least) from what looks like trivially
   simple markup.

[Docutils-users] Strange section structure

[Moore, P. <Pau...@at...>]

I don't understand. I created a document like this::

    a test
    =3D=3D=3D=3D=3D=3D

    as

    a sub
    -----

    whatever

Now, I'd expect this to be translated into a H1 heading, some text,
then a H2 subsection. But it doesn't::

    <?xml version=3D"1.0" encoding=3D"utf-8" ?>
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" =
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns=3D"http://www.w3.org/1999/xhtml" xml:lang=3D"en" =
lang=3D"en">
    <head>
    <meta http-equiv=3D"Content-Type" content=3D"text/html; =
charset=3Dutf-8" />
    <meta name=3D"generator" content=3D"Docutils 0.2.8: =
http://docutils.sourceforge.net/" />
    <title>a test</title>
    <link rel=3D"stylesheet" href=3D"default.css" type=3D"text/css" />
    </head>
    <body>
    <div class=3D"document" id=3D"a-test">
    <h1 class=3D"title">a test</h1>
    <p>as</p>
    <div class=3D"section" id=3D"a-sub">
    <h1><a name=3D"a-sub">a sub</a></h1>
    <p>whatever</p>
    </div>
    </div>
    </body>
    </html>

Note that "a sub" is in H1 style!!!!!

Why is this?

I can't see the logic from the "Quick reST" document, or from the =
specification.

Paul.

[Docutils-users] rST wikis ready to use?

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

I'm thinking of using a wiki and of couse I want an rST one.  There
were several messages on the list but I didn't understood clearly if
any are ready to use.  Could somebody clarify it?  Sorry for being
lazy ;)

-- 
Beni Cherniavsky <cb...@tx...>

Never spend several weeks on a single homework - or you will miss a
nice Linux conference ;-(.

Re: [Docutils-users] roles

[William D. <wi...@fl...>]

"Moore, Paul" <Pau...@at...> writes:

> From: Aahz [mailto:aa...@py...]
> >> Maybe we need a couple of simple "registration" wrappers, eg
> [...]
> 
> > Yes, I've said that before.  Let me put on my Goodger hat and say,
> > "Patches welcome."  ;-)
> 
> Well, OK then. See attached. It's basically what I said, but in patch
> format. But:
> 
> 1. I've never needed to write a user-defined directive, so I don't
>    know if it's "right" in terms of how it would be used.
> 2. There's a lot of cut and paste with the different languages.
>    Someone who knows something about internationalisation should
>    consider refactoring a bit.
> 3. I don't believe that any of this is documented other than in the
>    HOWTO. The HOWTO should get updated, but I don't know where the
>    source is.
> 4. As I said, maybe for the languages/??.py changes, it's good enough
>    just to document the directives dictionary as an "official" API.
>    I've not got the experience to judge this, though.
> 
> "Patches welcome" is easy enough, it's the design that's hard :-)

I try your patch, it works when the directive is in the current
directory, but not if it is somewhere else (in an other module).

register_directive("exergue",("mydirectives","exergue")) is OK
but
register_directive("exergue",("rst2web.mydirectives","exergue"))
doesn't works : <string>:4: (ERROR/3) Unknown directive type "exergue".

I found an other solution : register the directive directly in the
directive cache

def register_directive(name, directive):
    """Register a user defined directive"""
    _directives[name] = directive

and i can use it like that :

import rst2web.mydirectives
from docutils.parsers.rst import directives
directives.register_directive("exergue", rst2web.mydirectives.exergue)

rst2web.mydirectives.exergue is a directive function


-- 
William Dode - http://flibuste.net

Re: [Docutils-users] Questions

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

Thanks Beni; good answers.  Being chaneled is kinda nice.

[Eric Armstrong]
 >>>  1. Is the preferred abbreviation rst or reST?

I prefer RST, but answer to either.  See
<http://docutils.sourceforge.net/FAQ.html>, question 2.3.  Beni's
"re?ST" regexp is cute though.

 >>>  2. Is there an rst to HTML filter program out there
 >>>     anywhere?

[Beni Cherniavsky]
 >> Sure, ``docutils/tools/html.py``.

Right.

 >> The sandbox also has all kinds of other writers - to LaTeX, PDF,
 >> docbook and what not - in various degrees of completion.

The LaTeX Writer has actually been moved into the core Docutils
package.

 >>>  3. I'm inclined to think that Mozilla got text formatting
 >>>     right, with *foo bar* in bold, /foo bar/ in italics (but
 >>>     /foo/bar is recognized as a path),

But /foo/ is also a path, and even /foo bar/ could be a path (although
the space may have to be escaped, spaces *are* legal in most OSes).
Using "/" for markup is just too ambiguous.

 >>>     and _foo bar_ for underlining.
...
 >> Underlining is especially frowned upon - you'll almost never see it
 >> in a book...

See <http://docutils.sf.net/spec/rst/problems.html#underlining>.

 >>>     Is there some overwhelming reason why ** was chosen for bold?

reStructuredText is based on the ideas from StructuredText and Setext.
* and ** came from them.

 >>>  4. The "quick reference" at
 >>>     http://docutils.sourceforge.net/docs/rst/quickref.html
 >>>     contains a huge number of markyp devices (which leads me
 >>>     to believe it must be complete).
 >>
 >> No markup standard can ever be complete ;-).

True.  The quickref is not meant to be totally complete, just
reasonably complete for quick reference purposes.  The complete
references is at
<http://docutils.sf.net/spec/rst/reStructuredText.html>.

[Eric Armstrong]
 > One thing that struck me as odd, though, were the blank
 > lines after the underlined headers in the rst file. Is
 > that required by the standard, or was it just a formatting
 > option chosen by the writers. (I'm hoping it's the latter.)

It is an aesthetic choice.  See
<http://docutils.sf.net/spec/rst/reStructuredText.html#sections>:

     A blank line after a title is optional.

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

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

Re: [Docutils-users] Questions

[Eric A. <eri...@su...>]

(Again: Please reply-all to this post. Thanks.)

Beni Cherniavsky wrote:
 > ...(lots of good stuff)...
 >
Thanks, Beni. Marvelous response. I agree with your
comments. In particular:
   * You're right that italics is the preferred typographic
     emphasis.
   * And that there were no pre-existing standards for
     emphasis vs. strong-emphasis to choose from.

On the other hand, now that Mozilla shows me *foo* in
bold, I've taken to using /foo/ for emphasis, instead.
(But without that interactive feedback device to change
my habits, I would probably have adopted the rst solution,
as well.)

Also:
   * The rst HTML pages are pretty darn sophisticated, so
     the fact that they are rst-based is encouraging. (It's
     as close to complete as I'm ever going to need.)

One thing that struck me as odd, though, were the blank
lines after the underlined headers in the rst file. Is
that required by the standard, or was it just a formatting
option chosen by the writers. (I'm hoping it's the latter.)

[Docutils-users] reST writer to write HTML "fragments"

[Moore, P. <Pau...@at...>]

Just noticed this in the ActiveState Python Cookbook:

http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/193890

A quick test looks like it does the job. Might be useful
for people who want to embed reST into other documents
(like Wikis).

Apologies if this is well known to people...
Paul.

Re: [Docutils-users] Questions

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

Eric Armstrong wrote on 2003-04-10:

> Hello. I'm not (yet) a member of this list, so please
> reply to all.
>
> The markup standard looks amazingly complete, but I
> do have few questions:
>
>   1. Is the preferred abbreviation rst or reST?
>
This I wanted to know too :-).  David?

>   2. Is there an rst to HTML filter program out there
>      anywhere?
>
Sure, ``docutils/tools/html.py``.  The sandbox also has all kinds of
other writers - to LaTeX, PDF, docbook and what not - in various
degrees of completion.

>   3. I'm inclined to think that Mozilla got text formatting
>      right, with *foo bar* in bold, /foo bar/ in italics (but
>      /foo/bar is recognized as a path), and _foo bar_
>      for underlining. Is there some overwhelming reason why
>      ** was chosen for bold?
>
Mozilla went with WYSIWYG approach here.  re?ST tries to be a logical
format, so it just has *emphasis* and **strong emphasis**.   It so
happens that italics are the preferred emphasis style according to
typographic wisdom, bold coming second.  Underlining is especially
frowned upon - you'll almost never see it in a book...

These mappings are writer-dependent and can be tweaked in most cases,
for example you can provide your own stylesheet to the html writer...

>      (One thing I liked about my intitial introduction to the
>       standard was the way it codified existing practice. But
>       I've never see ** used in an email anywhere.)
>
Me neither - but emails don't have any accepted practice of normal vs.
strong emphasis so there was nothing to choose from.  Every one uses
other ranking of the possible "decorations" of text, some creative and
amusing but only appropriate for ascii-only mediums like email...

>   4. The "quick reference" at
>      http://docutils.sourceforge.net/docs/rst/quickref.html
>      contains a huge number of markyp devices (which leads me
>      to believe it must be complete).

No markup standard can ever be complete ;-).  It's pretty close
however and has some extension hooks: directives are very easy to add
and easy role extensibility is now being discussed.

>      But the "primer" at
>      http://docutils.sourceforge.net/docs/rst/quickstart.html
>      has a much more approachable subset that is easily grasped.
>
>      Is there perhaps a "subset standard" like the one described
>      in the tutorial, and perhaps a filter for that?
>
There was some disccussion on this recently; the problem is that any
such subset will be quickly outgrown by one's need - and what does he
do then?  All re?ST constructs were added when someone needed them
(and some needs were left unanswered still).  What do you want to gain
by defining a subset?

-- 
Beni Cherniavsky <cb...@tx...>

[Docutils-users] Questions

[Eric A. <eri...@su...>]

Hello. I'm not (yet) a member of this list, so please
reply to all.

The markup standard looks amazingly complete, but I
do have few questions:

  1. Is the preferred abbreviation rst or reST?

  2. Is there an rst to HTML filter program out there
     anywhere?

  3. I'm inclined to think that Mozilla got text formatting
     right, with *foo bar* in bold, /foo bar/ in italics (but
     /foo/bar is recognized as a path), and _foo bar_
     for underlining. Is there some overwhelming reason why
     ** was chosen for bold?

     (One thing I liked about my intitial introduction to the
      standard was the way it codified existing practice. But
      I've never see ** used in an email anywhere.)

  4. The "quick reference" at
     http://docutils.sourceforge.net/docs/rst/quickref.html
     contains a huge number of markyp devices (which leads me
     to believe it must be complete). But the "primer" at
     http://docutils.sourceforge.net/docs/rst/quickstart.html
     has a much more approachable subset that is easily grasped.

     Is there perhaps a "subset standard" like the one described
     in the tutorial, and perhaps a filter for that?

thanks
eric

Re: [Docutils-users] roles

[Stefan M. <sm...@oe...>]

-----BEGIN PGP SIGNED MESSAGE-----

Hi folks!

May be I can't help here very much because I did not even look at the
code, but...

Today Moore, Paul wrote:
> I'd say we should have a <span> equivalent. Yes, it's general, but so
> what?

...my penny on <span>: I think <span> is inherently evil. More than
enough I learned to hate <span> because some HTML pages are full of it
and it is a pain to translate them to a useful format.

I think <span> is an indication that you don't have a concept for what
you want to express. <span> is totally unrelated to the *real*
structure of the information and introduces more or less a new
language. I think this should be prevented.


						Mit Freien Gr=FC=DFen

						Stefan

-----BEGIN PGP SIGNATURE-----
Version: 2.6.3in
Charset: noconv
Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface

iQCVAwUBPpXSngnTZgC3zSk5AQH+agP/RyhucuUpblt/NYs1bCDYGACViqYMgVBQ
jO+MzHRFCgdlCWtqT+/8ZRMOA7orltM6WBXItcsxMHnHeLRr5uc2ZfZNvREHcg+z
G0MTLgEchdUr1xJdaMK5Qq3/ws2tttk8qLF+o9MBo1Rqmm42TqtgcVnPGlwIJAr4
LkVRFyt6sbA=3D
=3DGj2R
-----END PGP SIGNATURE-----

RE: [Docutils-users] roles

[Moore, P. <Pau...@at...>]

From: Aahz [mailto:aa...@py...]
>> Maybe we need a couple of simple "registration" wrappers, eg
[...]

> Yes, I've said that before.  Let me put on my Goodger hat and say,
> "Patches welcome."  ;-)

Well, OK then. See attached. It's basically what I said, but in patch
format. But:

1. I've never needed to write a user-defined directive, so I don't
   know if it's "right" in terms of how it would be used.
2. There's a lot of cut and paste with the different languages.
   Someone who knows something about internationalisation should
   consider refactoring a bit.
3. I don't believe that any of this is documented other than in the
   HOWTO. The HOWTO should get updated, but I don't know where the
   source is.
4. As I said, maybe for the languages/??.py changes, it's good enough
   just to document the directives dictionary as an "official" API.
   I've not got the experience to judge this, though.

"Patches welcome" is easy enough, it's the design that's hard :-)

Paul.

Re: [Docutils-users] roles

[Aahz <aa...@py...>]

On Thu, Apr 10, 2003, eng...@ss... wrote:
> On Thu, 10 Apr 2003, Aahz wrote:
>> On Thu, Apr 10, 2003, Moore, Paul wrote:
>>>
>>> On a related note, I skimmed the HOWTO on writing your own directive,
>>> which I just found on the website. It's great - congratulations to Dethe
>>> Elza for writing it - but it seems to imply that you need to edit some
>>> of the source of docutils itself (eg, to add the new directive into
>>> _directives_registry). Maybe we need a couple of simple "registration"
>>> wrappers, eg
>>>
>>>     [in directives/__init__.py]
>>>     def register_directive(name, data):
>>>         _directive_registry[name] = data
>>>
>>>     [in languages/en.py, and presumably others]
>>>     def register_directive_name(local_name, canonical_name):
>>>         directives[local_name] = canonical_name
>>
>> Yes, I've said that before.  Let me put on my Goodger hat and say,
>> "Patches welcome."  ;-)
> 
> not too hasty boyz: i said this lately regarding the specification of
>   urlcolors for the latexwriter and i am not so sure if this shouldnt
>   be done via stylesheet.

I'm not referring to this specific issue; I believe that it is entirely
appropriate for a local installation of docutils to add private
directives.  For example, suppose someone wants to run some code to
generate some text from a database?  Yes, zie could use the generic "run
external command" directive, but that might be overkill (not to mention
a security risk).  Given that, there should be a straightforward API for
extending docutils.

> OTOH: this one does not look bad: means we end up with some local
>   docutils plugins, which is securitywise better than interpreted text
>   but what happens if one lacks the extensions.

Then the document can't be output to other formats.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

This is Python.  We don't care much about theory, except where it intersects 
with useful practice.  --Aahz, c.l.py, 2/4/2002

Re: [Docutils-users] roles

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

On Thu, 10 Apr 2003, Aahz wrote:

> On Thu, Apr 10, 2003, Moore, Paul wrote:
> >
> > On a related note, I skimmed the HOWTO on writing your own directive,
> > which I just found on the website. It's great - congratulations to Dethe
> > Elza for writing it - but it seems to imply that you need to edit some
> > of the source of docutils itself (eg, to add the new directive into
> > _directives_registry). Maybe we need a couple of simple "registration"
> > wrappers, eg
> >
> >     [in directives/__init__.py]
> >     def register_directive(name, data):
> >         _directive_registry[name] = data
> >
> >     [in languages/en.py, and presumably others]
> >     def register_directive_name(local_name, canonical_name):
> >         directives[local_name] = canonical_name
>
> Yes, I've said that before.  Let me put on my Goodger hat and say,
> "Patches welcome."  ;-)

not too hasty boyz: i said this lately regarding the specification of
  urlcolors for the latexwriter and i am not so sure if this shouldnt
  be done via stylesheet.

the same happened when sidebars were added: couldnt these have been done
  by a :class: attribute to topic.

OTOH: this one does not look bad: means we end up with some local
  docutils plugins, which is securitywise better than interpreted text
  but what happens if one lacks the extensions.

maybe post the patches (although reverting is possible too).

-- 
 BINGO: significantly improved cost structure
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-users] roles

[Aahz <aa...@py...>]

On Thu, Apr 10, 2003, Moore, Paul wrote:
>
> On a related note, I skimmed the HOWTO on writing your own directive,
> which I just found on the website. It's great - congratulations to Dethe
> Elza for writing it - but it seems to imply that you need to edit some
> of the source of docutils itself (eg, to add the new directive into
> _directives_registry). Maybe we need a couple of simple "registration"
> wrappers, eg
> 
>     [in directives/__init__.py]
>     def register_directive(name, data):
>         _directive_registry[name] = data
> 
>     [in languages/en.py, and presumably others]
>     def register_directive_name(local_name, canonical_name):
>         directives[local_name] = canonical_name

Yes, I've said that before.  Let me put on my Goodger hat and say,
"Patches welcome."  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

This is Python.  We don't care much about theory, except where it intersects 
with useful practice.  --Aahz, c.l.py, 2/4/2002

RE: [Docutils-users] roles

[Moore, P. <Pau...@at...>]

From: David Goodger [mailto:go...@py...]
> In HTML, yes.  But what to use in the Docutils internal doc tree?
> Maybe we need an equivalent to <span> for arbitrary text spans, but
> I'd rather avoid it if possible (over-general).

I'd say we should have a <span> equivalent. Yes, it's general, but so
what? Why do you feel that generality is wrong here? We're at the stage
where we don't want to add much more to core docutils, but allow user
extensibility (user-defined directives) to handle any domain-specific
requirements.

For that to work, it's imperative that there be some form of "hook"
into the doctree, which can be used for user-defined (ie, general)
purposes. Otherwise, we just change from handling lots of requests for
domain-specific reST constructs, to handling lots of requests for
domain-specific doctree elements...

The key things here are directives and roles. Allowing an application
to define its own directives and roles, while still reusing as much as
possible of the docutils code, seems pretty crucial to me.

On a related note, I skimmed the HOWTO on writing your own directive,
which I just found on the website. It's great - congratulations to Dethe
Elza for writing it - but it seems to imply that you need to edit some
of the source of docutils itself (eg, to add the new directive into
_directives_registry). Maybe we need a couple of simple "registration"
wrappers, eg

    [in directives/__init__.py]
    def register_directive(name, data):
        _directive_registry[name] =3D data

    [in languages/en.py, and presumably others]
    def register_directive_name(local_name, canonical_name):
        directives[local_name] =3D canonical_name

It's trivial, but it makes the exposed API more complete. Maybe the
language-specific one isn't necessary, and just documenting the
"directives" dictionary is enough, there. Your call, I guess.

Sorry, that was rambling. I hope it made sense.
Paul.

Re: [Docutils-users] roles

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

David Goodger wrote on 2003-04-09:

>  > While I sympathise with the desire to keep reST output format
>  > independent, I think it would be useful in certain cases, such as
>  > this, to have a way of specifying the whole thing in the reST.
>
> Perhaps.  I simply think that a generic solution ought to be
> considered before a format-specific one.
>
I presume you don't propose to invent a new stylesheet language that
will be translatable to all output formats (although that would be
handy :-).  Then, the tuning of the presentation has to be done for
each format separately in any case.  So you probably mean that you'd
rather keep this tuning outside of the reST [1]_ text, right?

.. [1] What's the "canonical" abbreviation?  rST?  reST?  ReST?

Then, all we need is some data channel from reST into the
format-specific tuning.  Indeed, a single "class" name should be good
enough for most cases (when your styling doesn't fit a single class,
you are probably way outside reST's goals anyway).

There should be no problem to map it in each writer either to the
format's standard styling mechanism (e.g.  ``class="..."`` in html,
which is seen by CSS) or through a custom mapping tool (e.g. the PDF
writer could implement reading and applying a class -> ReportLab's
style attributes table (I see it already has one for the built-in
elements).

>  > > This would implement the "rewrite" role as adding a
>  > > ``class="rewrite"`` attribute to the interpreted text (note to
>  > > self: but what's the element?)
>  >
>  > It probably should be <span>.
>
> In HTML, yes.  But what to use in the Docutils internal doc tree?
> Maybe we need an equivalent to <span> for arbitrary text spans, but
> I'd rather avoid it if possible (over-general).
>
Did you choose one for the class directive?  The moment you have such
a directive, you can sneak this element into text anyway (with
substitutions), so just use it for this.  The html writer might have
to choose <div> or <span> depending on the context.

Another option that springs to mind is not to add yet another mapping
from roles to directives - just map roles 1-to-1 to classes (except
perhaps for builtin roles, although they too can be changed to match,
if they don't already).  This loses the power of arbitrary directives
as role meaning, limiting it to just the class directive.

What would an arbitrary role -> directive mapping do with directives
that take many arguments?  The originally proposed syntax suggests
that all arguments (field list, etc.) except for the body itself of
the directive are given once in the mapping.  That can surely work but
I'm not sure with what directives it would be useful...  OTOH, when
you need more flexibility you always can do per-case substitutions...

-- 
Beni Cherniavsky <cb...@tx...>

Re: [Docutils-users] roles

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

[David Goodger]
 >> In the specific example, I think the "font-color: red" part ought
 >> to reside in a stylesheet rather than in the document.  I might use
 >> the already-proposed "class" directive instead::

[Paul Moore]
 > (Butting in here, sorry)

Please do.

 > In the use case described (a Wiki) the person writing the reST won't
 > have access to the stylesheet, or indeed to *any* other aspect of
 > the final result.

In that case, I'd say the feature simply isn't supported by the
application and leave it at that.

 > While I sympathise with the desire to keep reST output format
 > independent, I think it would be useful in certain cases, such as
 > this, to have a way of specifying the whole thing in the reST.

Perhaps.  I simply think that a generic solution ought to be
considered before a format-specific one.

 > Hmm, maybe it's possible with the ``raw`` directive::
 >
 >     .. raw:: html
 >        <style>
 >        .rewrite { color: red }
 >        </style>
 >
 >     .. :rewrite: class:: rewrite
 >
 >     `This needs checking`:rewrite:
 >
 > Would that work??

According to the HTML spec, <style> is only allowed inside <head>.
Even though some browsers may accept it elsewhere, we should stick to
the spec.  A "raw-head" directive as Beni suggests could do it.  These
are all simply implementation details though.

 >> This would implement the "rewrite" role as adding a
 >> ``class="rewrite"`` attribute to the interpreted text
 >> (note to self: but what's the element?)
 >
 > It probably should be <span>.

In HTML, yes.  But what to use in the Docutils internal doc tree?
Maybe we need an equivalent to <span> for arbitrary text spans, but
I'd rather avoid it if possible (over-general).

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

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