docutils-develop

RE: [Docutils-develop] QuickRef (was RE: Figure references)

[Tony J I. (Tibs) <to...@ls...>]

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.)

RE: [Docutils-develop] QuickRef (was RE: Figure references)

[<eng...@ne...>]

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

Re: [Docutils-develop] QuickRef (was RE: Figure references)

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

Engelbert Gruber 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.

In a brute-force way, like this::

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

or like this::

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

Try it, it works!

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

RE: [Docutils-develop] QuickRef (was RE: Figure references)

[Tony J I. (Tibs) <to...@ls...>]

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.)

Re: [Docutils-develop] QuickRef (was RE: Figure references)

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

Tony J Ibbs (Tibs) wrote:
> 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.

I see, you're using "rst::" as a delimiter between examples,
effectively generating rows in an "example table".  Since "rst" is
assumes, this could be done more easily, perhaps with indentation and
".."::

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

>     ..examples::
>       rst::
>          The *raw* text we want.
> 
>          Which spans two paragraphs.
>       rst::
>          And might be a title
>          ====================
>          Or subtitle
>          -----------

The latter would be tricky, since section headers can only occur in
certain contexts (e.g., not within a block quote, and certainly not
within a table).  They may have to be simulated somehow.

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

Given enough effort, anything's possible. :-)

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

Re: [Docutils-develop] QuickRef (was RE: Figure references)

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

[Tony, re "fold-in" and "call-out" references]
> 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?

Yes, the proper names would help.  I have the feeling I saw the name
of the hardcopy style somewhere, but I haven't been able to find 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"

A note saying that would be fine.  I just think it's over-emphasized
and under-justified at present.

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