docutils-develop — For developer discussions of the implementation.

Re: [Docutils-develop] Formatting bulleted list of email addresses

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

Bill Bumgarner wrote:
> Say I want to do a section that contains nothing but a bulleted list of
> people, with each person being a mailto: link.
> 
> How should that be formatted?
> 
> =========================
> People
> ------
> 
> * `Bill Bumgarner`__
> __ mailto:"Bill Bumgarner" <bb...@co...>
> 
> * `Joe Smith`__
> __ mailto:"Joe Smith" <jo...@fo...>
> ==========================

The error messages are correct.  You'll have to reformat.

> If i remove the spaces from the mailto URLs (bummer-- anyway to format
> mailtos as shown above??):
  
I don't think you can encode the "common name" of an email recipient in a
URI.  URIs can't have spaces.  According to RFC 1738:

    No additional information other than an Internet mailing address
    is present or implied.

> If I put a newline after each * line, the resulting HTML has each
> bullet in its own <ul></ul> block.  Why would the anonymous hyperlink
> cause that? 

The target has to be left-aligned with the paragraph (indented relative for
the "*") for it to be part of the list item; otherwise the list ends.

> The anon link should be invisible to the structure of the
> doc, I would think.

I wouldn't ;).  The unindented block ends the list.  It would require a
special exception to go back and stitch blocks together for "invisible"
intervening blocks.  But what about cases where the "invisible" blocks were
*intended* to separate other constructs (that's the whole point of empty
comments, for example)?  I think it would add too much conceptual
complexity.

If you want to keep the targets together with the references, do this::

    * `Bill Bumgarner`__

      __ mailto:bb...@co...

(As a convenience, "mailto:" isn't strictly required in any of these target
forms.  Email addresses are distinctive enough to be unambiguous.)

The blank line is required to separate the paragraph from the target.  To
save some vertical space, you could put all the targets after the list::

    * `Bill Bumgarner`__
    * `Joe Smith`__

    __ bb...@co...
    __ jo...@fo...

Or you could use embedded URIs::

    * `Bill Bumgarner <bb...@co...>`__
    * `Joe Smith <jo...@fo...>`__

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] DocArticle in sandbox

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

[Bill Bumgarner]
>> Is there some test restructured text source that
>> exercises all required features?

[Aahz]
> tools/test.txt
> 
> David, maybe this should go into test/ or at least spec/ so that it's
> easier to find?

Yes, that would probably be a good thing.  Engelbert Gruber once suggested
that it be split up to allow for incremental testing.  A master document
with lots of "include" directives could put it all back together again.

Any volunteers?

-- David Goodger    go...@py...

Re: [Docutils-develop] HTML Acronyms

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

Jason Diamond wrote:
> I'm trying to add support to the html4css1 writer for acronyms. I want
> interpreted text that matches a known set of acronyms to output an
> <acronym> element instead of the default <span class="interpreted">
> element it outputs now. For example, `reST` should output <acronym
> title="reStructuredText">reST</acronym>.
> 
> I'm new to the docutils source code so was wondering what the best way
> to do this would be. I thought I'd add an --acronyms-file option to the
> writer, load the acronyms and their titles out of that file, and then
> check to see if the text for an interpreted node was one of those known
> acronyms. Is this an appropriate approach or should I be looking at
> implementing it via a transform? This makes sense to me since the
> acronym element I'm trying to output is specific to HTML.

There isn't a lot of support for interpreted text in Docutils yet.  It has
been a "future expansion" feature, but it looks like the future has arrived.
The main application of interpreted text has been the Python Source Reader,
which is making slow progress.  See PEP 258
(<http://docutils.sf.net/spec/pep-0258.html>) and
<http://docutils.sf.net/spec/pysource.html#interpreted-text> for details.

A quick & dirty way to implement what you want would be to indicate the role
of each acronym like this: "`reST`:acronym:" or "`reST`:a:".  This will put
the role into a doctree node attribute, which is easy to check for in code.
But the text is butt-ugly and this approach become obsolete (read on).

From <http://docutils.sf.net/spec/notes.html#restructuredtext-parser>:

    Alan Jaffray suggested (and I agree) that it would be sensible to:
    
    - have a directive to specify a default role for interpreted text
    - allow the reST processor to take an argument for the default role
    - issue a warning when processing documents with no default role
      which contain interpreted text with no explicitly specified role

(I just added "and/or command-line option" after "directive".)

An application (or document or processing run) could specify a default role,
so a ":role:" prefix or suffix wouldn't be required; plain `backquotes`
would be sufficient.

Ideally and eventually, the "interpreted" element will disappear from the
Docutils doctree.  In its place will be a customizable set of inline
elements including "acronym" and "index_entry", directly created by the
parser.

I won't be able to work on this for at least a week.  If you're interested
in helping out, please do!  If anything is unclear (and I'm sure there's
lots), please ask. 

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-develop] Re: Italian language support files

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

Nicola Larosa wrote:
> Please find, in tar.gz file attached to the patch #659080 on the SF project,
> the two "it.py" files needed to add Italian language support to Docutils.

Checked in & closed patch.  Grazie!

-- David Goodger    go...@py...

[Docutils-develop] languages; all keys lowercase...

[Bill B. <bb...@co...>]

To make a document more readable in raw form, I naturally used :Author: 
as opposed to :author:.

The document failed to parse, as a result.

Looking at the implementation, is there any reason not to use lower() 
when looking up a name in the Languages dictionary/module?

I.e.:

     def visit_admonition(self, node, name):
         self.bodyContent.append('<hr width="50%" />')
         self.bodyContent.append('<b>' + 
self.language.labels[name.lower()] + ':</b><br />\n')
b.bum

[Docutils-develop] Formatting bulleted list of email addresses

[Bill B. <bb...@co...>]

Say I want to do a section that contains nothing but a bulleted list of 
people, with each person being a mailto: link.

How should that be formatted?

=========================
People
------

* `Bill Bumgarner`__
__ mailto:"Bill Bumgarner" <bb...@co...>

* `Joe Smith`__
__ mailto:"Joe Smith" <jo...@fo...>
==========================

The above causes output like:

/tmp/foo.txt:5: (WARNING/2) Bullet list ends without a blank line; 
unexpected unindent.
/tmp/foo.txt:5: (WARNING/2) Anonymous hyperlink target contains 
whitespace. Perhaps a footnote was intended?

__ mailto:"Bill Bumgarner" <bb...@co...>
/tmp/foo.txt:8: (WARNING/2) Bullet list ends without a blank line; 
unexpected unindent.
/tmp/foo.txt:8: (WARNING/2) Anonymous hyperlink target contains 
whitespace. Perhaps a footnote was intended?

__ mailto:"Joe Smith" <jo...@fo...>
/tmp/foo.txt:: (ERROR/3) Anonymous hyperlink mismatch: 2 references but 
0 targets.
See "backrefs" attribute for IDs.

If i remove the spaces from the mailto URLs (bummer-- anyway to format 
mailtos as shown above??):

/tmp/foo.txt:5: (WARNING/2) Bullet list ends without a blank line; 
unexpected unindent.
/tmp/foo.txt:8: (WARNING/2) Bullet list ends without a blank line; 
unexpected unindent.

If I put a newline after each * line, the resulting HTML has each 
bullet in its own <ul></ul> block.  Why would the anonymous hyperlink 
cause that?  The anon link should be invisible to the structure of the 
doc, I would think.

Re: [Docutils-develop] DocArticle in sandbox

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

On Fri, Dec 27, 2002, Bill Bumgarner wrote:
>
> It is not complete;  there are a number of directives that it will 
> choke on, at this point.  I will fill in the implementations as I have 
> time [and the need].   Is there some test restructured text source that 
> exercises all required features?  That would be really helpful-- it 
> would allow sandbox developers to very quickly test to make sure their 
> writer is useful outside of the context that likely motivated the 
> development in the first place.

tools/test.txt

David, maybe this should go into test/ or at least spec/ so that it's
easier to find?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"I disrespectfully agree."  --SJM

[Docutils-develop] DocArticle in sandbox

[Bill B. <bb...@co...>]

The bbum sandbox now has the DocArticle writer.  It is, for all intents 
and purposes, a minimal, non-css, HTML writer that coincidentally spews 
HTML to the O'Reilly article spec.

It is not complete;  there are a number of directives that it will 
choke on, at this point.  I will fill in the implementations as I have 
time [and the need].   Is there some test restructured text source that 
exercises all required features?  That would be really helpful-- it 
would allow sandbox developers to very quickly test to make sure their 
writer is useful outside of the context that likely motivated the 
development in the first place.

b.bum

[Docutils-develop] HTML Acronyms

[Jason D. <ja...@in...>]

Hello.

I'm trying to add support to the html4css1 writer for acronyms. I want
interpreted text that matches a known set of acronyms to output an
<acronym> element instead of the default <span class="interpreted">
element it outputs now. For example, `reST` should output <acronym
title="reStructuredText">reST</acronym>.

I'm new to the docutils source code so was wondering what the best way
to do this would be. I thought I'd add an --acronyms-file option to the
writer, load the acronyms and their titles out of that file, and then
check to see if the text for an interpreted node was one of those known
acronyms. Is this an appropriate approach or should I be looking at
implementing it via a transform? This makes sense to me since the
acronym element I'm trying to output is specific to HTML.

Thanks,

-- 
Jason Diamond <ja...@in...>

[Docutils-develop] Italian language support files

[Nicola L. <ni...@te...>]

Please find, in tar.gz file attached to the patch #659080 on the SF project, 
the two "it.py" files needed to add Italian language support to Docutils.

"test_language.py it" runs fine after adding them.

Thanks for Docutils and reST!


-- 
"The browser wars won't be over until Mozilla stomps IE."
   Proudrooster on Slashdot

Nicola Larosa - ni...@te...

Re: [Docutils-develop] latex writer

[<gr...@us...>]

On Thu, 19 Dec 2002, Richard Jones wrote:

> On Thu, 19 Dec 2002 6:06 pm, gr...@us... wrote:
> > On Wed, 18 Dec 2002, Richard Jones wrote:
> > > 2. I'd like to be able to turn off the table of contents - it's not much
> > > use in most (if not all) of the pdfs generated for the Roundup
> > > documentation.
> >
> > you mean a switch --suppress-latex-toc ?

this was a wrong understanding on my side (i guess).

> That sounds good to me. Are you intending to provide page numbers in the LaTeX
> TOC at some stage?

option "--use-latex-toc 1"


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

Re: [Docutils-develop] emphasis/strong within literal_block?

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

[Benja Fallenstein]
>> IIRC parsed-literal is a directive, so,
>> 
>> .. parsed-literal::
>>    <something>

[Bill Bumgarner]
> Right. Got it.  That works great.
> 
> But it looks ugly-- it is the first intrusive formatting command I have
> had to include in the documents.   Feature request;  maybe if a
> paragraph ends in :;, the following block is a parsed literal as
> opposed to a literal block?

Adding ";;" as syntax is already a "to do?" item (search
<http://docutils.sf.net/spec/notes.html> for 'Syntax for the "line-block"
directive?').  ":;" is equivalent; I can see advantages and disadvantages.

Such syntax would be a minor enhancement (or wart, depending on tolerance
levels).  If you want it, a patch is the best way to get it.  Building
consensus is also required.  You've got to push for it.

> In general, I'm finding that basic docutils usage is straightforward
> and easy, but there is a HUGE learning curve between basic usage and
> advanced/competent/complete usage.  I.e. it took me quite a bit of
> experimentation to figure out how to control section levels.

Why is that?  Did you read the docs?  Which one(s) (primer, quickref, or
full ref)?  That's a very basic idea, and should be easily grasped.  If it
isn't (and if you *did* read at least one of the aforementioned docs), it
could be a doc bug.

>> IMHO that wouldn't be worth it-- I don't see this as something used by
>> many users, and it is hackish anyway, because it messes up the
>> alignment of lines-- if I write a UML diagram as ASCII art, I'd have
>> to write:
>> 
>> +---------+
>> | *MyClass* |
>> +---------+
>> 
>> to put the "MyClass" in italics (at least, as far as I understand
>> parsed-literal I have to) for showing that it is an abstract class.
>> Also, I may have to escape asterisks etc. in the code. So, I don't
>> think it is generally useful enough to warrant its own syntax...
> 
> I'm not sure I understand that line of reasoning.  Your example-- bold
> text in ASCII art-- isn't currently possible if I understand things
> correctly (big if, still)?

Sure it is possible.  That's the whole point of the parsed-literal
directive::

    .. parsed-literal::

       +---------+
       | *MyClass* |
       +---------+

One way to get around the fact that markup characters disappear would be to
use backslash-escapes in the other lines::

    .. parsed-literal::

       +-\-------\-+
       | *MyClass* |
       +-\-------\-+

Looks awful though.

> A specific example: In the article I'm writing, I have examples of
> working with an interactive interpreter.  I want the output of the
> interpreter to be italicized, but-- outside of that-- I want the rest
> of it to be treated as a /pre/ block:

I guess you've got that backwards.  In your example, the user input is
marked up as emphasized, but everything else (interpreter output, prompts,
etc.) is not.

> The request for ':;' was explicitly because it will not require any
> changes [that I can think of] to existing REST source.  Specifically,
> it will not require escaping * characters unless you explicitly request
> a parsed-literal block.

I'm not following you.  Please explain.

> It is merely a slight chunk of easily ignored syntactic sugar to give a
> hint to the docutils engine-- like the use of _, ``, ::, etc...

It's a syntax addition, no more or less than any other.  The question is
this: is the added functionality worth the cost of added syntax complexity?

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] emphasis/strong within literal_block?

[Bill B. <bb...@co...>]

On Tuesday, Dec 24, 2002, at 16:10 US/Eastern, Aahz wrote:
> On Mon, Dec 23, 2002, Bill Bumgarner wrote:
>> I have successfully modified aahz's OOwriter to produce HTML compliant
>> with O'Reilly's article spec.  The end result is a writer that-- while
>> not yet feature complete-- produces a minimal, non-CSS, HTML
>> representation of REST input.  In my opinion, it also provides a
>> relatively straightforward example of how to create a writer.
> Cool!  I've been bad-mouthing my own code, but if someone else was able
> to use it, I'm glad I uploaded it after all.

It is far from complete, but the generic HTML writer is useful now [at 
least to me].  It can do footnotes, handles literal and parsed-literal 
blocks, table of contents, links, basic formatting stuff, text (of 
course), sections, a handful of fields, and is becoming easier and 
easier to extend.

At this point, it is a combination of Aahz's code and the original 
html4css.py writer.   Somewhere along the way, I blew up settings and 
eliminated them-- I need to get the article done someday soon!-- but 
they should be easy to restore.

Writing generic HTML has driven home exactly how painful HTML truly is. 
  Namely, there are times where <p>, <br /> and nothing at all can imply 
a paragraph and using the wrong one can lead to extra ugly whitespace.  
  That was fun to work around.

I would really like to refactor the footnote code as it is currently 
spewing a whole slew of tables as opposed to a single table.

No CSS anywhere, but the output is fairly reasonable.   Good enough for 
my purposes anyway.  As soon as I have commit rights into the sandbox, 
I'll create a bbum directory and commit the module along w/a simple 
setup.py [my sf account is bbum, btw].

I'm seriously looking forward to getting feedback on the code from 
those that actually know what they are doing because I'm largely 
pecking in the dark, at this point.

b.bum

Re: [Docutils-develop] emphasis/strong within literal_block?

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

On Mon, Dec 23, 2002, Bill Bumgarner wrote:
> 
> I have successfully modified aahz's OOwriter to produce HTML compliant 
> with O'Reilly's article spec.  The end result is a writer that-- while 
> not yet feature complete-- produces a minimal, non-CSS, HTML 
> representation of REST input.  In my opinion, it also provides a 
> relatively straightforward example of how to create a writer.

Cool!  I've been bad-mouthing my own code, but if someone else was able
to use it, I'm glad I uploaded it after all.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"I disrespectfully agree."  --SJM

Re: [Docutils-develop] emphasis/strong within literal_block?

[Bill B. <bb...@co...>]

On Tuesday, Dec 24, 2002, at 15:32 US/Eastern, Benja Fallenstein wrote:
> IMHO that wouldn't be worth it-- I don't see this as something used by 
> many users, and it is hackish anyway, because it messes up the 
> alignment of lines-- if I write a UML diagram as ASCII art, I'd have 
> to write:
>
> +---------+
> | *MyClass* |
> +---------+
>
> to put the "MyClass" in italics (at least, as far as I understand 
> parsed-literal I have to) for showing that it is an abstract class. 
> Also, I may have to escape asterisks etc. in the code. So, I don't 
> think it is generally useful enough to warrant its own syntax...

I'm not sure I understand that line of reasoning.  Your example-- bold 
text in ASCII art-- isn't currently possible if I understand things 
correctly (big if, still)?

A specific example: In the article I'm writing, I have examples of 
working with an interactive interpreter.  I want the output of the 
interpreter to be italicized, but-- outside of that-- I want the rest 
of it to be treated as a /pre/ block:

-- excerpt -- 

For example:

.. parsed-literal::
     % *python*
     Python 2.2 (#1, 07/14/02, 23:25:09)
     [GCC Apple cpp-precomp 6.14] on darwin
     Type "help", "copyright", "credits" or "license" for more 
information.
     >>> *from foo import bar*
     >>> *print "foobar"*
     foobar

-- end excerpt -- 

I'd rather simply have the 'For example:' be 'For example:;' (as 
opposed to the normal 'For example::').

The request for ':;' was explicitly because it will not require any 
changes [that I can think of] to existing REST source.  Specifically, 
it will not require escaping * characters unless you explicitly request 
a parsed-literal block.

It is merely a slight chunk of easily ignored syntactic sugar to give a 
hint to the docutils engine-- like the use of _, ``, ::, etc...

b.bum

Re: [Docutils-develop] emphasis/strong within literal_block?

[Benja F. <b.f...@gm...>]

Hi Bill--

Bill Bumgarner wrote:

> On Tuesday, Dec 24, 2002, at 08:42 US/Eastern, Benja Fallenstein wrote:
>
>> Hiya,
>>
>> Bill Bumgarner wrote:
>>
>>> I understand that :: basically leads to a literal block, but I don't 
>>> see anything that causes a parsed-literal to be used instead?
>>
>> IIRC parsed-literal is a directive, so,
>>
>> .. parsed-literal::
>> <something>
>>
>> (where the 'something' is indented, in case my stupid mailer messes 
>> that up again :-( )
>
>
> Right. Got it. That works great.
>
> But it looks ugly-- it is the first intrusive formatting command I 
> have had to include in the documents. Feature request; maybe if a 
> paragraph ends in :;, the following block is a parsed literal as 
> opposed to a literal block?


IMHO that wouldn't be worth it-- I don't see this as something used by 
many users, and it is hackish anyway, because it messes up the alignment 
of lines-- if I write a UML diagram as ASCII art, I'd have to write:

+---------+
| *MyClass* |
+---------+

to put the "MyClass" in italics (at least, as far as I understand 
parsed-literal I have to) for showing that it is an abstract class. 
Also, I may have to escape asterisks etc. in the code. So, I don't think 
it is generally useful enough to warrant its own syntax...

Just my two cents, of course.
- Benja

Re: [Docutils-develop] emphasis/strong within literal_block?

[Bill B. <bb...@co...>]

On Tuesday, Dec 24, 2002, at 08:42 US/Eastern, Benja Fallenstein wrote:
> Hiya,
>
> Bill Bumgarner wrote:
>
>> I understand that :: basically leads to a literal block, but I don't 
>> see anything that causes a parsed-literal to be used instead?
> IIRC parsed-literal is a directive, so,
>
> .. parsed-literal::
> <something>
>
> (where the 'something' is indented, in case my stupid mailer messes 
> that up again :-( )

Right. Got it.  That works great.

But it looks ugly-- it is the first intrusive formatting command I have 
had to include in the documents.   Feature request;  maybe if a 
paragraph ends in :;, the following block is a parsed literal as 
opposed to a literal block?

In general, I'm finding that basic docutils usage is straightforward 
and easy, but there is a HUGE learning curve between basic usage and 
advanced/competent/complete usage.  I.e. it took me quite a bit of 
experimentation to figure out how to control section levels.

This is not a complaint or criticism-- docutils is at 0.2 and is 
already of a quality to be both useful and approachable (the ROI is 
good)-- just a comment.   (Heck, PyObjC is in its 7th year of 
development, is at version 0.8, and *still* doesn't have real docs... 
:-)

The generic/simple HTML parser is now actually useful -- i.e. I'm 
actually using it to write O'Reilly articles in the format they require 
and it is considerably faster than using Word, less tedious than 
writing raw HTML, and a heck of a lot more presentable than doing 
straight unformatted text.

b.bum

Re: [Docutils-develop] emphasis/strong within literal_block?

[Benja F. <b.f...@gm...>]

Hiya,

Bill Bumgarner wrote:

> I understand that :: basically leads to a literal block, but I don't 
> see anything that causes a parsed-literal to be used instead?


IIRC parsed-literal is a directive, so,

.. parsed-literal::
<something>

(where the 'something' is indented, in case my stupid mailer messes that 
up again :-( )
- Benja

Re: [Docutils-develop] emphasis/strong within literal_block?

[Bill B. <bb...@co...>]

On Tuesday, Dec 24, 2002, at 00:21 US/Eastern, David Goodger wrote:
> Are you sure about that?  <code> is an inline HTML element (like 
> <em>), and
> <pre> is a block/body-level element (like <p>).  How does O'Reilly use 
> them?
> The html4css1 writer produces <pre> for literal blocks and <tt> for 
> ``inline
> literals``.  I chose <tt> because it's neutral and generic, whereas 
> <code>
> is more specific.  It would be easy to use <code> instead of <tt> if
> required.

That'd make sense-- the spec really doesn't specify usage by example.   
Since I haven't actually immersed myself in tag definitions in a while, 
I decided to do a bit of research:

http://www.abiglime.com/webmaster/reference/html/tags/code.htm
http://www.abiglime.com/webmaster/reference/html/tags/pre.htm
http://werbach.com/barebones/barebones.html
http://developer.netscape.com/docs/manuals/htmlguid/alphlist.htm

So-- as David kindly indicated-- <code></code> is used inline whereas 
<pre></pre> is used to mark the preformatted nature of large chunks of 
text.   Makes sense and also makes sense in the context of an article-- 
use /code/ to delineate an inline example and /pre/ to show off a big 
chunk of text.  (Making up abbreviations on the fly here-- /code/ seems 
like a nice way to abbreviate <code></code>).

I understand that :: basically leads to a literal block, but I don't 
see anything that causes a parsed-literal to be used instead?

Confused, but less so....

b.bum

Re: [Docutils-develop] emphasis/strong within literal_block?

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

Bill Bumgarner wrote:
> I have successfully modified aahz's OOwriter to produce HTML compliant
> with O'Reilly's article spec.  The end result is a writer that-- while
> not yet feature complete-- produces a minimal, non-CSS, HTML
> representation of REST input.  In my opinion, it also provides a
> relatively straightforward example of how to create a writer.
> 
> If anyone is interested, ping me and I'll forward along a copy of what
> I have now.

Yes please.  Let me know your SF user name and I'll add you as a developer
too.

> (1) what about support for <code></code> blocks.  O'Reilly likes 'em in
> about as much as they like <pre>.

Are you sure about that?  <code> is an inline HTML element (like <em>), and
<pre> is a block/body-level element (like <p>).  How does O'Reilly use them?
The html4css1 writer produces <pre> for literal blocks and <tt> for ``inline
literals``.  I chose <tt> because it's neutral and generic, whereas <code>
is more specific.  It would be easy to use <code> instead of <tt> if
required.

> (2) within <pre></pre> blocks, things like <i></i> and <b></b> work
> fine.   How hard would it be to modify the existing literal block to
> allow for additional markup via said formatting tags (or am I barking
> up the wrong tree, here)?

Check out the "parsed-literal" directive; it does what you're describing.
For many examples, see the "Content Model" subsubsections of
<http://docutils.sf.net/spec/doctree.html>.

> I haven't though this stuff through outside of generating HTML for
> O'Reilly.  That is, generating output for other targets may change the
> requirements/thinking????

A writer producing truly generic HTML, that doesn't rely on CSS, would be a
useful addition to the project as an alternate HTML writer.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] emphasis/strong within literal_block?

[Richard J. <rj...@ek...>]

On Tue, 24 Dec 2002 11:53 am, Bill Bumgarner wrote:
> I have successfully modified aahz's OOwriter to produce HTML compliant
> with O'Reilly's article spec.  The end result is a writer that-- while
> not yet feature complete-- produces a minimal, non-CSS, HTML
> representation of REST input.  In my opinion, it also provides a
> relatively straightforward example of how to create a writer.
> [snip]
> (I'd be happy to maintain a sandbox directory, if warranted)

Please check the code into the sandbox, even if you're not sure you'll have 
time to maintain it. At least it's out in the open then!


    Richard

[Docutils-develop] emphasis/strong within literal_block?

[Bill B. <bb...@co...>]

I have successfully modified aahz's OOwriter to produce HTML compliant 
with O'Reilly's article spec.  The end result is a writer that-- while 
not yet feature complete-- produces a minimal, non-CSS, HTML 
representation of REST input.  In my opinion, it also provides a 
relatively straightforward example of how to create a writer.

If anyone is interested, ping me and I'll forward along a copy of what 
I have now.  Impatience, Laziness and Hubris are the motivating 
factors-- i.e. it'll likely not spew a correct document for your source 
because of unknown blocks-- but, given that its focus is on minimalism, 
it should be easy to fix.

(I'd be happy to maintain a sandbox directory, if warranted)

Questions:

(1) what about support for <code></code> blocks.  O'Reilly likes 'em in 
about as much as they like <pre>.  I haven't thought through why I 
would like one over the other, but it would be nice [in my imagination] 
to generate both.

(2) within <pre></pre> blocks, things like <i></i> and <b></b> work 
fine.   How hard would it be to modify the existing literal block to 
allow for additional markup via said formatting tags (or am I barking 
up the wrong tree, here)?   In my case, I want to be show a sample 
session with the Python interpreter and I want to format the output of 
the interpreter (or the input, can't decide which yet) with slightly 
different-- italics, bold, etc...

I haven't though this stuff through outside of generating HTML for 
O'Reilly.  That is, generating output for other targets may change the 
requirements/thinking????

(Cool stuff -- the raw article is totally easy to read/edit and the 
HTML markup is perfect!)

b.bum

[Docutils-develop] NEW STOCK PICK: TWLO - AMCG WENT UP 461%..................................................................................................................................................................................... ltp

[WALL S. B. ..4. <Sub...@ao...>]

<html>
<head>
</head>
<body>
<p align="center"><font style="font-size: 11pt" face="Courier">Did you miss out on AMCG, UP 461%?</font></p>
<p align="center"><font style="font-size: 11pt" face="Courier">Here's another pick - Another SHORT PLAY</font></p>
<p align="center"><b><a href="http://www.tristarzeus.com/103816/wall_street_bulletin.htm">CLICK HERE</a></b></p>
<p align="center"><img border="0" src="http://www.tristarzeus.com/103816/stopwatch01.gif"></p>
<p align="left">&nbsp;</p>
<p align="left">&nbsp;</p>
<p align="center"><font size="2"><A href="http://www.tristarzeus.com/remove/cstremove.htm">Click here to unsubscribe</A>
</body>
</html>

ybxtorfovngqxjyrybxta

Re: [Docutils-develop] Minimal writer?

[Bill B. <bb...@co...>]

Oh, that's perfect!

Cool!

Thanks you!

Now I can justify actually writing a mimimal HTML spewer as I write an 
article for O'Reilly....

I'll post it back to the list once it is useful.   Maybe someday, I'll 
ask for a sandbox, but the last thing I need in my life is 
yet-another-cvs-repository to which I feel obligated to commit on a 
regular basis.

b.bum

Re: [Docutils-develop] Minimal writer?

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

On Fri, Dec 20, 2002, Bill Bumgarner wrote:
>
> Is there a minimal writer example available?

Not exactly, but I think you'll find my OOwriter in sandbox/aahz/ to be
fairly close.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"To me vi is Zen.  To use vi is to practice zen.  Every command is a
koan.  Profound to the user, unintelligible to the uninitiated.  You
discover truth everytime you use it."  --re...@li...