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

eng...@ne... wrote:
> I donot beleive yet
>
> +-----+--------------------+
> | raw | the same formatted |
> +-----+--------------------+
> where  do you put the "::", inside the cell ?
> does this work ?
> i thought the lines on the left must be marked literal
> each.

David may answer this better than I can (he's *much* better at designing
directives!).

But the idea, as I would see it, is that one doesn't write::

    +-----+--------------------+
    | raw | the same formatted |
    +-----+--------------------+

but instead something like::

    ..examples::
      rst::
         The *raw* text we want
      rst::
         Another such.

which would *generate* something like (the result of processing)::

    +----------------------------+------------------------+
    | The user types             | The result is          |
    +============================+========================+
    | ``The *raw* text we want`` | The *raw* text we want |
    +----------------------------+------------------------+
    | ``Another such``           | Another such           |
    +----------------------------+------------------------+

For single lines, and simple inline things, we could obviously do
without the directive and do it "by hand", but the directive approach
also allows us to contemplate::

    ..examples::
      rst::
         The *raw* text we want.

         Which spans two paragraphs.
      rst::
         And might be a title
         ====================
         Or subtitle
         -----------

Since a directive can do "anything it likes" (that *may* be a quote)
with the stuff "inside" it, this approach seems like it should work...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

>David Goodger wrote:
>> Tibs wrote:
>> > The problem is writing the directives that take reST
>> > input for one column of a table and put out the result of processing
>> > it (e.g., to HTML) as the other column,
>>
>> That directive shouldn't be difficult to write.  Section titles and
>> transitions present a problem, but with some care everything else
>> should be easy.  Or we can just build a bunch of two-column tables,
>> duplicate the examples, and put "::" before the ones on the left.
>
>OK. An answer of "that's not as scary as you thought" is always good to
>get.

I donot beleive yet

+-----+--------------------+
| raw | the same formatted |
+-----+--------------------+
where  do you put the "::", inside the cell ?
does this work ? 
i thought the lines on the left must be marked literal
each.

Richard Jones wrote:
> I lieu of a "usable" version of the docutils python API doc
> extractor, I've run epydoc over the docutils tree, producing:
>
>   http://docutils.sourceforge.net/apidoc/docutils.html

Ooh - that's seriously pretty looking stuff!

(whether it's *useful* I'll leave to others, since I've not time to look
it over, but it is *does* look nice)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
A single element tuple needs a trailing comma, and an empty tuple needs
brackets to distinguish it from a coffee stain. - Duncan Booth, in his
intro to Python for the ACCU Spring 2002 conference
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

David Goodger wrote:
> Tibs wrote:
> > The problem is writing the directives that take reST
> > input for one column of a table and put out the result of processing
> > it (e.g., to HTML) as the other column,
>
> That directive shouldn't be difficult to write.  Section titles and
> transitions present a problem, but with some care everything else
> should be easy.  Or we can just build a bunch of two-column tables,
> duplicate the examples, and put "::" before the ones on the left.

OK. An answer of "that's not as scary as you thought" is always good to
get.

> I introduced a colleague to Docutils recently and let him loose with
> the docs.  He professed confusion with the non-standard terms
> "fold-in" and "call-out", and I've seen confusion from others as well.
> I think we should reconsider this complexity.  In a generated
> quickref, the reference style would be the default of the output
> format, "fold-in" for HTML, and "call-out" for a paper-only format.

The names of the two styles certainly don't help - good naming is one of
the hardest bits of any task, and I don't think I did particularly well
there. On the other hand, they *are* two different things, and both
styles are important - what *are* they called?

Anyway, whilst I personally like the idea of having both styles
available, it seems eminently sensible to say that one gets the style
(most) appropriate to the output format, and dropping the ability to ask
for either - at least until someone needs it enough to write the code to
support it!

However, in that case I still think the quickref has to say "well, there
are these two possible styles of output, and you'll get the one best
suited to your output medium" - it sounds a *bit* as if you're instead
saying that the quickref output to HTML would only describe the style
produced for HTML, which wouldn't be very helpful if I were using a
web-page of the quickref to consult whilst thinking about how my
document would appear in (for instance) PDF (or if I'd printed out the
quickref, from some random output format, long since having forgotten
which, and am referring to the paper copy).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

On Fri, Oct 11, 2002, Richard Jones wrote:
>
> Ah, the options structure. Yeah, that bit me a few times :)
> 
> See if the code in the ZReST product helps... sandbox/richard/ZReST/ZReST.py 
> in the render method.

Actually, it now looks like a snapshot bug.  I downloaded another
snapshot just a minute ago, and now I'm getting a different exception in
statemachine.

I've been mulling over whether I should suggest this, but it seems to me
that snapshots probably ought to pass a regression suite before being
uploaded, and perhaps only get updated once per day or so.  Seems to me
that anyone who really cares about the latest files can grab them from
CVS, and snapshots would have a bit more consistency to them, even if
they're not formal releases.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

On Fri, 11 Oct 2002 3:57 pm, Aahz wrote:
> I tried this recipe David gave to Michael Hudson::
>
>     pub = core.Publisher()
>     options = pub.set_options()
>     pub.source = io.FileInput(options, source_path=sys.argv[1])
>     pub.destination = io.StringOutput(options)
>     pub.set_reader('standalone', None, 'restructuredtext')
>     pub.writer = OOwriter.Writer
>     content = pub.publish()
>
> and got this traceback::
>
>     Traceback (most recent call last):
>       File "open_office.py", line 17, in ?
>         content = pub.publish()
>       File "/home/aahz/src/Lib-Python/docutils/core.py", line 135, in
> publish document = self.reader.read(self.source, self.parser, self.options)
> File "/home/aahz/src/Lib-Python/docutils/readers/__init__.py", line 69, in
> read self.parse()
>       File "/home/aahz/src/Lib-Python/docutils/readers/__init__.py", line
> 77, in parse self.parser.parse(self.input, document)
>       File "/home/aahz/src/Lib-Python/docutils/parsers/rst/__init__.py",
> line 89, in parse self.statemachine.run(inputlines, document,
> inliner=self.inliner) File
> "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 152, in
> run inliner.init_customizations(document.options)
>       File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line
> 435, in init_customizations if options.pep_references:
>     AttributeError: Values instance has no attribute 'pep_references'
>     make: *** [test] Error 1

Ah, the options structure. Yeah, that bit me a few times :)

See if the code in the ZReST product helps... sandbox/richard/ZReST/ZReST.py 
in the render method.


    Richard

I tried this recipe David gave to Michael Hudson::

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

and got this traceback::

    Traceback (most recent call last):
      File "open_office.py", line 17, in ?
        content = pub.publish()
      File "/home/aahz/src/Lib-Python/docutils/core.py", line 135, in publish
        document = self.reader.read(self.source, self.parser, self.options)
      File "/home/aahz/src/Lib-Python/docutils/readers/__init__.py", line 69, in read
        self.parse()
      File "/home/aahz/src/Lib-Python/docutils/readers/__init__.py", line 77, in parse
        self.parser.parse(self.input, document)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/__init__.py", line 89, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 152, in run
        inliner.init_customizations(document.options)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 435, in init_customizations
        if options.pep_references:
    AttributeError: Values instance has no attribute 'pep_references'
    make: *** [test] Error 1

(I'm posting this mainly to make Michael feel better; it's late enough
that I'll probably find the answer before I get a response.  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

This seemed like a good idea, hope I haven't overstepped the mark, David. I'm 
hoping that automatically generated API docs will help people (including me 
;) to understand the API...

I lieu of a "usable" version of the docutils python API doc extractor, I've 
run epydoc over the docutils tree, producing:

  http://docutils.sourceforge.net/apidoc/docutils.html

I didn't include the tools or test dirs, since epydoc can't cope with them. 
I've also attached the list of modules you'll need if you're wanting to run 
the doc generator yourself via:

      epydoc -o /tmp/apidoc `cat list`


     Richard

On Thu, Oct 10, 2002, David Goodger wrote:
> Aahz wrote:
>> 
>> What am I doing wrong with this directive::
>> 
>>     from docutils import nodes
>>     from docutils.parsers.rst import directives
>> 
>>     registry = directives._directive_registry
>>     registry['index'] = ('OOdirectives', 'index_directive')
> 
> You must be importing this module explicitly somewhere, right?
> Otherwise, how does the registration code run before the directive is
> registered? ;->

Of course.  I'm running a hacked publish.py currently to validate the
structure.  Next I'll be following your directions to Michael Hudson to
generate the actual OpenOffice.org XML (needs to go into a string so
that it can all get shoved into a ZIP file with the metadata).

>>     class index_entry(nodes.General, nodes.Element): pass
> 
> This is the problem.  Replace "nodes.Element" with
> "nodes.TextElement".  Their __init__ signatures are different.

Got it.  I was getting confused by the inheritance tree in nodes.py.
I'm still not sure that's the route I want to take, but it'll do for
now.

>>         return [node] + messages
>> 
>>     index_directive.content = 1
> 
> I'm guessing that this is a "first draft" of the directive, yes?
> You'll probably want to create an index_entry for each of the terms
> listed in the directive, and insert them at the beginning of the
> paragraph (therefore "index_entry" should be an inline element).  In
> fact, the class declaration should probably be::
> 
>     class index_entry(nodes.Inline, nodes.TextElement): pass

It appears that simply declaring something Inline doesn't do anything;
I'm assuming I need to run a transform in the writer?  Or should the
directive find its parent/predecessor-sibling during parsing?

>> If I replace the code of index_directive() with "return []", I don't
>> get an exception.
> 
> That's odd.  Are you sure you made no other changes?  

Yes, that line replaces all four lines of code, so the node wasn't
getting created.  ;-)  I was actually starting to think that the node
creation might be the problem before you responded, but I was at the
point where staring at the code gave me brain-burn.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Engelbert, would you please add some blank lines before & after your
comments?  It's difficult to notice your comments without them.

> (i know one might "pass" everything that is not working,
>  but i am still not sure what writers do in all the places,
>  e.g. see docinfo handling in latex_writer)

I don't see the problem.  It should be easy to put in a simple
catch-all method for unimplemented nodes.  Just make sure it doesn't
act (or not act) silently.  If you're not sure what should be done,
say so explicitly.

> or if i might dare i start making_a_writer.txt in some place
> you like and put in what i know and what i donot know ?

Yes, that would be most welcome.  I see that you've already started;
great!

> i donot want to remove test.txt, but maybe split it so when working
> on a feature i can use *the* test-tables.txt file, not do it myself
> everytime. and test.txt is the concatenation of all the test-*.txt
> files.

I see what you're saying now.  Incremental testing is definitely
useful; that's how the Docutils test suite works.  The parser would
never have been completed without many small unittests (now at 518
tests!).

If you'd like to make up a bunch of small document fragments for test
purposes, go ahead.  Perhaps in a new docutils/test/fragments
directory.

>> As I've said before, to get out of the sandbox the LaTeX Writer
>> doesn't have to handle every construct perfectly, but it *does* have
>> to handle every construct without (a) crashing or (b) silently
>> omitting data.  If the Writer can't handle a particular construct,
>> have it say so explicitly ("**X Not Implemented Yet**"), *and* have it
>> output a simpler form, such as the string returned by the
>> ``.astext()`` node method.  I earlier objected to the presence of many
>> Writer/Visitor methods containing only "pass", which is not
>> acceptable.
>>
>>     Errors should never pass silently.
>>     Unless explicitly silenced.
>
> agree absolutely. but it would make life easier if someone really
> needs the features (xp-wise nothing would be done otherwise),
> because the "customer" is a reviewer with high interest.

I don't understand what you mean.

-- 
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, Oct 10, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> It's already taking longer than I'd hoped to learn how to use reST.
> 
> That's unfortunate.  Any insights into how it might be made easier?
> Or is it because you're not only learning it as a user, but also as a
> developer?  Thinking about index directives and multi-chapter/file book
> processing adds complexity.

It's having to learn reST both inside and out that's the problem, yes; I
need to figure out not only the reST syntax, but also which bits apply
most appropriately to the demands of writing a book, *and* I have to
figure out how to convert the bits into usable output.  Until reST
settles down a bit more and has more than one full-fledged output
format, I don't think it *can* be much easier -- annoying as it is.

I'm about 70% of the way to a minimal system for converting a reST file
into OpenOffice format.  Please note the emphasis on "minimal", and it's
uuugly.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Aahz wrote:
> Here's some sample reST text::
> 
>     Overall, my primary source for determining what to include in
>     this book was the netnews group ``comp.lang.python``.  I've been
>     reading that group for several years, and the same questions
>     seem to show up over and over again.
> 
>     .. index::
>         comp.lang.python
>         Usenet
>         netnews
> 
> What am I doing wrong with this directive::
> 
>     from docutils import nodes
>     from docutils.parsers.rst import directives
> 
>     registry = directives._directive_registry
>     registry['index'] = ('OOdirectives', 'index_directive')

You must be importing this module explicitly somewhere, right?
Otherwise, how does the registration code run before the directive is
registered? ;->

>     class index_entry(nodes.General, nodes.Element): pass

This is the problem.  Replace "nodes.Element" with
"nodes.TextElement".  Their __init__ signatures are different.

>     def index_directive(name, arguments, options, content, lineno,
>             content_offset, block_text, state, state_machine):
>         text = '\n'.join(content)
>         text_nodes, messages = state.inline_text(text, lineno)
>         node = index_entry(text, '', *text_nodes)
                                   ^^
Right here, the code is sending a string ('') as a child node.

>         return [node] + messages
> 
>     index_directive.content = 1

I'm guessing that this is a "first draft" of the directive, yes?
You'll probably want to create an index_entry for each of the terms
listed in the directive, and insert them at the beginning of the
paragraph (therefore "index_entry" should be an inline element).  In
fact, the class declaration should probably be::

    class index_entry(nodes.Inline, nodes.TextElement): pass

> If I replace the code of index_directive() with "return []", I don't
> get an exception.

That's odd.  Are you sure you made no other changes?  This is where
the error originates:

>       File "OOdirectives.py", line 17, in index_directive
>         node = index_entry(text, '', *text_nodes)

-- 
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 Fri, 11 Oct 2002 11:58 am, David Goodger wrote:
> Agreed, and convinced.  I was trying for something that would be
> applicable to tables as well, but that can be done easily with a
> simple wrapper directive::
>
>     .. table:: optional title here
>
>        :name: table's name for references here
>
>        =====  =====
>          x    not x
>        =====  =====
>        True   False
>        False  True
>        =====  =====

I just saw this go past in the CVS log, and I _like_ it :)

+1


   Richard

Tibs wrote:
> The problem is writing the directives that take reST
> input for one column of a table and put out the result of processing
> it (e.g., to HTML) as the other column,

That directive shouldn't be difficult to write.  Section titles and
transitions present a problem, but with some care everything else
should be easy.  Or we can just build a bunch of two-column tables,
duplicate the examples, and put "::" before the ones on the left.

> and also the fact that for some inputs there are two alternate
> outputs, both of which need to be shown (i.e., the fold-in and
> call-out styles for references).

I introduced a colleague to Docutils recently and let him loose with
the docs.  He professed confusion with the non-standard terms
"fold-in" and "call-out", and I've seen confusion from others as well.
I think we should reconsider this complexity.  In a generated
quickref, the reference style would be the default of the output
format, "fold-in" for HTML, and "call-out" for a paper-only format.

-- 
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:
> It's already taking longer than I'd hoped to learn how to use reST.

That's unfortunate.  Any insights into how it might be made easier?
Or is it because you're not only learning it as a user, but also as a
developer?  Thinking about index directives and multi-chapter/file book
processing adds complexity.

-- 
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]
>>>> I've thought some more about this (full details soon to appear in
>>>> the spec/notes.txt file), and I think the best way to name an
>>>> object is the way we've always named targets::
>>>>
>>>>         .. _figure name:
>>>>
>>>>         .. figure:: image.png
>>>>
>>>> This applies equally well to tables.

[Aahz]
>>> It's not clear to me how these two directives interact.

The first isn't a directive.

[Richard]
>> The ".. _figure name:" creates a target, placing a target called
>> "figure name" in the document just before the ".. figure::"
>> directive. Not entirely clear, no, and I'd actually prefer the
>>
>> .. figure:: image.png
>>    :name: figure name
>> 
>> which looks a lot clearer (in terms of keeping related information
>> together) to me as a document author.

I can see your point of view.

>> I've always seen the ".. _figure name:" target generation syntax
>> as a last-resort fallback,

Yes, I suppose it is.

>> as it's almost always jarring to see in the source text. But that
>> could just be me :)

No, I try to avoid them as well.  They add clutter.

[Aahz]
> +1
> 
> reST should be easy to read for people only minimally familiar with
> it.

Agreed, and convinced.  I was trying for something that would be
applicable to tables as well, but that can be done easily with a
simple wrapper directive::

    .. table:: optional title here
       :name: table's name for references here

       =====  =====
         x    not x
       =====  =====
       True   False
       False  True
       =====  =====

This would also allow other attributes to be set, like border styles.
The same technique could be used for other objects.

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

Here's some sample reST text::

    Overall, my primary source for determining what to include in this book
    was the netnews group ``comp.lang.python``.  I've been reading that
    group for several years, and the same questions seem to show up over and
    over again.

    .. index::
        comp.lang.python
        Usenet
        netnews

What am I doing wrong with this directive::

    from docutils import nodes
    from docutils.parsers.rst import directives

    registry = directives._directive_registry
    registry['index'] = ('OOdirectives', 'index_directive')

    class index_entry(nodes.General, nodes.Element): pass

    def index_directive(name, arguments, options, content, lineno,
            content_offset, block_text, state, state_machine):
        text = '\n'.join(content)
        text_nodes, messages = state.inline_text(text, lineno)
        node = index_entry(text, '', *text_nodes)
        return [node] + messages

    index_directive.content = 1

If I replace the code of index_directive() with "return []", I don't get
an exception.  With the above code (ripped directly from
docutils.parsers.rst.directives.body.line_block()), I get the following
traceback::

    AttributeError: 'str' object has no attribute 'parent'
    input line 9
    module /home/aahz/src/Lib-Python/docutils/nodes.py, line 72, function setup_child
    Traceback (most recent call last):
      File "publish.py", line 27, in ?
        publish(description=description)
      File "/home/aahz/src/Lib-Python/docutils/core.py", line 161, in publish
        pub.publish(argv, usage, description, option_spec)
      File "/home/aahz/src/Lib-Python/docutils/core.py", line 135, in publish
        document = self.reader.read(self.source, self.parser, self.options)
      File "/home/aahz/src/Lib-Python/docutils/readers/__init__.py", line 69, in read
        self.parse()
      File "/home/aahz/src/Lib-Python/docutils/readers/__init__.py", line 77, in parse
        self.parser.parse(self.input, document)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/__init__.py", line 89, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 163, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/home/aahz/src/Lib-Python/docutils/statemachine.py", line 218, in run
        context, next_state, result = self.check_line(
      File "/home/aahz/src/Lib-Python/docutils/statemachine.py", line 400, in check_line
        return method(match, context, next_state)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 1885, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 1897, in explicit_construct
        return method(self, expmatch)
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 1669, in directive
        return self.parse_directive(
      File "/home/aahz/src/Lib-Python/docutils/parsers/rst/states.py", line 1751, in parse_directive
        block_text, self, self.state_machine)
      File "OOdirectives.py", line 17, in index_directive
        node = index_entry(text, '', *text_nodes)
      File "/home/aahz/src/Lib-Python/docutils/nodes.py", line 252, in __init__
        self.extend(children)           # maintain parent info
      File "/home/aahz/src/Lib-Python/docutils/nodes.py", line 418, in extend
        self.setup_child(node)
      File "/home/aahz/src/Lib-Python/docutils/nodes.py", line 72, in setup_child
        child.parent = self
    AttributeError: 'str' object has no attribute 'parent'

gr...@us... wrote:
> about the quickref.html to rest:
>  either use w3m -dump so one might have the tables useable
>  (external references are lost maybe link or netkit could do better)

Nah, the problem isn't converting HTML-as-such to reST (that's fairly
trivial with a decent text editor (well, Emacs) and a little time - I'd
guess 20 minutes as a maximum, and one needn't lose anything). The
problem is writing the directives that take reST input for one column of
a table and put out the result of processing it (e.g., to HTML) as the
other column, and also the fact that for some inputs there are two
alternate outputs, both of which need to be shown (i.e., the fold-in and
call-out styles for references).

Of course, the *advantage* of converting it to reST is the same as for
any document - one gains the ability to output it in multiple formats
(so PDF and LaTeX as well as HTML, at least). And, of course, the
proposed directives would be more reliable than hand-typing what one
*thinks* the output should be!

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

On Thu, Oct 10, 2002, gr...@us... wrote:
>
> http://jakarta.apache.org/poi/index.html
> claims to being able to write ole-documents (sounds like a bad zip-file)
> run docutils under jython and use it ?

No, at this point, I think I'd rather not drag in Java/Jython.  It's
already taking longer than I'd hoped to learn how to use reST.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

On Wed, 9 Oct 2002, David Goodger wrote:

> Engelbert Gruber wrote:
> > i am willing to give support for real problems, meaning not the
> > pathologic test.txt.
>
> I've got to call you on this one.  "Pathological"?!?  That is a gross
:-))))
> misrepresentation.  The tools/test.txt file is pretty complete (*not*
> 100% though), but there's nothing in it that can't be found elsewhere.
> Certainly nothing pathological!
>
> > sorry my time is limited and there are so much possibilities.
>
> Join the club. ;-)
>
> > maybe we schould split test.txt, so one could get a compliance page,
> > which construct works how good with which writer.
>
> tools/test.txt *is* the compliance file, the only one we've got.  I
> don't see a need for a weakened compliance test.
i mean that, test.txt holds "all" constructs as a compliance test
but it does not work (at least not always) when developing, i did
it and julien did the same, he did cut out the hard parts to get
test.txt through the writer.
(i know one might "pass" everything that is not working,
 but i am still not sure what writers do in all the places,
 e.g. see docinfo handling in latex_writer)
 or if i might dare i start making_a_writer.txt in some place
 you like and put in what i know and what i donot know ?

i donot want to remove test.txt, but maybe split it so when working
on a feature i can use *the* test-tables.txt file, not do it myself
everytime. and test.txt is the concatenation of all the test-*.txt files.

>
> As I've said before, to get out of the sandbox the LaTeX Writer
> doesn't have to handle every construct perfectly, but it *does* have
> to handle every construct without (a) crashing or (b) silently
> omitting data.  If the Writer can't handle a particular construct,
> have it say so explicitly ("**X Not Implemented Yet**"), *and* have it
> output a simpler form, such as the string returned by the
> ``.astext()`` node method.  I earlier objected to the presence of many
> Writer/Visitor methods containing only "pass", which is not
> acceptable.
>
>     Errors should never pass silently.
>     Unless explicitly silenced.
agree absolutely. but it would make life easier if someone really needs
the features (xp-wise nothing would be done otherwise), because the
"customer" is a reviewer with high interest.

about the quickref.html to rest:
 either use w3m -dump so one might have the tables useable
 (external references are lost maybe link or netkit could do better)
>
cheers
-- 
 BINGO: objects, objects, objects (r.racko)
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

http://jakarta.apache.org/poi/index.html
claims to being able to write ole-documents (sounds like a bad zip-file)
run docutils under jython and use it ?

see the BINGO and remember "'e's pinning for the fjords"

-- 
 BINGO: Remarkable bird, the Norwegian Blue.
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

On Thu, Oct 10, 2002, Richard Jones wrote:
> On Thu, 10 Oct 2002 2:25 pm, Aahz wrote:
>> David wrote:
>>>
>>> I've thought some more about this (full details soon to appear in the
>>> spec/notes.txt file), and I think the best way to name an object is the
>>> way we've always named targets::
>>>
>>>         .. _figure name:
>>>
>>>         .. figure:: image.png
>>>
>>> This applies equally well to tables.
>>
>> It's not clear to me how these two directives interact.
> 
> The ".. _figure name:" creates a target, placing a target called
> "figure name" in the document just before the ".. figure::"
> directive. Not entirely clear, no, and I'd actually prefer the
>
> .. figure:: image.png
>    :name: figure name
> 
> which looks a lot clearer (in terms of keeping related information
> together) to me as a document author. I've always seen the ".. _figure
> name:" target generation syntax as a last-resort fallback, as it's
> almost always jarring to see in the source text. But that could just
> be me :)

+1

reST should be easy to read for people only minimally familiar with it.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

On Thu, 10 Oct 2002 2:25 pm, Aahz wrote:
> David wrote:
> > I've thought some more about this (full details soon to appear in the
> > spec/notes.txt file), and I think the best way to name an object is the
> > way we've always named targets::
> >
> >         .. _figure name:
> >
> >         .. figure:: image.png
> >
> > This applies equally well to tables.
>
> It's not clear to me how these two directives interact.

The ".. _figure name:" creates a target, placing a target called "figure name" 
in the document just before the ".. figure::" directive. Not entirely clear, 
no, and I'd actually prefer the

.. figure:: image.png
   :name: figure name

which looks a lot clearer (in terms of keeping related information together) 
to me as a document author. I've always seen the ".. _figure name:" target 
generation syntax as a last-resort fallback, as it's almost always jarring to 
see in the source text. But that could just be me :)


    Richard

>>>> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
>>>> figure 3.11"), how do I do that?
>>> 
>>> I don't know.  Currently, figures don't have any attribute which can be
>>> referenced.  Perhaps a "name" option on figures?  For example::
>>> 
>>>     .. figure:: image.png
>>>        :name: image's name
> 
> I've thought some more about this (full details soon to appear in the
> spec/notes.txt file), and I think the best way to name an object is the
> way we've always named targets::
> 
>         .. _figure name:
> 
>         .. figure:: image.png
> 
> This applies equally well to tables.

It's not clear to me how these two directives interact.

> Too complicated.  The original interpreted text approach is better::
> 
>     See :figure:`figure name` on :page:`figure name`.
> 
> The "figure" and "page" roles could generate some boilerplate text.
> The position of the role (prefix or suffix) could also be utilized.

That works for me.

>>>> I'm probably going to create some kind of ToC directive that goes
>>>> in an include file so I can create cross-chapter references
>>>> easily.
>>> 
>>> I don't follow.
>>
>> What I'm thinking more of (at least for starters) is an
>> extremely simple list of references to reST documents.
> 
> Can you elaborate with details of the file's contents, and ideas of
> how it would work?  I'd like to understand what you're proposing (and
> I don't have a clue now).

First the ToC::

    .. ToC-list::
        Introduction.txt
        Objects.txt
        Data.txt
        Control.txt

Then a sample use::

    .. include:: ToC.txt

    As I said earlier in chapter :chapter:`Objects.txt`, the reference
    count gets increased every time a binding is made.

Which produces::

    As I said earlier in chapter 2, the reference count gets increased
    every time a binding is made.

The ToC in this form doesn't even need to be references to actual reST
documents; I'm simply doing it that way for a minimum of future-proofing,
in case I do want to add the ability to pick up references within
external chapters.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Aahz wrote:
>>> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
>>> figure 3.11"), how do I do that?
>> 
>> I don't know.  Currently, figures don't have any attribute which can be
>> referenced.  Perhaps a "name" option on figures?  For example::
>> 
>>     .. figure:: image.png
>>        :name: image's name

I've thought some more about this (full details soon to appear in the
spec/notes.txt file), and I think the best way to name an object is the
way we've always named targets::

        .. _figure name:

        .. figure:: image.png

This applies equally well to tables.

>> How to refer to a figure though?  Perhaps something like this::
>> 
>>     See :figure:`image's name`.

I also toyed with the idea of parameterized substitutions::

    See |figure (figure name)|, on |page (figure name)|.

    .. |figure (name)| figure-ref:: (name)
    .. |page (name)| page-ref:: (name)

The result would be::

    See figure 3.11 on page 157.

But this would require substitution directives to be processed at
reference-time, not at definition-time as they are now.  Or,
the directives could just leave ``pending`` elements behind, and the
transforms could do the work.  How to pass the data through?

Too complicated.  The original interpreted text approach is better::

    See :figure:`figure name` on :page:`figure name`.

The "figure" and "page" roles could generate some boilerplate text.
The position of the role (prefix or suffix) could also be utilized.

>>> I'm probably going to create some kind of ToC directive that goes
>>> in an include file so I can create cross-chapter references
>>> easily.
>> 
>> I don't follow.
...
> What I'm thinking more of (at least for starters) is an
> extremely simple list of references to reST documents.

Can you elaborate with details of the file's contents, and ideas of
how it would work?  I'd like to understand what you're proposing (and
I don't have a clue now).

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