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

attached a quick script that checks for language.labels
having all entries that en has.

and if language directives are found.

This is how i understood the datastructure, might be totally wrong.

Could be put into a test if correct (david ?).

Is it an error if rst.language has no language module but
languages has ? e.g. sk.

cheers

p.s. still no interest complaining about rst to latex to pdf conversions ?

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

hi,

I'm not on the list, I hope it does not matter

this is diff against docutils 0.2.4, it adds slovak
support for docutils.=20

it's gzipped and attached, because
it contains iso-8859-2 charset and i'm afraid of
mail-client mangling of that characters

please, let me know, if the patch was applied or not,
i can watch it on the list archives

thanks,
miro
 <<docutils.sk.diff.gz>>=20

On Tue, 5 Nov 2002, David Goodger wrote:

> Andreas Jung wrote:
> > I am currently working on the integration of reStructuredText into
> > Zope.
>
> > I have currently two unresolved issues:
> >
> >  - Zope includes (re)STX documents into an existing document with a
> >    starting level of 3 (means it starts with the <H3> header)
>
> Sorry, I don't know exactly what you mean or what you want here.
> I can guess, but I'd rather not.  Please give examples and ask questions.

i used stx from zope prior to reST. AFAIR when converting stx to html
one can set the level for top level sections.

in stx::

  My Chapter

    my top level.

    sub section to chapter

      some text.

means for rst file::

  My Chapter
  ==========

  my top level.

  sub section to chapter
  ----------------------

  some text.

the Chapter should become <h3>Chapter</h3> section would become <h4>section</h4>

so that one can produce sites from several documents.

>
> >  - included (re)STX documents must not contain HTML header and footer
> >
> > Is there a way with docutils to create partitial HTML docs?
>

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

Andreas Jung wrote:
> I am currently working on the integration of reStructuredText into
> Zope.

I know almost nothing about Zope, but I believe "integration" may need
qualification here.  What exactly are you trying to do?  Have you
looked at Richard Jones' ZReST work?  See
http://www.zope.org/Members/richard/ZReST
(locally at http://docutils.sf.net/sandbox/richard/ZReST/).

> I have currently two unresolved issues:
> 
>  - Zope includes (re)STX documents into an existing document with a
>    starting level of 3 (means it starts with the <H3> header)

Sorry, I don't know exactly what you mean or what you want here.
I can guess, but I'd rather not.  Please give examples and ask questions.

>  - included (re)STX documents must not contain HTML header and footer
> 
> Is there a way with docutils to create partitial HTML docs?

Yes.  Look at the docutils/writers/html4css1.py module's Writer class.
In the "translate" method, it copies several attributes from its
"visitor" (HTMLTranslator object), from "head_prefix" to
"body_suffix".  These are pieces of HTML that may or may not be broken
up the way you want.  See Ollie Rutherfurd's Writer for ht2html for an
example: http://docutils.sf.net/sandbox/oliverr/ht/hthtml.py .

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

The ReStructuredText Document Product has been updated to use the latest
docutils API. Get it at:

   http://www.zope.org/Members/richard/ZReST

This is a Zope interface to the docutils project's ReStructuredText format.
 It offers:

- through-the-web editing
- handling of errors (with control over the reporting level)
- FTP editing (with access to the config properties and errors)
- extraction of the document title from the text itself
- configuration of the stylesheet used
- source view


     Richard

Hi,

I am currently working on the integration of reStructuredText into Zope.
I have currently two unresolved issues:

 - Zope includes (re)STX documents into an existing document with a starting
   level of 3 (means it starts with the <H3> header)

 - included (re)STX documents must not contain HTML header and footer

Is there a way with docutils to create partitial HTML docs?

Thanks in advance,
Andreas

    ---------------------------------------------------------------------
   -    Andreas Jung                     http://www.andreas-jung.com   -
  -   EMail: andreas at andreas-jung.com                              -
   -            "Life is too short to (re)write parsers"               -
    ---------------------------------------------------------------------

On Sat, 2002-11-02 at 17:47, David Goodger wrote:
> Ian Bicking wrote:
> > I'm getting this error, and I'm pretty sure I didn't get it a few
> > days ago:
> 
> A few days ago, your code was setting the Reader by name, wasn't it?
> I didn't anticipate setting the Parser by name and the Reader by
> instance in the core.publish_* convenience functions; I never tried
> it that way.  They should be fixed now.

Yes, this has fixed it.  Thanks.

  Ian

Ian Bicking wrote:
> I'm getting this error, and I'm pretty sure I didn't get it a few
> days ago:

A few days ago, your code was setting the Reader by name, wasn't it?
I didn't anticipate setting the Parser by name and the Reader by
instance in the core.publish_* convenience functions; I never tried
it that way.  They should be fixed now.

...
>   File ".../docutils/parsers/rst/__init__.py", line 89, in parse
>     inputlines = docutils.statemachine.string2lines(
> AttributeError: Values instance has no attribute 'tab_width'
> 
> After calling the code:
> 
> core.publish_string(
>             source=text,
>             reader=Reader(),
>             parser_name='restructuredtext',
>             writer_name='html')

The "tab_width" setting is specified in the Parser.  The error message
shows that the Parser wasn't known to the Publisher when the runtime
settings were obtained (by a call to
``core.Publisher.get_settings()``).  But because of the omission in
core.publish_string(), I don't see how the Parser code could have been
called at all.  Was the Parser set explicitly in your code somewhere,
perhaps in your Reader class?  I'm curious to see how the parser *was*
called.  Please post or send me your code (*before* you fix it).

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

Aahz wrote:
> Let's see, when I was having this problem, it was due to not having
> these lines in the correct sequence::
> 
>     pub = core.Publisher(writer=OOwriter.Writer())
>     pub.set_reader('standalone', None, 'restructuredtext')
>     settings = pub.get_settings()
>     pub.source = io.FileInput(settings, source_path=sys.argv[1])
>     pub.destination = io.StringOutput(settings)
>     content = pub.publish()
> 
> Apparently, you need to set the reader and writer before you get the
> settings,

Correct, and the Parser too.  All components need to be set before
getting the runtime settings, because the specifications for the
runtime settings are stored *in* the component classes.

> and you need to get the settings before you set source and
> destination.

Correct.  Source & destination need to know about the input and output
encoding settings.

> Check your code to see if that's the problem; if not, submit an SF
> bug.

Turns out that the bug was in the convenience functions in core.py,
not in Ian's code.  Should be fixed now.

> Nanny-mode: make sure to triple-check that you've got the latest
> tarball; if you're using CVS, make sure that you don't have any
> inconsistencies.

Always a good idea :)

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

On Sat, Nov 02, 2002, Ian Bicking wrote:
>
> I'm getting this error, and I'm pretty sure I didn't get it a few days
> ago:
> 
>   File "/usr/lib/python2.2/site-packages/docutils/core.py", line 324, in publish_string
>     return pub.publish()
>   File "/usr/lib/python2.2/site-packages/docutils/core.py", line 161, in publish
>     document = self.reader.read(self.source, self.parser, self.settings)
>   File "/usr/lib/python2.2/site-packages/docutils/readers/__init__.py", line 66, in read
>     self.parse()
>   File "/usr/lib/python2.2/site-packages/docutils/readers/__init__.py", line 72, in parse
>     self.parser.parse(self.input, document)
>   File "/usr/lib/python2.2/site-packages/docutils/parsers/rst/__init__.py", line 89, in parse
>     inputlines = docutils.statemachine.string2lines(
> AttributeError: Values instance has no attribute 'tab_width'
> 
> After calling the code:
> 
> core.publish_string(
>             source=text,
>             reader=Reader(),
>             parser_name='restructuredtext',
>             writer_name='html')
> 
> 
> I tried messing with __init__.py and shortcutting tab_width, but another
> setting problem popped up in its place.

Let's see, when I was having this problem, it was due to not having
these lines in the correct sequence::

    pub = core.Publisher(writer=OOwriter.Writer())
    pub.set_reader('standalone', None, 'restructuredtext')
    settings = pub.get_settings()
    pub.source = io.FileInput(settings, source_path=sys.argv[1])
    pub.destination = io.StringOutput(settings)
    content = pub.publish()

Apparently, you need to set the reader and writer before you get the
settings, and you need to get the settings before you set source and
destination.  Check your code to see if that's the problem; if not,
submit an SF bug.  Nanny-mode: make sure to triple-check that you've got
the latest tarball; if you're using CVS, make sure that you don't have
any inconsistencies.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

I'm getting this error, and I'm pretty sure I didn't get it a few days
ago:

  File "/usr/lib/python2.2/site-packages/docutils/core.py", line 324, in publish_string
    return pub.publish()
  File "/usr/lib/python2.2/site-packages/docutils/core.py", line 161, in publish
    document = self.reader.read(self.source, self.parser, self.settings)
  File "/usr/lib/python2.2/site-packages/docutils/readers/__init__.py", line 66, in read
    self.parse()
  File "/usr/lib/python2.2/site-packages/docutils/readers/__init__.py", line 72, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python2.2/site-packages/docutils/parsers/rst/__init__.py", line 89, in parse
    inputlines = docutils.statemachine.string2lines(
AttributeError: Values instance has no attribute 'tab_width'

After calling the code:

core.publish_string(
            source=text,
            reader=Reader(),
            parser_name='restructuredtext',
            writer_name='html')


I tried messing with __init__.py and shortcutting tab_width, but another
setting problem popped up in its place.

  Ian

> > The one thing I *can't* do is help you figure out how to do this in 
> > code, because I haven't spent much time with reST in ages (okay, 
> > ever),
> 
> Garth *did* do a very cool overhaul of the unit test 
> framework, for which he has our eternal gratitude.

:) 

> On Wed, Oct 30, 2002, David Goodger wrote:
>> Perhaps "priority" isn't the right term?  (Better term, anyone?)  The
>> transform with the lowest priority value is applied first.  There's
>> the connotation that "highest priority" goes first, opposite from
>> what's used.

Aahz wrote:
> "order" might be a better word, particularly since increasing
> numbers work well with order

Perhaps, although "order" is such an overloaded term that it almost always
requires clarification.  Some other candidate terms: sequence, index,
rank/ranking, grade, position.

> Perhaps an entirely different system might be better.  Instead of making
> ordering implict based on the priority ..., instead
> have some kind of ``TransformList`` class with methods
> ``insert_before()`` and ``insert_after()`` that take a transform that's
> the insert point (0 and -1 indicate first and last as usual), plus either
> a new transform or an ordered sequence of transforms to be inserted.

I suspect that such a system would have its own problems.  To position
transform A before transform B, B would have to be registered already.  Or B
would have to know about the relationship, which may not always be the case.
The previous system, similar to the above, failed and was replaced by the
current one because it was too coarse.

An absolute numbering is very clear and simple IMO.

> People are much more likely to remember the names of transforms than
> either the number or the exact order.

Although few of us will ever have to look at the transforms, and only
infrequently.  The spec/transforms.txt file lists them all, in order, when
we do need to refer to them.

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

On Wed, Oct 30, 2002, David Goodger wrote:
>
> Perhaps "priority" isn't the right term?  (Better term, anyone?)  The
> transform with the lowest priority value is applied first.  There's
> the connotation that "highest priority" goes first, opposite from
> what's used.

Perhaps an entirely different system might be better.  Instead of making
ordering implict based on the priority ("order" might be a better word,
particularly since increasing numbers work well with order)), instead
have some kind of ``TransformList`` class with methods
``insert_before()`` and ``insert_after()`` that take a transform that's
the insert point (0 and -1 indicate first and last as usual), plus either
a new transform or an ordered sequence of transforms to be inserted.

People are much more likely to remember the names of transforms than
either the number or the exact order.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

The way the "include" directive currently works, it reads in the file
to include and runs it through a nested parse.  This is suboptimal in
many ways:

(a) A construct must be completely contained within the included file.
    For example, this wouldn't work.  File master.txt::

        Doc Title
        =========

        Paragraph before section.

        .. include:: section.txt

        Paragraph in master.txt but should be in section.

    File section.txt::

        Section Title
        -------------

        Paragraph in section.

    This is the current (malformed) output from tools/publish.py::

        <document id="doc-title" name="doc title" source="master.txt">
            <title>
                Doc Title
            <paragraph>
                Paragraph before section.
            <section id="section-title" name="section title">
                <title>
                    Section Title
                <paragraph>
                    Paragraph in section.
            <paragraph>
                Paragraph in master.txt but should be in section.

    This is what it should be (note the final paragraph)::

        <document id="doc-title" name="doc title" source="master.txt">
            <title>
                Doc Title
            <paragraph>
                Paragraph before section.
            <section id="section-title" name="section title">
                <title>
                    Section Title
                <paragraph>
                    Paragraph in section.
                <paragraph>
                    Paragraph in master.txt but should be in section.

(b) For some reasons unknown but possibly related, input like this
    doesn't work::

        Doc Title
        =========

        Paragraph before section.

        .. include:: section.txt

        .. include:: section.txt

To solve this, we have to get rid of the nested parse.  To do that,
the included file's contents has to be inserted into the state
machine's "input_lines" attribute (list of single-line strings).  But I
don't want to modify the input list directly, because that would throw
off the line numbers (and file names) in the diagnostic output.

I'm thinking of a class that provides a single contiguous list-like
interface but maintains multiple discrete input lists internally,
keeping track of the offsets and sources of each list.  For example,
say we start with a single input list, source "one.txt", document
offset 0, input offset 0.  If we encounter an "input" directive at
line 10, the initial list is split in two, and the new included file's
input list is inserted in-between.  The new included file, "two.txt",
is 10 lines long; source is "two.txt, document offset 10, input offset
0.  The second part of the initial file has source "one.txt", document
offset 20, input offset 10 (from the beginning of "one.txt").

An iterator may be applicable, except that references will not be
exclusively forward or one-at-a-time.  A __getitem__ interface looks
best.  Also, iterators are only in Python 2.2+, so we'd have to
upgrade the minimum requirement (again).

Does anyone have any experience with this kind of situation, or know
of any references (examples, design patterns, etc.) that would be
applicable?  Advice?

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

[David]
>> From http://docutils.sf.net/spec/doctree.html#transitions:
>>
>>     A transition may not begin or end a section or document, nor
>>     may two transitions be immediately adjacent.
>>
>> The transitions were between sections (easy to see if you use the
>> tools/publish.py front end).  The parser isn't enforcing that rule,
>> which is a bug that should be fixed.

Fixed.  The parser now enforces the structure; transitions aren't
allowed at the beginning or end of sections or the document itself.

>> Removing the transitions turns up a much more serious bug though,
>> generating a traceback.  *This* could be an "include" directive
>> bug.  I'll look into it.

[Brett]
> ...that's why I put the transitions in -- I found that sequential
> "include"s with no intervening text stopped all the processing

You should have reported *that* as a bug! ;)

> putting transitions inbetween stopped the complaints.

That will work as a temporary work-around, until the "include"
directive problem is fixed.  I don't know *why* it works (or why it's
needed) yet.

It turns out that part the problem is quite deep.  The "include"
directive starts a nested parse, which means that a section in the
included file must be complete (it can't start in the included file
and finish in the master file).  This isn't very useful, so the
implementation of the "include" directive has to be rethought.
Unfortunately, to fix "include" it may be necessary to rework a very
low-level aspect of the parser.  If you're interested, I'll be
following up on this on the docutils-develop list
(http://lists.sf.net/lists/listinfo/docutils-develop).

> Unfortunately I've been in the position of needing to convert an
> existing doc over to reStructuredText in a hurry, and haven't had
> much time to study the spec or the code closely.

Understandable :)

> Kudos again on building a system that let me get as far as I did in
> a few hours!

Thanks.

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

Ian Bicking wrote:
> Wow, it actually works.  That was easier than I thought it would be.

Always good to hear ;-)

> Here's what I did:
...
> class WikiLink(Transform):
> 
>     default_priority = 400
...
> Oh, and what exactly is the default_priority bit?  If I set it high,
> will Wiki links be created before internal links (hence subsuming
> internal links)?

default_priority is used for ordering the transforms.  From PEP 258
(http://docutils.sf.net/spec/pep-0258.html#transformer):

    Transform classes each have a ``default_priority`` attribute which
    is used by the Transformer to apply transforms in order (low to
    high).  The default priority can be overridden when adding
    transforms to the Transformer object.

Perhaps "priority" isn't the right term?  (Better term, anyone?)  The
transform with the lowest priority value is applied first.  There's
the connotation that "highest priority" goes first, opposite from
what's used.

See http://docutils.sf.net/spec/transforms.html for a complete list of
transforms and the order they are applied.  I would say that the
WikiLink transform should be applied after references.InternalTargets,
and therefore should have a priority value of 680.  The value of 400
used above will apply WikiLink before any of the standard hyperlink
resolution transforms, causing *all* references to be Wiki references
(i.e., none would be "resolved" prior to WikiLink seeing them).

> # Then to actually use it I had to do:
> 
> from docutils import readers
> # WikiReST is the module I gave above, and it's located here:
> sys.path.append('/usr/home/ianb/prog/WebwareWiki/Wiki')
> readers._reader_aliases['wiki'] = 'WikiReST'
> 
> # Then I use 'wiki' for the reader_name in
>   docutils.core.publish_string

That would be fine if your Reader was a module installed in
docutils/readers.  Since it isn't...

> it would be better still if I could have simply passed in the class
> to an argument to publish_string. Of course, now that I look at it,
> there's a reader argument to publish_string

Bingo!

> -- but I have to give it an instance, and that seem awkward to make
> -- how can I instantiate the reader if I have to pass the parser to
> the constructor, and the parser is created in publish_string?

The Reader will instantiate the parser automatically.  Like this::

    import WikiReST
    from docutils import core
    reader = WikiReST.Reader(parser=None,
                             parser_name='restructuredtext')
    output = docutils.core.publish_string(reader=reader,
                                          parser=reader.parser,
                                          ...)

I've just added default parameter values to the
``docutils.readers.Reader.__init__`` method to make Reader
instantiation easier::

    reader = WikiReST.Reader()

> Of course, it would be good if there was a better hook for adding a
> reader like that.

As I mentioned, that interface is only meant for installed modules.

> For instance, a better use of __import__ in
> docutils.readers.__init__ would have kept me from having to add
> something to the path

In fact, there's a to-do item that proposes removing the temptation of
using sys.path magic:

    * In ``docutils.readers.get_reader_class`` (& ``parsers`` &
      ``writers`` too), should we be importing "standalone" or
      "docutils.readers.standalone"?  (This would avoid importing
      top-level modules if the module name is not in docutils/readers.
      Potential nastiness.)

So it becomes a simple choice: get a standard (installed) component by
name, or pass a custom component object explicitly.

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

On Thu, 31 Oct 2002 12:22 am, David Goodger wrote:
> Richard Jones wrote:
> >>> The ZReST product is broken at the moment, and I've received two
> >>> emails about it.
> >>
> >> I'll take a look and see if I can fix it.  Can you forward the reports
> >> you've received?  Any details you can add would help.
> >
> > AFAICT it's an options thing. The errors are things like:
> >
> > Publisher instance has no attribute 'set_options'
> > Publisher instance has no attribute 'options'
> >
> > ... that sort of thing :)
>
> Have you tried the latest ZReST with the latest Docutils (both from CVS)?
> On 18 Oct I did a mass edit & checkin of the options->settings change, and
> ZReST.py was also changed.  I may have missed something, but I *did* call
> for testing.

Yep, and I haven't had time to actually test it, sorry.


    Richard

Richard Jones wrote:
>>> The ZReST product is broken at the moment, and I've received two
>>> emails about it.
>> 
>> I'll take a look and see if I can fix it.  Can you forward the reports
>> you've received?  Any details you can add would help.
> 
> AFAICT it's an options thing. The errors are things like:
> 
> Publisher instance has no attribute 'set_options'
> Publisher instance has no attribute 'options'
> 
> ... that sort of thing :)

Have you tried the latest ZReST with the latest Docutils (both from CVS)?
On 18 Oct I did a mass edit & checkin of the options->settings change, and
ZReST.py was also changed.  I may have missed something, but I *did* call
for testing.

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

On Tue, 2002-10-29 at 19:59, David Goodger wrote:
> Transforms, actually.  Hyperlinks are resolved in the transforms in
> docutils.transforms.references.  The
> docutils.transforms.universal.FinalChecks transform checks for unresolved
> references and signals errors.  A transform replacing or preceding this one
> would be the place to do the Wiki-linking.

Wow, it actually works.  That was easier than I thought it would be. 
Here's what I did:

from docutils import nodes
from docutils.readers import standalone
from docutils.transforms import Transform

class WikiLinkResolver(nodes.SparseNodeVisitor):

    def visit_reference(self, node):
        if node.resolved or not node.hasattr('refname'):
            return
        refname = node['refname']
        node.resolved = 1
        node['refuri'] = refname
        del node['refname']

class WikiLink(Transform):

    default_priority = 400

    def apply(self):
        visitor = WikiLinkResolver(self.document)
        self.document.walk(visitor)
        
class Reader(standalone.Reader):

    supported = standalone.Reader.supported + ('wiki',)

    default_transforms = standalone.Reader.default_transforms \
                         + (WikiLink,)



######################################
# Then to actually use it I had to do:

from docutils import readers
# WikiReST is the module I gave above, and it's located here:
sys.path.append('/usr/home/ianb/prog/WebwareWiki/Wiki')
readers._reader_aliases['wiki'] = 'WikiReST'

# Then I use 'wiki' for the reader_name in docutils.core.publish_string

######################################

Of course, it would be good if there was a better hook for adding a
reader like that.  For instance, a better use of __import__ in
docutils.readers.__init__ would have kept me from having to add
something to the path (I could have used
"readers._reader_aliases['wiki'] = 'Wiki.WikiReST'"), and of course it
would be better still if I could have simply passed in the class to an
argument to publish_string.  Of course, now that I look at it, there's a
reader argument to publish_string -- but I have to give it an instance,
and that seem awkward to make -- how can I instantiate the reader if I
have to pass the parser to the constructor, and the parser is created in
publish_string?

I'm sure there's a better way, or you can add a better way ;)  But it
works without heroic efforts, and that's very cool.

Oh, and what exactly is the default_priority bit?  If I set it high,
will Wiki links be created before internal links (hence subsuming
internal links)?

  Ian

On Wed, 30 Oct 2002 1:57 pm, David Goodger wrote:
> Richard Jones wrote:
> > I realise the API won't be frozen for eternity, but it'll make early
> > adoption much easier.
>
> ...
>
> > Being able to recommend to users that they use version 0.3.x, which has a
> > frozen API and possibly even a maintenance cycle, would make life a lot
> > easier.
> >
> > As far as I'm concerned, the API freeze could happen _today_.
>
> Although I sympathize and appreciate your predicament, I don't want to
> freeze the API because there's so much yet to be done.  I still consider
> this to be an experimental work in progress, and a learning experience. 
> I'm always learning more about the problem domain.
>
> Maybe there's a middle ground.  I've committed to getting a working
> PySource Reader for the 0.3 release, but there hasn't been much progress
> there yet. Perhaps an interim 0.2.x release that we can base tools on?

Actually, that's pretty much what I was thinking about. I didn't necessarily 
mean to freeze the API for ever, just for one release that can be labelled 
"0.2.x" or "0.3.x".


> I think the project is too young to pursue parallel stable/maintenance and
> development/experimental branches.  I wouldn't want to take on that kind of
> chore.

That's a fair call, really.


>  How do you handle this type of situation with RoundUp or other
> projects?

I've made a lot more releases with Roundup, and as a consequence I have to 
produce upgrading information for people who actually follow through the 
changing API etc.


> Why don't you bring this up on docutils-develop?  Maybe some of the other
> developers/consultants will have some ideas.  Feel free to quote anything
> here.

Actually, I misfired with the original email - it was _supposed_ to go to 
docutils-develop ;)


> > The ZReST product is broken at the moment, and I've received two
> > emails about it.
>
> I'll take a look and see if I can fix it.  Can you forward the reports
> you've received?  Any details you can add would help.

AFAICT it's an options thing. The errors are things like:

  Publisher instance has no attribute 'set_options'
  Publisher instance has no attribute 'options'

... that sort of thing :)


>  I may even use it as
> an excuse to learn a bit about Zope.  Like how to install it. ;-)

In short:

1. download the 2.5.1 source from zope.org
2. make a directory like /usr/local/zope
3. unpack the source in that directory
4. make a directory /usr/local/zope/instance
5. ... and another couple: instance/var and instance/Products
6. symlink the ZReST directory from the docutils source to instance/Products
7. make a script called "start" in /usr/local/zope/instance containing::

    #! /bin/sh
    reldir=`dirname $0`
    export INSTANCE_HOME=`cd $reldir; pwd`
    exec /usr/bin/python2 \
         /export/zope/Zope-2.5.1-src/z2.py \
         -D "$@"

8. ./start

That'll start the server on port 8080, attached to the current terminal, with 
some logging going to the terminal and some additional debug output when 
errors occur. Remove the "-D" (debug) in the start script to have it detach 
and lose that other stuff.

The full range of options that the start script will accept are given in the 
Zope source "z2.py" script, at the top.


> > Though it'd be nice to get HTML production sans <html>/<head>/<body>
> > wrapper tags so the ZReST product could produce fragments.
>
> You can get that now.  Use the NullOutput class for destination, or throw
> away the string returned from StringOutput (copy & modify the
> publish_string function), and access the html4css1 Writer's
> "body_pre_docinfo", "docinfo", and "body" attributes (all lists of
> strings).  Just add them together and ''.join() them.

Yeah, that makes sense. Sorry, it's been several projects since I last looked 
at that stuff :(


> > Don't ask much, do I? :)
>
> Find me a good sponsor and I'd be able to *give* much more. :)

That one's outta my hands, I'm afraid :)


     Richard

I agree with Garth that new markup is not the way to go here.  But I also
agree with Ian that "trust me" just ain't good enough ;-), so I'm glad some
good convincing arguments came up.

[Ian]
>> My only concern is that I won't be able to distinguish between
>> internal and external links if _ gets more overloaded.

[Garth]
> Not at all. It's up to the consumer of the document to resolve links. In
> reST terminology, that's either a parser or a formatter or something
> else -- I can never guess -- but it's not the *parser* that does it.

Transforms, actually.  Hyperlinks are resolved in the transforms in
docutils.transforms.references.  The
docutils.transforms.universal.FinalChecks transform checks for unresolved
references and signals errors.  A transform replacing or preceding this one
would be the place to do the Wiki-linking.

> The one thing I *can't* do is help you figure out how to do this in
> code, because I haven't spent much time with reST in ages (okay, ever),

Garth *did* do a very cool overhaul of the unit test framework, for which he
has our eternal gratitude.

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

On Tue, 2002-10-29 at 18:24, Garth Kidd wrote:
> If you can make a link resolve within a document, fantastic! If not,
> resolve it to other documents in the Wiki. That precedence also lets
> people break titled sections in a document (automatic target) into a
> separate page on the Wiki, in which case all of the links in the
> document will suddenly point to the new page when the title is removed
> from the source document. 
> 
> The same is true of links in the text. Let's say a site you used to link
> to has disappeared. Pull a copy out of the Internet Archive, save as a
> Wiki page, and remove the ``.. _target:`` entry. Done. 

Those are good arguments, you've convinced me.  Now I just need to know
how to do it :)

  Ian

>>> As I think about it, I'm leaning toward new punctuation.
>>> Where should I look for this?
>> 
>> Please, don't do the punctuation. Stick with the trailing 
>> ``_``. Trust me on this one. :)
> 
> Why, what's your experience?  Too hard to do, or too messy 
> when you're through?  

Too hard to deal with the people who find the existing reST syntax hard
enough to deal with before you throw even more punctuation into the mix?
:) 

> My only concern is that I won't be able to distinguish between 
> internal and external links if _ gets more overloaded.

Not at all. It's up to the consumer of the document to resolve links. In
reST terminology, that's either a parser or a formatter or something
else -- I can never guess -- but it's not the *parser* that does it. 

If you can make a link resolve within a document, fantastic! If not,
resolve it to other documents in the Wiki. That precedence also lets
people break titled sections in a document (automatic target) into a
separate page on the Wiki, in which case all of the links in the
document will suddenly point to the new page when the title is removed
from the source document. 

The same is true of links in the text. Let's say a site you used to link
to has disappeared. Pull a copy out of the Internet Archive, save as a
Wiki page, and remove the ``.. _target:`` entry. Done. 

If you used different punctuation, someone would have to wade through
the document changing all of the punctuation to do these things, which
is overly painful. 

The one thing I *can't* do is help you figure out how to do this in
code, because I haven't spent much time with reST in ages (okay, ever),
but I reckon changing target resolution is going to be a whole lot
easier than adding YetMorePunctuation_. 

Regards,
Garth.

On Tue, 2002-10-29 at 11:06, Garth Kidd wrote:
> > As I think about it, I'm leaning toward new punctuation.  
> > Where should I look for this?
> 
> Please, don't do the punctuation. Stick with the trailing ``_``. Trust
> me on this one. :) 

Why, what's your experience?  Too hard to do, or too messy when you're
through?  My only concern is that I won't be able to distinguish between
internal and external links if _ gets more overloaded.

  Ian