docutils-develop — For developer discussions of the implementation.

Re: [Docutils-develop] reST.php?

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

Dethe Elza wrote:
> Also, if we parse directly to a DOM it makes reST more flexible and
> easier to port, since a DOM binding exists for most languages.  Many
> DOMs use either SAX or Expat to build the DOM itself, my idea would
> be to replace the low-level parser with reST.

I don't see how that would improve flexibility.  The parser can
already build a real DOM tree; just call ``document.asdom()``.  What
benefits would a DOM approach provide?  I'm not being defensive; I'd
really like to know.  If there is a benefit that outweighs the cost,
it should be explored.

> Building up a true XML DOM internally has several advantages.  More
> potential developers would be familiar with the API than are
> currently comfortable with the reST internals.

I don't think the document tree is the bottleneck.  Rather, I think
it's the complexity of the parser.  Unfortunately, parsing
reStructuredText *is* complex, because it has to grok two-dimensional
patterns that humans understand implicitly.  It's the curse of
user-friendliness. ;-)

> Writers could be written in XSLT without knowing anything about reST
> besides it's DTD.

This can already be done: just use ``document.asdom()`` then run that
through the XSLT engine.  The reason we don't go that route is because
there is no XSLT engine in core Python.  If PyXML is ever incorporated
into the core, we can re-examine that decision.

> And my *other* project of converting existing HTML and DocBook
> documents into reST for maintenance would be that much easier!

I don't follow this at all.  Can you elaborate?

> Even further off-topic, the docs mention that reST has constructs
> which are missing from DocBook.  What are they?

There are plenty.  Off the top of my head: field lists, option lists,
decorations (headers & footers), doctest blocks, line blocks,
transitions.  None of these are difficult to render or approximate
using regular DocBook elements, it's just that there's no one-to-one
correspondence.  Even in elements where there *is* a strong
correspondence, some are not completely compatible, such as definition
lists.  It is the goal of http://docutils.sf.net/spec/doctree.html to
document all of this; any assistance would be gratefully accepted and
much appreciated.

The Docutils document model was designed by me (with much input, of
course), as it makes sense to me.  I've had some experience with
various models, including DocBook and TEI, and I've designed several
DTDs before.  Every document designer has different sensibilities, so
differences and incompatibilies are inevitable.  For example, I know
of no DTD that has the equivalent of a "transition" element, although
they're quite common in novels and articles.

-- 
David Goodger  <go...@us...>  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] reST.php?

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

Axel,

Richard Jones gave the answers I would have given to your questions
(thanks Richard!).  I have a question for you.  Please note, I know
nothing about PHP.

Before you invest the considerable time and effort [*]_ into porting
the reStructuredText parser (and relevant parts of the rest of
Docutils), can't you simply install Python and Docutils in parallel
and call it from your PHP code?  If that proved to be a great success,
then the porting effort may prove worthwhile.

If you do choose to port it, I wish you success.  I'll be happy to
help in any way I can.  I really mean that, not least because most
requests for assistance inevitably make their way back into the
Docutils code or docs.

.. [*] At least you'll have the benefit of working from an existing
   implementation with a mature spec and the bugs worked out!

-- 
David Goodger  <go...@us...>  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] reST.php?

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

On Fri, 20 Sep 2002 8:17 pm, Axel Kollmorgen wrote:
> i'm a contributor to drupal ( http://drupal.org ), a php content
> management/discussion engine. me and some others there quite like rST,
> and we are currently discussing ( http://drupal.org/node.php?id=507#649
> ,
> http://drupal.org/node.php?title=Structured+Text+-+filter+enhancement )
> the use of (re)StructuredText for submitting (and maybe storing) content
> to the system. hence my questions:

Sounds like a fine idea.


> - does a php port of (re)StructuredText exists?

No.


> - does a php port of something similar to (re)StructuredText exists
> (aside of http://www.keithdevens.com/software/ , StructuredText Markup)?

*shrug*


> - does any other language port of rST or similar exists?

No. There should be :)


> - as there is probably none of above: do you think it is possible to
> port rST to php? more specifically:
>   . is there any general experience in porting python to php?

I'm sure there's some out there, you just need to find it :) Seriously, I've 
never seen any conversion information between the two. I've seen some 
skin-deep comparisons, and they look similar - on the surface, PHP is Python 
with added punctuation ... "and bugs" according to our PHP developer :)


>   . how much of / which parts of the docutils distribution would be
> required to port for basic functionality, i.e. for rendering html? how
> much for more functionality including xml-storage?

Fortunately, the design of the docutils project is quite clean and organised, 
and you can see how it all works at:

   http://docutils.sourceforge.net/#specification

See PEP 258 for a description of the processing framework itself. That works 
along the basic lines of:

1. read from a source document, parsing the structure out of it and creating a
   DOM tree (http://docutils.sourceforge.net/spec/doctree.html)
2. optionally do some transforms on the tree (NOOP for current ReST reader)
3. pass the DOM to a writer, in this case HTML
4. perform any HTML-specific DOM transforms (insert system messages, turn
   references into hyperlinks, handle footnotes, ...)
5. turn the DOM into HTML


>   . is there any developer documentation about the code structure /
> class hierarchies / ... beside
> http://docutils.sourceforge.net/#docutils-internals , the code and the
> devel-mailing list?

See the above specification link. At a minimum, you could just implement a 
parser for ReST and your own framework for generating the HTML. If that's the 
case, you just need the ReST format specification:

    http://docutils.sourceforge.net/spec/rst/reStructuredText.html

Hope this helps :)



        Richard

[Docutils-develop] reST include update

[Dethe E. <de...@en...>]

Hi folks,

Sorry for the delay.  In the past few weeks we've completed the 
acquisition of my company by a larger company, started to merge the two 
(which has involved changing all computer systems, among other things), 
my mom has immigrated to Canada and we've gotten her settled in, my 
daughter started first grade, and my wife had a multiple-of-five 
birthday.

However, I have finally gotten my sandbox build on SourceForge and in 
it is a copy of parsers/rst/directives/__init__.py which I believe 
approximates the parse_directive function that we've discussed here.  
Please feel free to look at it and suggest improvements and point out 
problems.

Next I'm going to reimplement the include and raw directives using the 
new function.  I'll then add examples to the HOWTO, along with Aahz's 
corrections (thanks, Aahz!).

--Dethe

Re: [Docutils-develop] reST.php?

[Dethe E. <de...@ma...>]

I'd love to see this.  Projects such as porting reST to PHP (or=20
whatever) are part
of why I was asking about rigorous specs in the form of EBNF syntax, to=20=

make
it more portable.

Also, if we parse directly to a DOM it makes reST more flexible and=20
easier
to port, since a DOM binding exists for most languages.  Many DOMs use
either SAX or Expat to build the DOM itself, my idea would be to replace
the low-level parser with reST.  I understand that David doesn't want=20
to give
up the simplicity of the node constructors for the verbosity of DOM=20
calls, but
node.py could be reimplemented as convenience functions to make the DOM
calls for you.

Building up a true XML DOM internally has several advantages.  More=20
potential
developers would be familiar with the API than are currently=20
comfortable with
the reST internals.  Writers could be written in XSLT without knowing=20
anything
about reST besides it's DTD.  And my *other* project of converting=20
existing HTML and DocBook documents into reST for maintenance would be=20=

that much easier!

Even further off-topic, the docs mention that reST has constructs which=20=

are missing from DocBook.  What are they?

--Dethe

On Friday, September 20, 2002, at 03:17 AM, Axel Kollmorgen wrote:

> hi all,
>
> i'm a contributor to drupal ( http://drupal.org ), a php content
> management/discussion engine. me and some others there quite like rST,
> and we are currently discussing ( =
http://drupal.org/node.php?id=3D507#649
> ,
> http://drupal.org/node.php?title=3DStructured+Text+-+filter+enhancement =
)
> the use of (re)StructuredText for submitting (and maybe storing)=20
> content
> to the system. hence my questions:
>
> - does a php port of (re)StructuredText exists?
> - does a php port of something similar to (re)StructuredText exists
> (aside of http://www.keithdevens.com/software/ , StructuredText=20
> Markup)?
> - does any other language port of rST or similar exists?
> - as there is probably none of above: do you think it is possible to
> port rST to php? more specifically:
>   . is there any general experience in porting python to php?
>   . how much of / which parts of the docutils distribution would be
> required to port for basic functionality, i.e. for rendering html? how
> much for more functionality including xml-storage?
>   . is there any developer documentation about the code structure /
> class hierarchies / ... beside
> http://docutils.sourceforge.net/#docutils-internals , the code and the
> devel-mailing list?
>
> looking forward for your feedback. tia.
>
> --=99
> ax
>
> "Jeder will alt werden, aber keiner will es sein." (Martin Held, dt.
> Schauspieler)
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by:ThinkGeek
> Welcome to geek heaven.
> http://thinkgeek.com/sf
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop

[Docutils-develop] reST.php?

[Axel K. <ax...@co...>]

hi all,

i'm a contributor to drupal ( http://drupal.org ), a php content
management/discussion engine. me and some others there quite like rST,
and we are currently discussing ( http://drupal.org/node.php?id=3D507#649
,
http://drupal.org/node.php?title=3DStructured+Text+-+filter+enhancement )
the use of (re)StructuredText for submitting (and maybe storing) content
to the system. hence my questions:

- does a php port of (re)StructuredText exists?
- does a php port of something similar to (re)StructuredText exists
(aside of http://www.keithdevens.com/software/ , StructuredText Markup)?
- does any other language port of rST or similar exists?
- as there is probably none of above: do you think it is possible to
port rST to php? more specifically:
  . is there any general experience in porting python to php?
  . how much of / which parts of the docutils distribution would be
required to port for basic functionality, i.e. for rendering html? how
much for more functionality including xml-storage?
  . is there any developer documentation about the code structure /
class hierarchies / ... beside
http://docutils.sourceforge.net/#docutils-internals , the code and the
devel-mailing list?

looking forward for your feedback. tia.

--=81
ax

"Jeder will alt werden, aber keiner will es sein." (Martin Held, dt.
Schauspieler)

Re: [Docutils-develop] Functionnal LaTeX writer

[Julien T. L. <me...@fr...>]

Hi list,
Hi Engelbert,

> * what is your input ?

The Docutils README.txt.
But I'm going to try it with test.txt, as suggested ;)

> * how does your style.tex look like ?

It just sets a few lengths. It was supposed (as you probably guessed) to be
used as the equivalent of a CSS.

> my article class does not support subtitle ?
> """
> Document
> ========
>
> and this
> --------
> """
> tries to put subtitle{and this}

I don't know about this construct... But I'll try to solve the problem.

> * why did verbatim not work for you.

Because of encode(): since all of the text inside nodes finally gets
encode()d, I had to encode underscores, ampersands, etc., which get
interpreted as erroneous math-mode characters by TeX.

But then, if I use verbatim, stuff like {\_} appear in the output (of course);
the \obeylines\obeyspaces substitute seemed to work fairly well, and I
couldn't think of a better solution...

I'm improving latex2e.py a lot today; I want it to transform tools/test.txt
about correctly. I'll post the new version once I'm done :)

Cheers,
-- 
Julien T. Letessier     email: co...@me...
ENSIMAG Student         web: http://www.mezis.net

Re: [Docutils-develop] Functionnal LaTeX writer

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

Julien T. Letessier wrote:
> I decided that I loved reST a few days ago, and that I'd love it
> even more if it could output LaTeX. So I found this preliminary
> LaTeX writer file in Engelbert Gruber's sandbox directory, and I
> improved it (that is, made it a bit more functionnal).

Julien, merci!

Engelbert, are you planning on continuing development of the LaTeX
writer or the PDF writer in the near future?  Or would it be OK if
Julien or someone else took over?

Engelbert and Julien, would either or both of you be willing to
complete the writer?  "Complete" doesn't mean it has to be perfect,
just that it handles all Docutils constructs, as the current
html4css1.py does.  Once complete, I'd like to put it into the main
source tree.  Try running it over tools/test.txt to see where the
issues are.

I've been maintaining the HTML writer.  Once the LaTeX writer is in
place, it will be maintained as well, hopefully with the assistance of
people with more TeX knowledge than I.

A technical issue: please don't use hard tabs in the source files.
Use 4 spaces per indent level instead.  See:

    http://docutils.sf.net/spec/notes#coding-conventions

> I don't know if this fits somewhere in your developement process,

The process is loose and flexible.  For details of the development
process as it stands, please read:

    http://docutils.sf.net/spec/notes#project-policies

> Tell me if you find it useful ;)

I'm sure some people will.  With more format writers, Docutils will
become more useful, and its audience will become broader.

-- 
David Goodger  <go...@us...>  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: Relax the 4-character minimum on section title underlines?

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

I have removed the 4-character minimum requirement for section title
underlines and overlines.  The following section titles will now
process as expected::

    ABC
    ===

    ---
    DEF
    ---

The original reason for the minimum was to avoid misinterpretation of
common punctuation constructs, such as ellipsis ("...") and m-dash
("---").  The parser now allows for such constructs where they may
otherwise be misinterpreted as title adornments.  For example, all of
the following will parse as ordinary paragraphs::

    This is not a title
    ...

    ...
    nor is this

    Or this
    ---

Level-1/INFO system messages are inserted wherever there's any
question.  Normally, level-1/INFO messages are not visible; to see
them, use the --verbose, -v, or --report-level=info options.

There is still one limitaton.  A two-period overlined title is not
possible, because it will be parsed as a comment start.  The text
immediately following will generate a warning because there's no
intervening blank line::

    ..
    Hi
    ..

Extending the over/underlines to 3 characters makes it work::

    ...
    Hi
    ...

A two-period *underline* has no problem though::

    Hi
    ..

In other recent news:

* A subtle bug that introduced unwanted empty rows in some "simple"
  tables has been fixed.

* The locale-setting code in front ends has been made fault-tolerant.

* The definition of "simple reference names" has been altered
  slightly: internal hyphens, periods, and underscores may only occur
  one at a time, not two or more adjacent.  This prevents text like
  "object.__method__" from being parsed as a reference (because of the
  trailing underscores).  If any such text *does* exist, it can always
  be quoted like this::

    reference to `object.__method__`_

The CVS snapshot is always up to date and available at:

    http://docutils.sf.net/docutils-snapshot.tgz

-- 
David Goodger  <go...@us...>  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] Functionnal LaTeX writer

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

On Thu, 19 Sep 2002, Julien T. Letessier wrote:

> Hi list,
>
> I decided that I loved reST a few days ago, and that I'd love it even
> more if it could output LaTeX. So I found this preliminary LaTeX
> writer file in Engelbert Gruber's sandbox directory, and I improved it (that
> is, made it a bit more functionnal).
>
> I don't know if this fits somewhere in your developement process, but anyways,
> here's my current version of the thing. I'm using it against my daily docutils
> CVS checkout.
>
> Tell me if you find it useful ;)

of course.

* what is your input ?
* how does your style.tex look like ?

my article class does not support subtitle ?
"""
Document
========

and this
--------
"""
tries to put subtitle{and this}

* why did verbatim not work for you.

sorry the server did not respond.

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

[Docutils-develop] Functionnal LaTeX writer

[Julien T. L. <me...@fr...>]

Hi list,

I decided that I loved reST a few days ago, and that I'd love it even
more if it could output LaTeX. So I found this preliminary LaTeX
writer file in Engelbert Gruber's sandbox directory, and I improved it (that
is, made it a bit more functionnal).

I don't know if this fits somewhere in your developement process, but anyways,
here's my current version of the thing. I'm using it against my daily docutils
CVS checkout.

Tell me if you find it useful ;)

Cheers,
-- 
Julien T. Letessier     email: co...@me...
ENSIMAG Student         web: http://www.mezis.net

Re: [Docutils-develop] Directives Howto (in progress)

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

On Thu, Aug 29, 2002, Dethe Elza wrote:
> 
> Define Directive
> ----------------
> 
> The directive signature itself should follow this template:

Shouldn't that be "template::"?

Also, you should explain that a directive is a plain function (a
callback), not a method.

>     def my_directive(match, type_name, data, state, state_machine, option_presets):

Reformat to shorter lines?

> Define Options
> --------------
> 
> You will have to define the options your directive requires.  This is a
> dictionary of name, conversion pairs which are applied to each option value to
> convert it to an expected type.  Python's built-in conversion are often usable
> for this, for example, str, int, float.  Other useful types would be bool
> (included in python 1.3) and exists (to test for existence of an option when
> you don't care about the value or the option has no value).

Python 2.3, right?

Again shorter lines would be better, I think.

> Parse Directive
> ---------------
> 
> You'll want to use the parse_directive method, which has returns a 4-tuple
> (arguments, options, content, blank_finish) and has the following signature:

Method of what?  What does "use" mean?  (I.e., I believe the writer of a
directive doesn't actually call parse_directive(); parse_directive()
calls the my_directive() callback.  Whether I'm right or wrong, clarity
is needed.)

(Yes, examples will help, but the text should also be correct and
complete.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

[Docutils-develop] ANN: DocFactory wxPython app for Docutils

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

Gunnar Schwant has contributed DocFactory, a wxPython GUI application for
Docutils.  It is in the preliminary stages.  For details, please see

    http://docutils.sf.net/sandbox/gschwant/docfactory/README.html

I have begun a "To Do" list:

    http://docutils.sf.net/sandbox/gschwant/docfactory/NOTES.html

The code is available via CVS or snapshot:

    http://docutils.sf.net/docutils-sandbox-snapshot.tgz

Please try it out.  Feedback is welcome: bug reports, patches, feature
ideas, etc.

-- 
David Goodger  <go...@us...>  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] Relax the 4-character minimum on section title underlines?

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

I am considering relaxing the 4-character minimum requirement for
reStructuredText section title underlines, and would like to determine
the best course of action.  The spec states:

    An underline/overline is a single repeated punctuation character
    that begins in column 1 and forms a line extending at least as far
    as the right edge of the title text. ...  An underline/overline
    must be at least 4 characters long (to avoid mistaking ellipses
    ["..."] for overlines).

    (http://docutils.sf.net/spec/rst/reStructuredText.html#sections)

The 4-character minimum on transition markers will remain, regardless.

Sometimes a title is less than 4 characters long, and it's natural to
want to use an underline of exactly the same length.  I've noticed
such cases in others' documents, and in my own.  In my own document, I
used a 3-character underline; the title was parsed as an ordinary
paragraph and it took some time to discover the problem and fix it,
because the parser produced no warning.

Here's the current entry in the "Bugs" section of the "To Do" list:

    Section headers must have underlines at least 4 characters long.
    But when the section title is only 3 characters long, it's natural
    to underline with "===" (I just did).  The parser should produce a
    warning in such cases.

    Or should the parser simply recognize such short underlines?  A
    zero-tolerance policy might work: over/underlines of 3 or fewer
    characters which are shorter than the "title" text are not
    recognized as titles, and should generate an "info" message.

There has also been a bug report submitted on the issue (by Jeremy
Hylton):
http://sf.net/tracker/?func=detail&atid=422030&aid=608108&group_id=38414

There's no problem with the typical case, where the over/underlines
are at least as long as the title text::

    ABC
    ===
    
    ---
    DEF
    ---

But what to do when the over/underline is too short?  Ellipsis ("...")
and m-dash (commonly written "---") both use 3 repeated punctuation
characters; this ambiguity is what the 4-character minimum avoided.  For
example::

    Is This Supposed To Be A Title?
    ---

    This, surely, is not
    ...

In these cases, I'm thinking of inserting INFO (level 1) system
messages that say, "Possible title underline, too short for the title
text.  Treating it as ordinary text because it's so short."  INFO
system messages are not normally visible (shown only if the
-v/--verbose option is used).  In other words, short underlines (<= 3
characters) are recognized as title adornments if they're long enough
for the title text, but if they're too short they're just wrapped text
plus a normally-invisible system message.  I think this is the right
balance of precision (unambiguous, unsurprising) and "do what I say"
(intuitive).

How about these cases, of overlines?  Unless stated otherwise, the
short overlines would each be treated as ordinary text and an INFO
system message inserted::

    ...
    This is not a title; perhaps an excerpt from a quote.

    ..
    This is interpreted as a comment start immediately followed by a
    paragraph.  Triggers a "no blank line; unexpected unindent"
    warning.

    ==
    These lines would not be interpreted as a title.
    ==

    ---
    The three dashes above might represent an m-dash.

    ==
      Would this become a definition list?

    ==
      And what about this?  A definition list item followed by a
      paragraph and a "no blank line; unexpected unindent" warning.
    ==

And when section titles are not expected/allowed::

    Ordinary paragraph.

        This title should trigger a SEVERE error (sections not allowed
        inside block quotes), as currently happens with longer titles:

        ABC
        ===

        This title should trigger an INFO message and be treated as an
        ordinary paragraph, since the underline is too short for the
        title:
        
        ABC
        ==

Does all of this seem reasonable?  Any gotchas I'm missing?

-- 
David Goodger  <go...@us...>  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] Forcing line breaks

[Adam C. <ad...@ch...>]

On Sat, 07 Sep 2002 13:12:32 -0400 David Goodger
<go...@us...> wrote:

> > Definition lists do fit *conceptually*, but unfortunately not with
> > regard to presentation. When you specify contact information or
> > similar data, you almost always do it like this::
> > 
> >   Name:    Adam Chodorowski
> >   Address: The Street 42
> >            11111 The City
> >   Country: Sweden
> >   Phone:   +46-8-1111111
> 
> Actually, I would write it like this::
> 
>     Adam Chodorowski
>     The Street 42
>     11111 The City
>     Sweden
>     phone +46-8-1111111
> 
> Most of the labels are redundant; people know how to read addresses
> from context.

That's true, as long as you only have name and address I guess. But when you
start tacking on things like phone, mobile, email, ..., you have to prefix
them with something (atleast phone and mobile, I guess email would be clear
from the context :)).



> > Having definition lists is *not* intuitive for the reader
> ...
> > nobody excepts contact information to be presented that way.
> 
> I wouldn't expect contact information to be presented the "field list"
> way either.  Are conventions so different in Sweden?  Do you really
> need to label everything?  (But this is avoiding the real issue.)

Well, no, I guess we don't label addresses normally since everyone knows what
is what from the context. But when I also add phone number and such, I usually
put labels on everything (to be consistent).
 
[...]
> I'm beginning to like this change.  If we drop the notion of "field
> arguments", field lists become simpler and fully generic.  Then I'd
> drop my objection to their use as a generic document construct.  Any
> objections to this change?

No. :)

---
Adam Chodorowski <ad...@ch...>

Of course everyone knows that vim is the best text editor in the world.  
Anyone who tells you differently is either wrong, lying, or criminally 
insane.  (Or an emacs user, in which case they are wrong, lying and 
criminally insane).
    -- CmdrTaco / SlashDot

Re: [Docutils-develop] reST Includes

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

On Fri, Sep 13, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Well, suppose I've got the following Python code::
>> 
>>     print "Hello, world!"
>> 
>> I'm going to want to include both::
>> 
>>     print "Hello, world!"
>> 
>> and::
>> 
>>     Hello, world!
>> 
>> Thus, there needs to be a directive to *run* the Python code and
>> capture stdout (and/or stderr), probably as some kind of literal
>> block.
> 
> I see.  You want a directive that does the equivalent of
> ``os.system()``, and inserts the output into the document.  Hmmm.
> Seems dangerous to me, to embed system calls in a document.  Perhaps
> that should be left outside of the document, in the user's production
> system (a makefile or a script or whatever)?  Or, the directive could
> be disabled by default and only enabled with an explicit command-line
> option or config file setting.  Even then, an interactive prompt may
> be useful, such as:
> 
>     The file.txt document you are processing contains a "system"
>     directive requesting that the ``sudo rm -rf /`` command be
>     executed.  Allow it to execute?  (y/N)

Well, I wasn't expecting this to be a standard directive, I was just
explaining the context for wanting the Python code in a separate file.
If you want to add this as a standard directive, you've probably got the
correct approach.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Re: [Docutils-develop] reST Includes

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

On Sat, 14 Sep 2002 8:28 am, David Goodger wrote:
> I see.  You want a directive that does the equivalent of
> ``os.system()``, and inserts the output into the document.  Hmmm.
> Seems dangerous to me, to embed system calls in a document.  Perhaps
> that should be left outside of the document, in the user's production
> system (a makefile or a script or whatever)?  Or, the directive could
> be disabled by default and only enabled with an explicit command-line
> option or config file setting.  Even then, an interactive prompt may
> be useful, such as:
>
>     The file.txt document you are processing contains a "system"
>     directive requesting that the ``sudo rm -rf /`` command be
>     executed.  Allow it to execute?  (y/N)

I think that's a reasonable level of precaution.


    Richard

Re: [Docutils-develop] reST Includes

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

Aahz wrote:
> Well, suppose I've got the following Python code::
> 
>     print "Hello, world!"
> 
> I'm going to want to include both::
> 
>     print "Hello, world!"
> 
> and::
> 
>     Hello, world!
> 
> Thus, there needs to be a directive to *run* the Python code and
> capture stdout (and/or stderr), probably as some kind of literal
> block.

I see.  You want a directive that does the equivalent of
``os.system()``, and inserts the output into the document.  Hmmm.
Seems dangerous to me, to embed system calls in a document.  Perhaps
that should be left outside of the document, in the user's production
system (a makefile or a script or whatever)?  Or, the directive could
be disabled by default and only enabled with an explicit command-line
option or config file setting.  Even then, an interactive prompt may
be useful, such as:

    The file.txt document you are processing contains a "system"
    directive requesting that the ``sudo rm -rf /`` command be
    executed.  Allow it to execute?  (y/N)

-- 
David Goodger  <go...@us...>  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] reST Includes

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

On Thu, Sep 12, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> In all the discussion of include files, it's still not clear to me how
>> best to accomplish what I want: including a .py file as text.  I don't
>> want the text in the reST file because I'm going to use a *second*
>> include directive to get the output from the .py file.
> 
> I'm not sure I understand what you're saying.  By "including a .py file as
> text", do you mean that you want to insert a .py file into the document as a
> **literal block**?  I don't think that's part of the proposal Dethe is
> working on, but it seems useful and simple enough to do.  Something like::
> 
>     .. include:: example.py
>        :literal:
> 
> If that's not what you meant, please explain.

Yeah, I think that's what I meant, but I don't know reST well enough to
be certain.  ;-)

> And I don't follow the second sentence at all.  Perhaps an illustrative
> example?

Well, suppose I've got the following Python code::

    print "Hello, world!"

I'm going to want to include both::

    print "Hello, world!"

and::

    Hello, world!

Thus, there needs to be a directive to *run* the Python code and capture
stdout (and/or stderr), probably as some kind of literal block.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Re: [Docutils-develop] reST Includes

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

Aahz wrote:
> In all the discussion of include files, it's still not clear to me how
> best to accomplish what I want: including a .py file as text.  I don't
> want the text in the reST file because I'm going to use a *second*
> include directive to get the output from the .py file.

I'm not sure I understand what you're saying.  By "including a .py file as
text", do you mean that you want to insert a .py file into the document as a
**literal block**?  I don't think that's part of the proposal Dethe is
working on, but it seems useful and simple enough to do.  Something like::

    .. include:: example.py
       :literal:

If that's not what you meant, please explain.

And I don't follow the second sentence at all.  Perhaps an illustrative
example?

-- 
David Goodger  <go...@us...>  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] reST Includes

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

In all the discussion of include files, it's still not clear to me how
best to accomplish what I want: including a .py file as text.  I don't
want the text in the reST file because I'm going to use a *second*
include directive to get the output from the .py file.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Re: [Docutils-develop] Stylesheets quickie

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

On Thu, 12 Sep 2002 12:37 pm, David Goodger wrote:
> Richard Jones wrote:
> > Could the docutils html tool have an option to embed the stylesheet
> > please?  Much easier to distribute then...
>
> Sure it could.  What's stopping you? ;-)

Roundup. 0.5 release. Brain full :)


> But since it was an interesting request, and you asked so
> nicely... done.  We now have --embed-stylesheet and --link-stylesheet
> options; the default is to link.

Thanks ever so much :)


    Richard

Re: [Docutils-develop] Stylesheets quickie

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

Richard Jones wrote:
> Could the docutils html tool have an option to embed the stylesheet
> please?  Much easier to distribute then...

Sure it could.  What's stopping you? ;-)

But since it was an interesting request, and you asked so
nicely... done.  We now have --embed-stylesheet and --link-stylesheet
options; the default is to link.

-- 
David Goodger  <go...@us...>  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] Stylesheets quickie

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

Could the docutils html tool have an option to embed the stylesheet please? 
Much easier to distribute then...


   Richard

[Docutils-develop] Field arguments dropped (was Re: Forcing line breaks)

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

I wrote:
> Or perhaps we just drop the idea of field arguments altogether, and
> rely on the application code to parse the field name as it likes.

And now it's implemented.  Field lists are now freely usable as generic
document constructs.  Field names may have multiple words, although
restrictions may be imposed by (and the interpretation depends on)
application code.  Short form: field lists are more general-purpose now,
with no problems anticipated.

-- 
David Goodger  <go...@us...>  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/