docutils-develop Mailing List for Docutils: Documentation Utilities (Page 404)

somehow complete (for my reasons/usage overcomplete)

open issues
* blanks in line blocks
* more visible admonitions
* a latex error on centering the abstract title without
  visible effect, but annoying.

* the multirow/column problem: deferred

the tables are problematic anyway.
* tabularx (used for docinfo and option list) is only for
  single page tables.
* table width is always full page width:
  possibly to try: assume rst-pagewidth of 80 get tablewidth
  and make same ratio in latex.

cheers
-- 
 BINGO: change the basis of competition
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

On Friday 06 December 2002 9:47 pm, David Goodger wrote:
> Doug Hellmann wrote:
> >
> > Why perform all of those transformations?  Why not go from the AST
> > to a generic doctree?  Or, even from the AST to the final output?
>
> I want the docutils.readers.python.moduleparser.parse_module()
> function to produce a standard documentation-oriented AST that can be
> used by any tool.  We can develop it together without having to
> compromise on the rest of our design (i.e., HappyDoc doesn't have to
> be made to work like Docutils, and vice-versa).  It would be a
> higher-level version of what compiler.py provides.

That part makes sense.

> The Python reader component transforms this generic AST into a
> Python-specific doctree (it knows about modules, classes, functions,
> etc.), but this is specific to Docutils and cannot be used by HappyDoc
> or others.  The stylist transform does the final layout, converting
> Python-specific structures ("class" sections, etc.) into a generic
> doctree using primitives (tables, sections, lists, etc.).  This
> generic doctree does *not* know about Python structures any more.  The
> advantage is that this doctree can be handed off to any of the output
> writers to create any output format we like.

Ah.  I handled that differently in HappyDoc.  Instead of building another 
data structure, I set up the API for the formatters to have methods that do 
things like start/end a (sub)section, start/end a list, etc.  The primary 
implementation is an HTML formatter that produces tables, but there are other 
formatters.  The docset is then responsible for calling the right formatter 
method when it wants it.  Having the docset and formatter separate makes 
things more complicated than I expected, so in HappyDoc 3.0 there will just 
be one plugin system.  

There is a new scanner which walks the input directory building a tree of 
scanned files, doing optional special processing for each based on mimetype.  
For text/x-python files, the file is parsed and information about classes, 
etc. are extracted.  The output formatter walks the resulting tree, also 
doing mimetype-based processing for each file.  HTML and image files will be 
copied from input to output.  Text files are converted using the docstring 
converter, and the parse results from Python modules are used to generate new 
HTML output files.

I've got the scanner done, and am working on the output formatter code now. 

Doug

Doug Hellmann wrote:
> Does compiler include comments?  I had to write a separate parser to
> pull comments out.

As Michael said, no.  That's another reason for using compiler and
tokenize in parallel.

>> The Docutils Python reader component will transform this AST into a
>> Python-specific doctree, and then a `stylist transform`_ would
>> further transform it into a generic doctree.  Namespaces will have
>> to be compiled for each of the scopes, but I'm not certain at what
>> stage of processing.
> 
> Why perform all of those transformations?  Why not go from the AST
> to a generic doctree?  Or, even from the AST to the final output?

I want the docutils.readers.python.moduleparser.parse_module()
function to produce a standard documentation-oriented AST that can be
used by any tool.  We can develop it together without having to
compromise on the rest of our design (i.e., HappyDoc doesn't have to
be made to work like Docutils, and vice-versa).  It would be a
higher-level version of what compiler.py provides.

The Python reader component transforms this generic AST into a
Python-specific doctree (it knows about modules, classes, functions,
etc.), but this is specific to Docutils and cannot be used by HappyDoc
or others.  The stylist transform does the final layout, converting
Python-specific structures ("class" sections, etc.) into a generic
doctree using primitives (tables, sections, lists, etc.).  This
generic doctree does *not* know about Python structures any more.  The
advantage is that this doctree can be handed off to any of the output
writers to create any output format we like.

The latter two transforms are separate because I want to be able to
have multiple independent layout styles (multiple runtime-selectable
"stylist transforms").  Each of the existing tools (HappyDoc, pydoc,
epydoc, Crystal, etc.) has its own fixed format.  I personally don't
like the tables-based format produced by these tools, and I'd like to
be able to customize the format easily.  That's the goal of stylist
transforms, which are independent from the Reader component itself.
One stylist transform could produce HappyDoc-like output, another
could produce output similar to module docs in the Python library
reference manual, and so on.

It's for exactly this reason:

>> It's very important to keep all docstring processing out of this,
>> so that it's a completely generic and not tool-specific.

... but it goes past docstring processing.  It's also important to
keep style decisions and tool-specific data transforms out of this
module parser.

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

Doug Hellmann <do...@he...> writes:

> If you're starting from scratch, I would definitely recommend trying the 
> compiler module first.

Amen.

[...]
> Does compiler include comments? 

No.  tokenize.py does, though.

I don't know how hard it would be to turn the output of tokenize.py
into something like the output of compiler/transformer.py, but with
comments.  SPARK may be your friend...

Cheers,
M.

-- 
  Two things I learned for sure during a particularly intense acid
  trip in my own lost youth: (1) everything is a trivial special case
  of something else; and, (2) death is a bunch of blue spheres.
                                             -- Tim Peters, 1 May 1998

On Thursday 05 December 2002 9:45 pm, David Goodger wrote:
> Doug Hellmann wrote:
> > I'm pretty sure HappyDoc was written before the compiler module was
> > generally available
>
> I suspected as much.  Either that, or you're a glutton for punishment
> ;-)

Well, I didn't say that wasn't true.  :-)  I actually started with some 
sample code included in the Python source distribution, so it wasn't too hard 
to extend it and come up with a useful parser.

> > I've only had to make a few minor modifications to it in the past,
> > since the language syntax hasn't evolved that far.
>
> That's good to know.  Still, the parser.suite() approach seems a lot
> harder.

If you're starting from scratch, I would definitely recommend trying the 
compiler module first.

> > I'm working on a major overhaul of HappyDoc anyway, so now might be
> > the time to rewrite the parsing stuff to use the compiler module.
> > If you're interested in collaborating, let me know.
>
> I am, definitely.  What I'd like to do is to take a module, read in
> the text, run it through the module parser (using compiler.py and
> tokenize.py) and produce a high-level AST full of nodes that are
> interesting from an auto-documentation standpoint.  For example, given
> this module (x.py)::

[...]

> compiler.parse() provides most of what's needed for this AST.  I think
> that "tokenize" can be used to get the rest, and all that's left is to
> hunker down and figure out how.  We can determine the line number from
> the compiler.parse() AST, and a get_rhs(lineno) method would provide
> the rest.

Does compiler include comments?  I had to write a separate parser to pull 
comments out.

> The Docutils Python reader component will transform this AST into a
> Python-specific doctree, and then a `stylist transform`_ would further
> transform it into a generic doctree.  Namespaces will have to be
> compiled for each of the scopes, but I'm not certain at what stage of
> processing.

Why perform all of those transformations?  Why not go from the AST to a 
generic doctree?  Or, even from the AST to the final output?

> It's very important to keep all docstring processing out of this, so
> that it's a completely generic and not tool-specific.

Definitely.

Doug

Engelbert Gruber wrote:
> what is the intention:

The intention is to summarize the code and docstrings of Python
modules in order to auto-document the code.  Specifically, the
intention is to extract some pieces of raw source code (RHS of
assignments and default argument values, perhaps others) that don't
survive intact past compiler.parse().

See my reply to Doug Hellmann, and

    http://docutils.sf.net/pep-0258.html#python-source-reader

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

Doug Hellmann wrote:
> I'm pretty sure HappyDoc was written before the compiler module was
> generally available

I suspected as much.  Either that, or you're a glutton for punishment
;-)

> I've only had to make a few minor modifications to it in the past,
> since the language syntax hasn't evolved that far.

That's good to know.  Still, the parser.suite() approach seems a lot
harder.

> I'm working on a major overhaul of HappyDoc anyway, so now might be
> the time to rewrite the parsing stuff to use the compiler module.
> If you're interested in collaborating, let me know.

I am, definitely.  What I'd like to do is to take a module, read in
the text, run it through the module parser (using compiler.py and
tokenize.py) and produce a high-level AST full of nodes that are
interesting from an auto-documentation standpoint.  For example, given
this module (x.py)::

    # comment

    """Docstring"""

    """Additional docstring"""

    __docformat__ = 'reStructuredText'

    a = 1
    """Attribute docstring"""

    class C(Super):

        """C's docstring"""

        class_attribute = 1
        """class_attribute's docstring"""

        def __init__(self, text=None):
            """__init__'s docstring"""

            self.instance_attribute = (text * 7
                                       + ' whaddyaknow')
            """instance_attribute's docstring"""


    def f(x, y=a*5, *args):
        """f's docstring"""
        return [x + item for item in args]

    f.function_attribute = 1
    """f.function_attribute's docstring"""

The module parser should produce a high-level AST, something like this
(in pseudo-XML_)::

    <Module filename="x.py">
        <Comment lineno=1>
            comment
        <Docstring lineno=3>
            Docstring
        <Docstring lineno=...>           (I'll leave out the lineno's)
            Additional docstring
        <Attribute name="__docformat__">
            <Expression>
                'reStructuredText'
        <Attribute name="a">
            <Expression>
                1
            <Docstring>
                Attribute docstring
        <Class name="C" inheritance="Super">
            <Docstring>
                C's docstring
            <Attribute name="class_attribute">
                <Expression>
                    1
                <Docstring>
                    class_attribute's docstring
            <Method name="__init__" argnames=['self', ('text', 'None')]>
                <Docstring>
                    __init__'s docstring
                <Attribute name="instance_attribute" instance=True>
                    <Expression>
                        (text * 7
                         + ' whaddyaknow')
                    <Docstring>
                        class_attribute's docstring
        <Function name="f" argnames=['x', ('y', 'a*5'), 'args']
varargs=True>
            <Docstring>
                f's docstring
            <Attribute name="function_attribute">
                <Expression>
                    1
                <Docstring>
                    f.function_attribute's docstring

compiler.parse() provides most of what's needed for this AST.  I think
that "tokenize" can be used to get the rest, and all that's left is to
hunker down and figure out how.  We can determine the line number from
the compiler.parse() AST, and a get_rhs(lineno) method would provide
the rest.

The Docutils Python reader component will transform this AST into a
Python-specific doctree, and then a `stylist transform`_ would further
transform it into a generic doctree.  Namespaces will have to be
compiled for each of the scopes, but I'm not certain at what stage of
processing.

It's very important to keep all docstring processing out of this, so
that it's a completely generic and not tool-specific.

For an overview see:

    http://docutils.sf.net/pep-0258.html#python-source-reader

For very preliminary code see:

    http://docutils.sf.net/docutils/readers/python/moduleparser.py

For tests and example output see:

    http://docutils.sf.net/test/test_readers/test_python/test_parser.py

I have also made some simple scripts to make "compiler", "parser", and
"tokenize" output easier to read.  They use input from the
test_parser.py module above.  See showast, showparse, and showtok in:

    http://docutils.sf.net/test/test_readers/test_python/

.. _pseudo-XML: http://docutils.sf.net/spec/doctree.html#pseudo-xml
.. _stylist transform:
   http://docutils.sf.net/spec/pep-0258.html#stylist-transforms

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

On Wednesday 04 December 2002 10:16 pm, David Goodger wrote:
>
> I've looked over the HappyDoc code and Tony "Tibs" Ibbs' PySource
> prototype. HappyDoc uses the stdlib "parser" module to parse Python modules
> into abstract syntax trees (ASTs), but that seems difficult and fragile,
> the ASTs being so low-level.  Tibs' prototype uses the much higher-level
> ASTs built by the stdlib "compiler" module, which are much easier to
> understand.  I've decided to use the "compiler" module also.

I'm pretty sure HappyDoc was written before the compiler module was generally 
available, but I'm not sure.  I've only had to make a few minor 
modifications to it in the past, since the language syntax hasn't evolved 
that far.  I'm working on a major overhaul of HappyDoc anyway, so now might 
be the time to rewrite the parsing stuff to use the compiler module.  If 
you're interested in collaborating, let me know.

Doug

On Wed, 4 Dec 2002, Brett Cannon wrote:

> [David Goodger]
>
> > So, is there any prior art out there?  Any pointers or advice?
> >
>
> How does PyChecker do it?  I would guess by reading the bytecode, but you
> never know.
>
> I would guess using regexes would be the best if you just want to read the
> source.  The ``tokenize`` module has all the regexes and they might be
> available independently from the methods in the module.

from ancient times when i did crossreferencing on modula or later pretty
printing newtonscript. i have to things on mind:
* when using regexes nultiline statements are not so easy.
* when using a lexer, association with the line might get
  lost (the lexer would probably merge the lines)
but whome do i tell this david, you should know more than i ever will
after parsing reST.

what is the intention:
* read doc-strings
* pretty print
* check the code
* reformat the code


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

[David Goodger]

> So, is there any prior art out there?  Any pointers or advice?
>

How does PyChecker do it?  I would guess by reading the bytecode, but you
never know.

I would guess using regexes would be the best if you just want to read the
source.  The ``tokenize`` module has all the regexes and they might be
available independently from the methods in the module.

-Brett

I have begun work on a Python source Reader component for Docutils.  I
expect the work to go slowly, as there is lots to absorb, much earlier work
to study and learn from, and little spare time to devote.  I'm trying to
keep it as simple as possible, mostly for my own benefit (lest my brain
explode).

I've looked over the HappyDoc code and Tony "Tibs" Ibbs' PySource prototype.
HappyDoc uses the stdlib "parser" module to parse Python modules into
abstract syntax trees (ASTs), but that seems difficult and fragile, the ASTs
being so low-level.  Tibs' prototype uses the much higher-level ASTs built
by the stdlib "compiler" module, which are much easier to understand.  I've
decided to use the "compiler" module also.

My first stumbling block is in parsing assignments.  I want to extract the
right-hand side (RHS) of assignments straight from the source.  In his
prototype, Tibs rebuilds the RHS from the AST, but that seems rather
roundabout and the results may not match the source perfectly (equivalent,
but not character-for-character).  I think using the "tokenize" module in
parallel with "compiler" may allow the code to extract the raw RHS text, as
well as other raw text that doesn't make it verbatim to the AST.

So, is there any prior art out there?  Any pointers or advice?

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

On Fri, Nov 29, 2002 at 07:14:52PM +0000, John Kozak wrote:
> I'm thinking of developing a wiki (to run under twisted) that uses
> reST as its native format.  Apart from the parser in MoinMoin, does
> anyone know of any effort I'm duplicating?

I have a rough abstract class at:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/ianb/wiki/WikiPage.py

It doesn't have a GUI (I've written very small ones with Webware and Spyce,
but I haven't uploaded them anywhere).  It's pretty simple.

  Ian

I'm thinking of developing a wiki (to run under twisted) that uses
reST as its native format.  Apart from the parser in MoinMoin, does
anyone know of any effort I'm duplicating?

John Kozak

Ray Leyva wrote:
> Working by running html.py on tools/test.txt, and checking the
> results ( visually / manually )

How is the HTML being rendered?

> versus what I get when I transform tools/test.txt with
> docutils-xml.py, and apply xsl stylesheet to the resulting test.xml
> documnt.  In some cases there are disparaties, what is the best way
> to determing what it *should* be?

The internal document tree is described in spec/doctree.txt
(http://docutils.sf.net/spec/doctree.html); it specifies how
attributes should be interpreted and processing expectations.

The output should match the input as much as possible.  I haven't
written anything to specify what the output should be.  The HTML
output assumes a modern graphical browser (Mozilla, MSIE, etc.) that
understands and correctly processes cascading stylesheets (at least
level 1, preferably level 2 also).  Support for stylesheets is
improving, but there are differences between browsers.  I check the
rendering on Mozilla and MSIE specifically.

> For instance in the examples below I believe my interpretation to be
> more correct, but I may be wrong please let me know.
> 
> Specifically on the enumerated lists samples :

It took me a while to see what the difference was.  Please point out
the differences explicitly.  I believe you mean that in the HTML, the
enumerators of list items are always arabic numerals, where some ought
to be letters or roman numerals instead.

I've seen this before from people using older browsers, especially
text-based browsers (links/lynx?).  The rendering of enumerators is
completely governed by the stylesheet, so either the browser can't
find the stylesheet (try using "--embed-stylesheet"), or it can't
understand it (try a recent Mozilla or MSIE).

If HTML that doesn't rely on stylesheets is desired, a new Writer
component is needed.  As I've said before, the writers/html4css1.py
module I wrote is a proof of concept, reference implementation, but it
doesn't have to be the only game in town.

I've updated the FAQ with some of these issues:
<." rel="nofollow">http://docutils.sf.net/FAQ.html>.

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

Ray Leyva wrote:
> 2) Can there be a command line option to remove the <!DOCTYPE ...
> directive from the XML file created by docutils xml?

I've added "--no-doctype" and "--no-xml-declaration" options to the
docutils_xml.py writer.  Use the tools/docutils-xml.py front end.

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

Working by running html.py on tools/test.txt, and checking the results (
visually / manually ) versus what I get when I transform tools/test.txt
with docutils-xml.py, and apply xsl stylesheet to the resulting test.xml
documnt.  In some cases there are disparaties, what is the best way to
determing what it *should* be?

For instance in the examples below I believe my interpretation to be
more correct, but I may be wrong please let me know.

Specifically on the enumerated lists samples :

test.html from running html.py on tools/test.txt :

2.3   Enumerated Lists

   1.

      Arabic numerals.
         1. lower alpha)
               1. (lower roman)
                     1. upper alpha.
                           1. upper roman)
   2.

      Lists that don't start at 1:
         3. Three
         4. Four
         3. C
         4. D
         3. iii
         4. iv

test.txt -> docutils-xml.py = test.xml -> my xsl stylesheet:

2.3   Enumerated Lists

   1. Arabic numerals.
         a. lower alpha)
               i. (lower roman)
                     A. upper alpha.
                           I. upper roman)
   2. Lists that don't start at 1:

      Enumerated list start value not ordinal-1: "3" (ordinal 3)
         3. Three
         4. Four

      Enumerated list start value not ordinal-1: "C" (ordinal 3)
         C. C
         D. D

      Enumerated list start value not ordinal-1: "iii" (ordinal 3)
         iii. iii
         iv. iv

Which is a better representation?

Thanks,
Ray

PS: I've inundated David Goodger with multiple replies that I was
sending directly to him, when I thought that I was sending to the list. 
Mea culpa.  I'll be more careful in the future.

On Tue, 2002-11-26 at 22:50, eng...@ss... wrote:
> On 26 Nov 2002, Ray Leyva wrote:
> 
> > 3)  Is there a single test document that uses everything in rst (
> > section indentation, tables, etc ... )?
> 
> i'd say tools/test.txt
> 
> 
> -- 
>  BINGO: Think outside the box
>  --- Engelbert Gruber -------+
>  SSG Fintl,Gruber,Lassnig   /
>  A6410 Telfs Untermarkt 9  /
>  Tel. ++43-5262-64727 ----+
> 
> 
> 
> 
> -------------------------------------------------------
> This SF.net email is sponsored by: Get the new Palm Tungsten T 
> handheld. Power & Color in a compact size! 
> http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0002en
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop

On 26 Nov 2002, Ray Leyva wrote:

> 3)  Is there a single test document that uses everything in rst (
> section indentation, tables, etc ... )?

i'd say tools/test.txt


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

Ray Leyva wrote:
> I'd be more than happy to contribute.  Right now though it requires
> libxml2, libxslt and their respective python bindings for this to work.
> I don't know if you're interested in something like that.

Not in the core, no, but a sandbox or parallel project would be great.

> 1)  The docutils-xml.py has some none functioning commandline options,
> is that known?  I can document if it hasn't already.

No, it isn't known.  Please do tell.

> 2)  Can there be a command line option to remove the <!DOCTYPE ...
> directive from the XML file created by docutils xml?

Yes.  I've made the changes, but I'll check them in tomorrow night (can't
now).

> I know it's a minidom, but I don't understand the cmdline classes well
> enought to add this option yet.

I don't understand this.

> 3)  Is there a single test document that uses everything in rst (
> section indentation, tables, etc ... )?

tools/test.txt exists for that purpose (not 100%, but close).

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

Thank you.
Ray

On Tue, 2002-11-26 at 07:49, Aahz wrote:
> [removing docutil-users]
> 
> On Tue, Nov 26, 2002, Ray Leyva wrote:
> >
> > 3)  Is there a single test document that uses everything in rst (
> > section indentation, tables, etc ... )?
> 
> I believe spec/rst/reStructuredText.txt comes pretty close.
> -- 
> Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/
> 
> "If you don't know what your program is supposed to do, you'd better not
> start writing it."  --Dijkstra
> 
> 
> -------------------------------------------------------
> This SF.net email is sponsored by: Get the new Palm Tungsten T 
> handheld. Power & Color in a compact size! 
> http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0002en
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop

[removing docutil-users]

On Tue, Nov 26, 2002, Ray Leyva wrote:
>
> 3)  Is there a single test document that uses everything in rst (
> section indentation, tables, etc ... )?

I believe spec/rst/reStructuredText.txt comes pretty close.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"If you don't know what your program is supposed to do, you'd better not
start writing it."  --Dijkstra

I'd be more than happy to contribute.  Right now though it requires
libxml2, libxslt and their respective python bindings for this to work. 
I don't know if you're interested in something like that.

Actually I can contribute the xsl stylesheets I'll be generating right
from the start.  A few questions:

1)  The docutils-xml.py has some none functioning commandline options,
is that known?  I can document if it hasn't already.

2)  Can there be a command line option to remove the <!DOCTYPE ...
directive from the XML file created by docutils xml?  I know it's a
minidom, but I don't understand the cmdline classes well enought to add
this option yet.  The reason I want to remove it is for offline
processing with libxml2 ... it's a validating parser, and when I go to
transform the docutils-xml file it first tries to validate.  That's no
issue when connected, but when offline it can get a bit annoying.

3)  Is there a single test document that uses everything in rst (
section indentation, tables, etc ... )?

Thanks for your feedback, and I'll definitely be contributing the Xsl
stylesheets.  I've got one that works throught he sections / title /
paragraphs.  I'm trying to work out the rest as I go along.  That's why
a good sample that uses *everything* would be great.

Ray

Ray Leyva wrote:
> Just wondering if anybody has begun working on an DocUtils-Xml -> Xsl to
> multi-target ( Html w/Css | Html no CSS | PDF ) transformation project
> yet.

Not as such, no.

> So the question is, has anybody started to work on any Xsl for
> DocUtils-XML?  If they have can they share what they've worked on?  I've
> looked in the sandbox but have found nothing ... maybe I'm looking in
> the wrong place?

Back in April I merged the former reStructuredText and DPS projects into
Docutils, and some of the old sandbox projects got left behind.  Several XSL
examples were there:

* http://cvs.sf.net/cgi-bin/viewcvs.cgi/structuredtext/sandbox/alanj
  (Alan Jaffray)
* http://cvs.sf.net/cgi-bin/viewcvs.cgi/structuredtext/sandbox/paulw
  (Paul Wright)
* http://cvs.sf.net/cgi-bin/viewcvs.cgi/structuredtext/sandbox/rtxt2html
  (Remi Bertholet)

They haven't been updated for some time, but they may help you get started.
If you can, please contribute your results back to Docutils!

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

Hi,

Just wondering if anybody has begun working on an DocUtils-Xml -> Xsl to
multi-target ( Html w/Css | Html no CSS | PDF ) transformation project
yet.

I've spent the last few months working on just such a thing, but my
initial documents are my own grammar of Xml, and well ... after much
working with it I've definitely come to the decision that while great
for transformation, and computerized transformations it sucks to have to
write so many < blah blah > just to get a basic webpage up.  In comes
DocUtils, and it's ability to create an Xml representation of reST.

So I started reading the code on Sunday afternoon ( yesterday ), and
have decided I *really* want to start using reST, as my standard static
content creation language.  Non-static stuff, might move to generate
reST, but I've already built it to generate my Xml grammar so I really
don't see the need at this time.  Maybe if somebody creates a better
presentation layer than mine I'll move it, but for now I think mines
better than most out there.

So the question is, has anybody started to work on any Xsl for
DocUtils-XML?  If they have can they share what they've worked on?  I've
looked in the sandbox but have found nothing ... maybe I'm looking in
the wrong place?  Anyways thanks for your time.

Ray

PS : Sorry for the cross post, but I thought it would be easier if I
sent this out as widely as possible, and I *know* that sometimes people
in dev are not in users, and vice-versa.

sorry i try once again

On Sun, 17 Nov 2002, Julien Letessier wrote:

> On mardi, nov 12, 2002, at 07:59 Europe/Paris,
> gr...@us... wrote:
>
> > style.tex should hold: the font (as sayed earlier palatino make pdfs
> > bigger)
> >
> > settings required for proper layout should be set by the writer
> > (written
> > to the output): this concerns your solution for footnotes and figures.
>
> sounds logical. i'll hard-code my TeX hacks into latex2e.py (if that's
> what you mean)

yes

> > the inclusion of the style file should be done after setting defaults,
> > so there is a possibility to overwrite defaults.
>
> yep, I'm perfectly okay ith that.

a suggestion from me, do you think it will work or must we expect
that some packages donot allow re-use or will collide.

> > caveats: if an option is given to the documentclass other packages
> >   recognize it automatically (at least i read so), otherwise every
> >   concerned package needs the option (it said so in th FM).
>
> As  a TeXnician, I've always considered as a bad habit using
> 'documentclass' options to set defaults for the various packages --
> rather specify the options exactly when needed. But if it makes your
> life easier, fine.

as a simple latex user i have no opinion. just tell what i read.
i am only concerned to not code to much knowledge (which package needs
which options) into the writer.

> One point though -- I think we should keep the 'geometry' package
> included -- the '\geometry' command can be used in the stylesheet to
> modify the settings.
>
> > and we need documented stylefiles so people have an idea what to use
> > it for.
>
> You mean, provide a few documented examples?

yes. should go into latex writer doc (=docs/latex_writer.txt ?)

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

On Sun, 17 Nov 2002, Julien Letessier wrote:

> On mardi, nov 12, 2002, at 07:59 Europe/Paris,
> gr...@us... wrote:
>
> > style.tex should hold: the font (as sayed earlier palatino make pdfs
> > bigger)
> >
> > settings required for proper layout should be set by the writer
> > (written
> > to the output): this concerns your solution for footnotes and figures.
>
> sounds logical. i'll hard-code my TeX hacks into latex2e.py (if that's
> what you mean)
>
> > the inclusion of the style file should be done after setting defaults,
> > so there is a possibility to overwrite defaults.
>
> yep, I'm perfectly okay ith that.
>
> > caveats: if an option is given to the documentclass other packages
> >   recognize it automatically (at least i read so), otherwise every
> >   concerned package needs the option (it said so in th FM).
>
> As  a TeXnician, I've always considered as a bad habit using
> 'documentclass' options to set defaults for the various packages --
> rather specify the options exactly when needed. But if it makes your
> life easier, fine.
>
> One point though -- I think we should keep the 'geometry' package
> included -- the '\geometry' command can be used in the stylesheet to
> modify the settings.
>
> > and we need documented stylefiles so people have an idea what to use
> > it for.
>
> You mean, provide a few documented examples?
>
> Cheers,
>
> -- julien
>
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by: To learn the basics of securing
> your web site with SSL, click here to get a FREE TRIAL of a Thawte
> Server Certificate: http://www.gothawte.com/rd524.html
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>

-- 
 BINGO: best of breed products and services
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+