Development discussion for the docutils project

David Abrahams | 1 Sep 2004 04:38

Re: Notation for continued paragraphs?

David Goodger <goodger <at> python.org> writes:

> [David Abrahams]
>  > it strikes me as a deficiency in ReST that I can't express what I
>  > mean.
>
> The Docutils document model is designed to be relatively simple.  It
> is not meant to be as all-inclusive as DocBook.  Just compare the
> lengths of their DTDs. 
>
> My opinion is that paragraphs are simple block elements, not compound
> block elements [*]_.  The Docutils document model reflects that.
> DocBook allows them, but DocBook allows a lot of things which Docutils
> doesn't, and never will.  IMO, allowing mixed text and block-level
> elements is asking for trouble.  

You already allow nested block structures:

* foo bar

  .. parsed-literal::

     baz

* mumble

With a little effort I know I could think of more.

> The concept of "compound paragraphs"
> is at a higher level than what the Docutils document model is designed

(Continue reading)

headers

David Goodger | 1 Sep 2004 04:59

Re: Notation for continued paragraphs?

[David Goodger]
 >> IMO, allowing mixed text and block-level elements is asking for
 >> trouble.

[David Abrahams]
 > You already allow nested block structures:
 >
 > * foo bar
 >
 >   .. parsed-literal::
 >
 >      baz
 >
 > * mumble

So?  There's no mixed text and block-level elements there.  That
parses to:

<bullet_list>
     <list_item>
         <paragraph>
             foo bar
         <literal_block>
             baz
     <list_item>
         <paragraph>
             mumble

Nothing wrong with that.  What I was talking about is structure like
this:

(Continue reading)

headers

David Abrahams | 1 Sep 2004 10:03

Re: Notation for continued paragraphs?

David Goodger <goodger <at> python.org> writes:

> [David Goodger]
>  >> IMO, allowing mixed text and block-level elements is asking for
>  >> trouble.
>
> [David Abrahams]
>  > You already allow nested block structures:
>  >
>  > * foo bar
>  >
>  >   .. parsed-literal::
>  >
>  >      baz
>  >
>  > * mumble
>
> So?  There's no mixed text and block-level elements there.  That
> parses to:
>
> <bullet_list>
>      <list_item>
>          <paragraph>
>              foo bar
>          <literal_block>
>              baz
>      <list_item>
>          <paragraph>
>              mumble
>

(Continue reading)

headers

Felix Wiemann | 1 Sep 2004 16:23

Re: Notation for continued paragraphs?

David Abrahams wrote:

> David Goodger writes:
>
>> <paragraph>
>>      some text
>>      <literal_block>
>>          literal text
>>      more paragraph text
>>
>> Note that there's a block-level element, <literal_block>, embedded in
>> #PCDATA.  That structure is, IMO, insane.  
>
> Looks perfectly sane to me.

The reason why it's probably a bad idea is that the structure above
mixes block-level elements (literal block) and inline-level elements
(text).

Thus it makes trouble when using the HTML writer.

>>> .. paragraph::
>>>
>>>    foo bar
>>>
>>>    .. parsed-literal::
>>>
>>>       mumble
>>>
>>>    baz

(Continue reading)

headers

Fred L. Drake, Jr. | 2 Sep 2004 05:48

Re: Re: Notation for continued paragraphs?

On Wednesday 01 September 2004 10:23 am, Felix Wiemann wrote:
 > The reason why it's probably a bad idea is that the structure above
 > mixes block-level elements (literal block) and inline-level elements
 > (text).

I'm beginning to suspect that the current point of contention has, as its 
foundation, an assumption that Felix's comment makes clear:  That some 
elements are "block" and others are "inline".  I don't think this distinction 
is right, and it closely reflects assumptions that HTML has (in the past) 
encouraged.

Describing an element type as being fundamentally "block" implies certain 
aspects of it's presentation.  In HTML, this has classically been accepted, 
though as CSS has evolved, those assumptions are being called to task.  Lists 
are not always "block" in the presentational sense that they were in early 
HTML dialects; an ordered list, for example, can be embedded within a 
sentence (within a paragraph), quite effectively:

-----------------------------------------------------------------------------
To reproduce the failing test result, you need to 1) install Python 2.3.4, 2) 
install PyFoobar 0.9.3.5.1a12, and 3) run the script in Figure 1.
-----------------------------------------------------------------------------

There's nothing "block" about the list in this presentation; but its still a 
list.

Some document structures lend themselves to "block" presentation, but others 
are more flexible, and can be presented in either inline (as above) or block 
forms:

(Continue reading)

headers

David Goodger | 2 Sep 2004 06:50

Re: Re: Notation for continued paragraphs?

[Fred L. Drake, Jr.]
 > I'm beginning to suspect that the current point of contention has,
 > as its foundation, an assumption that Felix's comment makes clear:
 > That some elements are "block" and others are "inline".

No suspicion necessary:
<http://docutils.sf.net/docs/ref/doctree.html#element-hierarchy> makes
it quite clear.  We have structural elements (sections, etc.), body
elements (paragraphs, lists, etc.), and inline elements (emphasis,
etc.).

 > I don't think this distinction is right, and it closely reflects
 > assumptions that HTML has (in the past) encouraged.

Perhaps I'm dating myself, but I think this distinction *is* right,
and necessary.  It has nothing to do with HTML though; my biases
predate HTML's evils.

 > --------------------------------------------------------------------
 > To reproduce the failing test result, you need to 1) install Python
 > 2.3.4, 2) install PyFoobar 0.9.3.5.1a12, and 3) run the script in
 > Figure 1.
 > --------------------------------------------------------------------
 >
 > There's nothing "block" about the list in this presentation; but its
 > still a list.

There are limits though that show that the block concept is useful and
necessary.  List items consisting of more than phrases (e.g. multiple
sentences or paragraphs) are difficult or impossible to render inline.

(Continue reading)

headers

David Abrahams | 2 Sep 2004 13:54

Re: Notation for continued paragraphs?

David Goodger <goodger <at> python.org> writes:

>  > --------------------------------------------------------------------
>  > To reproduce the failing test result, you need to 1) install Python
>  > 2.3.4, 2) install PyFoobar 0.9.3.5.1a12, and 3) run the script in
>  > Figure 1.
>  > --------------------------------------------------------------------
>  >
>  > There's nothing "block" about the list in this presentation; but its
>  > still a list.
>
> There are limits though that show that the block concept is useful and
> necessary.  List items consisting of more than phrases (e.g. multiple
> sentences or paragraphs) are difficult or impossible to render inline.
> It's not simply a matter of stylesheet-fiddling.

I think that proves Fred's point.  Some renderers might decide the
presentation of a list (inline or block) depending on the size of its
items.  "Block-ness" is not an inherent property of a lists, which are
logical/structural elements.

--

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.

(Continue reading)

headers

David Goodger | 2 Sep 2004 16:19

Re: Re: Notation for continued paragraphs?

[David Goodger]
 >> There are limits though that show that the block concept is useful
 >> and necessary.  List items consisting of more than phrases
 >> (e.g. multiple sentences or paragraphs) are difficult or impossible
 >> to render inline.  It's not simply a matter of stylesheet-fiddling.

[David Abrahams]
 > I think that proves Fred's point.  Some renderers might decide the
 > presentation of a list (inline or block) depending on the size of
 > its items.

Some authors might object strenuously to renderers which mess with
their docs in such a way.  Even with structured documents, writing is
a creative, artistic act, and cannot be automated completely.  Authors
make decisions about document structure that are (IMO) too subtle for
markup and impossible for software to understand.  The rationale for a
vertical list may be to provide extra emphasis, and that emphasis
would be lost were the list to be rendered inline.

 > "Block-ness" is not an inherent property of a lists, which are
 > logical/structural elements.

I disagree.  In the Docutils/reStructuredText model, "block-ness" *is*
an inherent property of lists.  If I mark up a list, it's because I
want a structured, block-level list.  If I want an inline list (1)
I'll just write it in the text flow, (2) using implicit markup like
you see here, (3) because no further markup is necessary and would
just get in the way.  Some people may say that an inline list like
that does need to be marked up, and they might also say that a word in
"quotes" should actually be a word in <quote>quotes</quote>.  But I

(Continue reading)

headers

David Priest | 2 Sep 2004 17:11

Re: Re: Notation for continued paragraphs?

On Thu, 02 Sep 2004 10:19:30 -0400, David Goodger <goodger <at> python.org>  
wrote:

> Some authors might object strenuously to renderers which mess with
> their docs in such a way.  Even with structured documents, writing is
> a creative, artistic act, and cannot be automated completely.  Authors
> make decisions about document structure that are (IMO) too subtle for
> markup and impossible for software to understand.  The rationale for a
> vertical list may be to provide extra emphasis, and that emphasis
> would be lost were the list to be rendered inline.

That is a terrible argument.  Worst I've seen yet on this issue.  For  
starters, most authors don't have any choice about how their documents are  
rendered with Docutils writers, and for those authors who *want* an inline  
list, they're currently out of luck despite their most strenuous  
objections.

Writing is writing.  Layout is layout.  One of the key benefits to ReST is  
that it removes layout from the authoring equation: authors indicate  
structure only, not layout.

--

-- 
David Priest -- 250 542-5208
WritersBlock Technical Communications

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

(Continue reading)

headers

engelbert.gruber | 3 Sep 2004 07:35

Re: Re: Notation for continued paragraphs?

On Thu, 2 Sep 2004, David Priest wrote:

> On Thu, 02 Sep 2004 10:19:30 -0400, David Goodger <goodger <at> python.org>
> wrote:
>
> > Some authors might object strenuously to renderers which mess with
> > their docs in such a way.  Even with structured documents, writing is
> > a creative, artistic act, and cannot be automated completely.  Authors
> > make decisions about document structure that are (IMO) too subtle for
> > markup and impossible for software to understand.  The rationale for a
> > vertical list may be to provide extra emphasis, and that emphasis
> > would be lost were the list to be rendered inline.
>
> That is a terrible argument.  Worst I've seen yet on this issue.  For
> starters, most authors don't have any choice about how their documents are
> rendered with Docutils writers, and for those authors who *want* an inline
> list, they're currently out of luck despite their most strenuous
> objections.
>
> Writing is writing.  Layout is layout.  One of the key benefits to ReST is
> that it removes layout from the authoring equation: authors indicate
> structure only, not layout.

i thought this is the other way for structured text: authors write text
already formatted with mininmal markup where unavoidable.

perl pod and some wiki syntaxes do ease the parser part by doing it
linewise, e.g. ::

  =section title=

(Continue reading)

headers

David Abrahams | 2 Sep 2004 20:05

Re: Re: Notation for continued paragraphs?

"David Priest" <priest <at> sfu.ca> writes:

> On Thu, 02 Sep 2004 10:19:30 -0400, David Goodger <goodger <at> python.org>
> wrote:
>
>> Some authors might object strenuously to renderers which mess with
>> their docs in such a way.  Even with structured documents, writing is
>> a creative, artistic act, and cannot be automated completely.  Authors
>> make decisions about document structure that are (IMO) too subtle for
>> markup and impossible for software to understand.  The rationale for a
>> vertical list may be to provide extra emphasis, and that emphasis
>> would be lost were the list to be rendered inline.
>
> That is a terrible argument.  Worst I've seen yet on this issue.  For
> starters, most authors don't have any choice about how their documents
> are  rendered with Docutils writers, and for those authors who *want*
> an inline  list, they're currently out of luck despite their most
> strenuous  objections.
>
> Writing is writing.  Layout is layout.  One of the key benefits to
> ReST is  that it removes layout from the authoring equation: authors
> indicate  structure only, not layout.

Well, that was my view of it too, but David G. gets to say what ReST
indicates.  If he says it indicates layout, it does.  Too bad,
though.  I'd rather fight than switch, but only up to a point.

--

-- 
Dave Abrahams
Boost Consulting

(Continue reading)

headers

David Goodger | 2 Sep 2004 21:37

Re: Re: Notation for continued paragraphs?

[David Abrahams]
 > David G. gets to say what ReST
> indicates.  If he says it indicates layout, it does.

Only on the input side.  ReST is a markup language and parser.
It's independent of output, and doesn't care about it.

--

-- 
David Goodger <http://python.net/~goodger>

headers

David Abrahams | 2 Sep 2004 22:25

Re: Notation for continued paragraphs?

David Goodger <goodger <at> python.org> writes:

> [David Abrahams]
>  > David G. gets to say what ReST
>> indicates.  If he says it indicates layout, it does.
>
> Only on the input side.  ReST is a markup language and parser.
> It's independent of output, and doesn't care about it.

What if we consider output to be the Docutils XML?

--

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

David Priest | 2 Sep 2004 22:42

Re: Re: Notation for continued paragraphs?

On Thu, 02 Sep 2004 16:25:43 -0400, David Abrahams  
<dave <at> boost-consulting.com> wrote:

> David Goodger <goodger <at> python.org> writes:
>
>> [David Abrahams]
>>  > David G. gets to say what ReST
>>> indicates.  If he says it indicates layout, it does.
>>
>> Only on the input side.  ReST is a markup language and parser.
>> It's independent of output, and doesn't care about it.
>
> What if we consider output to be the Docutils XML?

XML has no layout (ie. visual) structure.  It has only logical structure.

reST dictates logical structure only insofar as Docutils can successfully  
infer structure from reST.  What happens after that is wholly independent  
of reST.

--

-- 
David Priest -- 250 542-5208
WritersBlock Technical Communications

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

(Continue reading)

headers

Aahz | 2 Sep 2004 19:33

Re: Re: Notation for continued paragraphs?

On Thu, Sep 02, 2004, David Priest wrote:
>
> Writing is writing.  Layout is layout.  One of the key benefits to
> ReST is that it removes layout from the authoring equation: authors
> indicate structure only, not layout.

On the contrary: reST uses layout to indicate structure.  reST is
designed to be both human-readable and computer-parsable; that limits
what can be done with implicit markup.  The goal of reST is to make the
most common features available implicitly or with subtle cues that don't
distract from readability (such as ``::``).
--

-- 
Aahz (aahz <at> pythoncraft.com)           <*>         http://www.pythoncraft.com/

"To me vi is Zen.  To use vi is to practice zen.  Every command is a
koan.  Profound to the user, unintelligible to the uninitiated.  You
discover truth everytime you use it."  --reddy <at> lion.austin.ibm.com

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

David Goodger | 2 Sep 2004 17:34

Re: Re: Notation for continued paragraphs?

[David Priest]
 > That is a terrible argument.  Worst I've seen yet on this issue.

Worst ... argument ... ever 
I'll try to redeem it.

 > For starters, most authors don't have any choice about how their
 > documents are rendered with Docutils writers,

Stylesheets?  But that's a different issue altogether.

Perhaps I shouldn't have said "renderers".  What I meant is that
structure is significant, and I think that vertical and inline lists
represent different structure.  Changing a vertical list into an
inline list would alter the structure.  I don't think a document
system has any business doing such structural alterations.

 > and for those authors who *want* an inline list, they're currently
 > out of luck despite their most strenuous objections.

How so?  (a) This is an inline list.  (b) It requires no special
markup.  (c) Is there anything wrong with it?  (d) I haven't seen any
strenuous objections anyhow.

 > Writing is writing.  Layout is layout.  One of the key benefits to
 > ReST is that it removes layout from the authoring equation: authors
 > indicate structure only, not layout.

Sure, I agree completely.  But don't you think that vertical and
inline lists represent different structure?

(Continue reading)

headers

David Priest | 2 Sep 2004 18:05

Re: Re: Notation for continued paragraphs?

On Thu, 02 Sep 2004 11:34:10 -0400, David Goodger <goodger <at> python.org>  
wrote:
> I think that vertical and inline lists
> represent different structure.  Changing a vertical list into an
> inline list would alter the structure.  I don't think a document
> system has any business doing such structural alterations.

Best to differentiate between logical structure and visual structure.  A  
vertical list and an inline list are both logically the same, regardless  
the visual presentation; it is the duty of the writer/renderer to  
determine whether that logical structure is presented vertically, inline,  
or otherwise.

> How so?  (a) This is an inline list.  (b) It requires no special
> markup.  (c) Is there anything wrong with it?  (d) I haven't seen any
> strenuous objections anyhow.

There are two problems: a) the logical structure is lost; b) the visual  
renderer can not enforce stylistic conventions.  As demonstrated ably by  
the difference between our two lists, I think.

ReST's markup
  a. Absolutely determines logical structure.  It would be an uncommon  
Docutils writer that makes deep changes to the structure.
  b. Only *hints* at visual structure.  It would be an uncommon renderer  
that precisely replicates the ReST visual layout.

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!

(Continue reading)

headers

David Goodger | 2 Sep 2004 18:32

Re: Re: Notation for continued paragraphs?

[David Priest]
 > Best to differentiate between logical structure and visual
 > structure.

Problem is, reST infers logical structure from visual cues.

 > A vertical list and an inline list are both logically the same,
 > regardless the visual presentation;

I think there is a subtle but real difference.  An inline list says
"this list is part of the text flow", whereas a vertical list says
"this list is an independent entity, separate from the text flow."

 > it is the duty of the writer/renderer to determine whether that
 > logical structure is presented vertically, inline, or otherwise.

In this case, I disagree.

 >> (a) This is an inline list.  (b) It requires no special
 >> markup.  (c) Is there anything wrong with it?  (d) I haven't seen
 >> any strenuous objections anyhow.
 >
 > There are two problems: a) the logical structure is lost;

Oh, how so?  I don't see anything lost.

 > b) the visual renderer can not enforce stylistic conventions.  As
 > demonstrated ably by the difference between our two lists, I think.

Stylistic conventions, such as?  Separating items by semicolons vs.

(Continue reading)

headers

David Goodger | 2 Sep 2004 21:28

Re: Re: Notation for continued paragraphs?

(Replying to David's accidental off-list message.  Yes, I checked 

[David Goodger]
 >>>> (a) This is an inline list.  (b) It requires no special markup.
 >>>> (c) Is there anything wrong with it?  (d) I haven't seen any
 >>>> strenuous objections anyhow.

[David Priest]
 >>> There are two problems: a) the logical structure is lost;

[David Goodger]
 >> Oh, how so?  I don't see anything lost.

[David Priest]
 > Eh?  Docutils recognizes the inline list and provides structure
 > denoting it as such, so that the writer/renderer may adjust the
 > visual style as desired??

No, reST doesn't infer any structure from that (though I suppose it
might be possible).  What I meant was, parse that paragraph, render it
as anything, and nothing is missing that was there at the beginning.
The reader is able to infer the fact that it's an inline list.

 >> I'd say reST does more than hint.  ReST is WYSIWYG plaintext
 >> markup, so it is a very visual medium.
 >
 > You kidding me?

Not at all.  Read what I wrote again; I'm not saying any more or less.
When I talk about reST, I'm only talking about the input markup and

(Continue reading)

headers

David Priest | 2 Sep 2004 22:08

Re: Re: Notation for continued paragraphs?

> [David Goodger]
>  >>>> (a) This is an inline list.  (b) It requires no special markup.
>  >>>> (c) Is there anything wrong with it?  (d) I haven't seen any
>  >>>> strenuous objections anyhow.
>
> [David Priest]
>  >>> There are two problems: a) the logical structure is lost;
>
> [David Goodger]
>  >> Oh, how so?  I don't see anything lost.

2nd attempt: the *logical* structure is lost.  As-is the transformation  
tools (writers) are unable to recognize that that is a list and render it  
using whatever visual conventions deemed necessary by the transformation.

IOW, with the vertical list Docutils recognizes and creates a logical  
structure; that structure can be used by the transformation tool to create  
whatever visual output is desired.  The t.t. might very well indent all  
lists and render the items vertically; or it might well render them inline.

In general the t.t. will render *all* occurances of a particular logical  
element the same way.  When the logical element is not available, ie. as  
with inline lists, the t.t. can not enforce those visual conventions:  
rather, the author's personal predilictions are used.  That means a)  
various (b) forms of c. inline d: lists, for example.

>  >> I'd say reST does more than hint.  ReST is WYSIWYG plaintext
>  >> markup, so it is a very visual medium.
>  >
>  > You kidding me?

(Continue reading)

headers

David Goodger | 2 Sep 2004 23:11

Re: Re: Notation for continued paragraphs?

[David Goodger]
 >>> (a) This is an inline list.  (b) It requires no special markup.
 >>> (c) Is there anything wrong with it?  (d) I haven't seen any
 >>> strenuous objections anyhow.

[David Priest]
 > 2nd attempt: the *logical* structure is lost.  As-is the
 > transformation tools (writers) are unable to recognize that that is
 > a list and render it using whatever visual conventions deemed
 > necessary by the transformation.

There's nothing lost; the parser just doesn't recognize inline lists.
That inline list simply isn't parsed.  The reST parser is an
up-translating parser; it takes implicitly structured input and adds
explicit structure to its output.  In this case nothing was added,
but nothing was lost either.

Transforms and writers don't know about the input or markup.  If
someone wants to (and is able to) define conventions for inline lists,
and add that functionality to the parser, only then will that inline
list be recognized and find its way into the document tree.

My point is, that even without the inline list structure being parsed,
there's enough information implicit in the text that readers will
recognize the list.  That's good enough for me.

If you want to, without modifying the parser (much), you could write
up some text like this:

     .. paragraph::

(Continue reading)

headers

David Abrahams | 2 Sep 2004 22:25

Re: Notation for continued paragraphs?

"David Priest" <priest <at> sfu.ca> writes:

> There are three components to the Docutils workflow.
>
> There is the reST source file, which uses visual markup conventions.
> There is the logical structure derived from that reST file (the
> Docutils  XML output).
> There is the final product derived from that logical structure (the
> LaTeX,  HTML, PDF output created by the transformation tools,
> ie. writers).
>
> The reST visual markup does not dictate the visual appearance of the
> final  product.

But the whole argument is about whether the Docutils XML output (step
2 of 3) should be able to express structures that have block elements
within paragraphs.

--

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

David Goodger | 2 Sep 2004 23:13

Re: Re: Notation for continued paragraphs?

[David Abrahams]
 > But the whole argument is about whether the Docutils XML output
 > (step 2 of 3) should be able to express structures that have block
 > elements within paragraphs.

We got a bit off-topic.

To reiterate: +1, yes, we can add the "compound paragraph" concept to
the Docutils doc model and add a directive to reST.  The details just
remain to be worked out.

--

-- 
David Goodger <http://python.net/~goodger>

headers

David Priest | 2 Sep 2004 22:58

Re: Re: Notation for continued paragraphs?

On Thu, 02 Sep 2004 16:25:00 -0400, David Abrahams  
<dave <at> boost-consulting.com> wrote:

> "David Priest" <priest <at> sfu.ca> writes:
>
>> There are three components to the Docutils workflow.
>>
>> There is the reST source file, which uses visual markup conventions.
>> There is the logical structure derived from that reST file (the
>> Docutils  XML output).
>> There is the final product derived from that logical structure (the
>> LaTeX,  HTML, PDF output created by the transformation tools,
>> ie. writers).
>>
>> The reST visual markup does not dictate the visual appearance of the
>> final  product.
>
> But the whole argument is about whether the Docutils XML output (step
> 2 of 3) should be able to express structures that have block elements
> within paragraphs.

Agreed.  I was addressing what I saw to be a little confusion over reST's  
visual appearance and the visual appearance of the final product.  They  
have nothing to do with each other, except that the logical structure  
produced by the former can be used to differentiate visual styles of the  
other.

I convert Docutils XML using XSL:FO tranformations for rendering to PDF by  
XEP.  I could, if I so chose, render all lists as inline elements.  I am  
not forced by reST to render them vertically.

(Continue reading)

headers

Fred L. Drake, Jr. | 2 Sep 2004 16:18

Re: Re: Notation for continued paragraphs?

On Thursday 02 September 2004 07:54 am, David Abrahams wrote:
 > I think that proves Fred's point.  Some renderers might decide the
 > presentation of a list (inline or block) depending on the size of its
 > items.  "Block-ness" is not an inherent property of a lists, which are
 > logical/structural elements.

Right.  The fact that inline presentations don't make sense for all lists 
doesn't mean that lists can't be inline.  I'm fine if not all semantic 
structures can be readily represented in ReST, but the model shouldn't impose 
the restriction.

The fact is that docutils has long admitted the possibility that non-ReST 
parsers could be used; having a document model with too many artificial 
constraints makes that pointless.  I think this is such a constraint.  The 
Python documentation has long been one of the motivating factors for 
docutils, and I think I've demonstrated that paragraphs containing displays 
are common enough they need to be supported by the model (and preferably in 
the ReST syntax as well).  The use of an explicit paragraph directive for 
this is quite reasonable to avoid guessing about when a bit of text starts a 
new paragraph and when it continues an already "open" paragraph.

  -Fred

--

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.

(Continue reading)

headers

David Goodger | 2 Sep 2004 17:35

Re: Re: Notation for continued paragraphs?

[Fred L. Drake, Jr.]
 > The fact that inline presentations don't make sense for all lists
 > doesn't mean that lists can't be inline.  I'm fine if not all
 > semantic structures can be readily represented in ReST, but the
 > model shouldn't impose the restriction.

I don't think that the model imposes any such restriction.  The
functionality is simply absent at present.  If it becomes necessary to
represent inline lists in the document model, we'll add them.

 > The fact is that docutils has long admitted the possibility that
 > non-ReST parsers could be used; having a document model with too
 > many artificial constraints makes that pointless.  I think this is
 > such a constraint.

If and when another parser is added, I'm sure that the document model
will have to adapt.  Let's not add functionality early.

 > The Python documentation has long been one of the motivating factors
 > for docutils, and I think I've demonstrated that paragraphs
 > containing displays are common enough they need to be supported by
 > the model
...
 > The use of an explicit paragraph directive for this is quite
 > reasonable to avoid guessing about when a bit of text starts a new
 > paragraph and when it continues an already "open" paragraph.

+1.  I like the "compound" wrapper Felix proposed.  If the name
"compound" is not ideal, we should be able to come up with a better
one.  "paragraph" would work, but it may be too specific.  Are there

(Continue reading)

headers

David Abrahams | 2 Sep 2004 20:18

Re: Notation for continued paragraphs?

David Goodger <goodger <at> python.org> writes:

>
> +1.  I like the "compound" wrapper Felix proposed.  If the name
> "compound" is not ideal, we should be able to come up with a better
> one.  "paragraph" would work, but it may be too specific.  Are there
> non-paragraph cases?  We already have an "inline" element for
> arbitrary text markup; this could be an arbitrary body/block-level
> element.

.. block::

??

It's a bit shorter than paragraph, FWIW.

>  > (and preferably in the ReST syntax as well).
>
> A directive will suffice for now.  If suitable specialized syntax is
> invented/discovered, it can be added later.

The directive is good for clarity because the block/paragraph will be
a bit indented... though that does disturb ReST's "plaintext WYSIWYG"
property a bit.

Another possibility that might preserve the WYSIWYG a bit better:

  This is a paragraph with an

  .. parsed-literal::

(Continue reading)

headers

David Goodger | 2 Sep 2004 23:30

Re: Re: Notation for continued paragraphs?

[David Goodger]
 >> +1.  I like the "compound" wrapper Felix proposed.  If the name
 >> "compound" is not ideal, we should be able to come up with a better
 >> one.

[David Abrahams]
 > .. block::
 >
 > ??

Perhaps.  But perhaps we don't actually need an arbitrary
body/block-level element.  An important question to answer here is:

 >> Are there non-paragraph cases?

Looking at the DTD and at docs/ref/doctree.txt, I don't think there
are.  Every other element that directly contains text is either inline
(i.e., occurs within paragraphs) or specialized and atomic (like
literal blocks or titles) and would never be "continued".  Paragraphs
seem to be unique in this sense among the elements.

 > The directive is good for clarity because the block/paragraph will
 > be a bit indented... though that does disturb ReST's "plaintext
 > WYSIWYG" property a bit.

Not enough to worry about.  Such WYSIWYG disturbance is unavoidable
with explicit markup.

 > Another possibility that might preserve the WYSIWYG a bit better:
 >

(Continue reading)

headers

Felix Wiemann | 10 Sep 2004 20:11

Re: Notation for continued paragraphs?

David Goodger wrote:

> So far, the directive name contenders are:
>
> * compound

Good.

> * paragraph

Bad, because it migles the concepts 'single paragraph' / 'compound
paragraph'.

> * block

Bad, because we're going to add is not a generic block-level-container
like HTML's DIV, but a compound paragraph.

> I like "compound_paragraph" for the element name, but there could be
> something better.

I think "compound_paragraph" is good (especially better than
"compound"), because its name makes it obvious that it's block-level,
and if we need to add an inline-element like "compound_text" later,
"compound_paragraph" is clearly more distinguishable than "compound".

--

-- 
When replying to my email address, please ensure
that the mail header contains 'Felix Wiemann'.

(Continue reading)

headers

Aahz | 3 Sep 2004 00:41

Re: Re: Notation for continued paragraphs?

On Thu, Sep 02, 2004, David Goodger wrote:
>
> So far, the directive name contenders are:
> 
> * compound

+0

> * paragraph

-1

> * block

+0
--

-- 
Aahz (aahz <at> pythoncraft.com)           <*>         http://www.pythoncraft.com/

"To me vi is Zen.  To use vi is to practice zen.  Every command is a
koan.  Profound to the user, unintelligible to the uninitiated.  You
discover truth everytime you use it."  --reddy <at> lion.austin.ibm.com

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

David Goodger | 1 Sep 2004 18:42

Re: Re: Notation for continued paragraphs?

[Felix Wiemann]
 > The reason why it's probably a bad idea is that the structure above
 > mixes block-level elements (literal block) and inline-level elements
 > (text).

Yes.

 > Thus it makes trouble when using the HTML writer.

Yes, among others.

 > What about:
 >
 > <compound>
 >     <paragraph>
 >         foo bar
 >     <literal_block>
 >         mumble
 >     <paragraph>
 >         baz

Yes, that could work.

 > This would allow writers which don't (need to) support
 > paragraph-continuation to remain almost unchanged while requiring
 > little modification to, for example, the LaTeX writer.  And it would
 > allow the DocBook writer to write the document without doing any
 > transformation, wouldn't it?

For true compound paragraph DocBook output, a transformation would

(Continue reading)

headers

David Abrahams | 1 Sep 2004 17:44

Re: Notation for continued paragraphs?

Felix Wiemann <Felix.Wiemann <at> gmx.net> writes:

> What about:
>
> <compound>
>     <paragraph>
>         foo bar
>     <literal_block>
>         mumble
>     <paragraph>
>         baz
>
> This would allow writers which don't (need to) support
> paragraph-continuation to remain almost unchanged while requiring little
> modification to, for example, the LaTeX writer.  And it would allow the
> DocBook writer to write the document without doing any transformation,
> wouldn't it?

I think I've been suggesting something like:

<paragraph>
    <text>
        foo bar
    <literal_block>
        mumble
    <text>
        baz

Is that very different in spirit?

(Continue reading)

headers

David Goodger | 1 Sep 2004 19:02

Re: Re: Notation for continued paragraphs?

(Replying to multiple messages from David A.)

[David Goodger]
 >> Practically though, mixed text and block-level elements are *far*
 >> more difficult to implement.  At some point, the compound structure
 >> has to be flattened.

[David Abrahams]
 > Without some explanation, it's hard to see why that's true.
 > Especially since some output formats *don't* require that
 > flattening.

Eventually, they all do, at some point in the processing.  Document
models are at different conceptual levels, where the lowest level is
that of typography (glyphs and page/screen coordinates).  I'd say that
the Docutils model is at a higher level than HTML's model, higher than
TeX's model, but (in some ways) it is lower than DocBook's model.
Very high-level models may support compound paragraphs, but
lower-level ones don't.  In the end, a document becomes a sequence of
blocks of text, with structure suggested by typeface, size, style,
indentation, borders, etc.

 >>> Recursion is difficult for you?
 >>
 >> Please drop the sarcasm.
 >
 > I don't mean to be sarcastic; sorry if it came off that way.

I guess I'd assumed you'd seen enough Docutils code to realize that
recursion is an essential technique used ubiquitously in Docutils'

(Continue reading)

headers

David Priest | 1 Sep 2004 16:50

Re: Re: Notation for continued paragraphs?

I'm with David Goodger on this one.  Things inside paragraphs are inline  
elements.  Allowing block elements to be nested inside paragraphs opens a  
nasty can of worms and is not at all advisable.  I think we'll discover  
that there are many, *many* problems with such an idea, and that it'll  
come back to bite us in the ass.

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

David Abrahams | 1 Sep 2004 18:16

Re: Notation for continued paragraphs?

"David Priest" <priest <at> sfu.ca> writes:

> I'm with David Goodger on this one.  Things inside paragraphs are
> inline  elements.  Allowing block elements to be nested inside
> paragraphs opens a  nasty can of worms and is not at all
> advisable.  

I have to agree with Fred that this rings loudly of FUD.  I've heard
numerous references to cans of worms and insanity but nobody has
offered a single detail about why it's actually problematic.

--

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

Felix Wiemann | 1 Sep 2004 17:06

Re: Notation for continued paragraphs?

David Priest wrote:

> I'm with David Goodger on this one.  Things inside paragraphs are
> inline elements.  Allowing block elements to be nested inside
> paragraphs opens a nasty can of worms and is not at all advisable.

As you replied to my posting: I did say exactly this (or I tried to, at
least  ).

What I proposed was a new 'compound' element, containing only
block-level elements but suggesting that they belong together.

--

-- 
When replying to my email address, please ensure
that the mail header contains 'Felix Wiemann'.

http://www.ososo.de/

-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click

headers

David Goodger | 1 Sep 2004 16:01

Re: Notation for continued paragraphs?

[David Goodger]
 >> <paragraph>
 >>      some text
 >>      <literal_block>
 >>          literal text
 >>      more paragraph text
 >>
 >> Note that there's a block-level element, <literal_block>, embedded
 >> in #PCDATA.  That structure is, IMO, insane.

[David Abrahams]
 > Looks perfectly sane to me.

Note the "IMO".  You're welcome to your opinion too -- I just don't
share it.

The parse tree above is making implied context-sensitive switches
between fundamentally different levels of structure.  Compare to:

<paragraph>
      some text
      <emphasis>
          some inline text
      more paragraph text

Structurally, they're exactly the same.  Practically though, mixed text
and block-level elements are *far* more difficult to implement.  At
some point, the compound structure has to be flattened.  Any marginal
(and, IMO, questionable) gain from compound paragraphs just isn't
worth the massive pain.

(Continue reading)

headers

David Abrahams | 1 Sep 2004 16:39

Re: Notation for continued paragraphs?

David Goodger <goodger <at> python.org> writes:

> [David Goodger]
>  >> <paragraph>
>  >>      some text
>  >>      <literal_block>
>  >>          literal text
>  >>      more paragraph text
>  >>
>  >> Note that there's a block-level element, <literal_block>, embedded
>  >> in #PCDATA.  That structure is, IMO, insane.
>
> [David Abrahams]
>  > Looks perfectly sane to me.
>
> Note the "IMO".  You're welcome to your opinion too -- I just don't
> share it.
>
> The parse tree above is making implied context-sensitive switches
> between fundamentally different levels of structure.  Compare to:
>
> <paragraph>
>       some text
>       <emphasis>
>           some inline text
>       more paragraph text
>
> Structurally, they're exactly the same.  Practically though, mixed text
> and block-level elements are *far* more difficult to implement.  At
> some point, the compound structure has to be flattened.

(Continue reading)

headers

Fred L. Drake, Jr. | 1 Sep 2004 17:40

Re: Notation for continued paragraphs?

On Wednesday 01 September 2004 10:39 am, David Abrahams wrote:
 > Sorry, I don't know what #PCDATA means.

"#PCDATA" is SGML/XML speak for "a bunch of text of text".  More detail than 
that isn't relevant here.

 > It seems easy enough to define "paragraph" to be a structural element
 > rather than a text element.  Just like a section, a chapter, or
 > whatever.

As it should be.

 > > Do you have any real examples of unrepresentable cases?
 > > If so, please show them.
 >
 > No.  If I had any real examples, I would probably need that
 > capability.  I could perhaps conjure something realistic, but it
 > wouldn't be real.

Lots of things can be placed in paragraphs that the HTML-centric view as 
"block" elements.  Ordered and unordered lists commonly fall into this 
category; DocBook pretty much gets them right, but HTML doesn't support the 
model.

 > I understand.  Just to be clear, I don't think compound paragraphs
 > are needed, or neccessarily realistic.  I *do* think textual block
 > elements within a paragraph are probably needed.

I still don't know what a "compound" paragraph is.  It *sounds* like FUD.

(Continue reading)

headers

David Abrahams | 1 Sep 2004 18:02

Re: Notation for continued paragraphs?

"Fred L. Drake, Jr." <fdrake <at> acm.org> writes:

> On Wednesday 01 September 2004 10:39 am, David Abrahams wrote:
>  > Sorry, I don't know what #PCDATA means.
>
> "#PCDATA" is SGML/XML speak for "a bunch of text of text".  More
> detail than that isn't relevant here.

Thanks.

>  > It seems easy enough to define "paragraph" to be a structural
>  > element rather than a text element.  Just like a section, a
>  > chapter, or whatever.
>
> As it should be.

:^)  Semantics uber-alles!

>  > > Do you have any real examples of unrepresentable cases?
>  > > If so, please show them.
>  >
>  > No.  If I had any real examples, I would probably need that
>  > capability.  I could perhaps conjure something realistic, but it
>  > wouldn't be real.
>
> Lots of things can be placed in paragraphs that the HTML-centric
> view as "block" elements.  Ordered and unordered lists commonly fall
> into this category; DocBook pretty much gets them right, but HTML
> doesn't support the model.

(Continue reading)

headers

David Goodger | 1 Sep 2004 19:29

Re: Notation for continued paragraphs?

[David Abrahams]
 >>> It seems easy enough to define "paragraph" to be a structural
 >>> element rather than a text element.  Just like a section, a
 >>> chapter, or whatever.

[Fred L. Drake, Jr.]
 >> As it should be.

[David Abrahams]
 > :^)  Semantics uber-alles!

As I said, controversial.  It's one of the "religious wars" of
structured document systems.

[Fred L. Drake, Jr.]
 > Lots of things can be placed in paragraphs that the HTML-centric
 > view as "block" elements.  Ordered and unordered lists commonly fall
 > into this category;

[OT: That's another religious issue.  I cringe whenever I hear
"unordered list".  What's unordered about a bullet list?  I think most
authors would scream bloody murder if the order of items in their
bullet lists was changed.  They're *implicitly* ordered, not
*un*-ordered.]

 > DocBook pretty much gets them right,

In your opinion.  Not in mine.  I think DocBook screwed the pooch on
this one.

(Continue reading)