Menu
▾
▴
docutils-develop
|
From: Jarno E. <el...@ik...> - 2004-03-25 12:17:10
|
Hi, Why is it that "(ERROR/3) Section may not end with a transition"? I think it's probably the most usual places where you might want to use one: Official statement about XYZ ============================ blah blah blah blah Conclusions ----------- blah blah -------------------------------------- Differing opinion ================= blah blah blah blah This example is a simplification of one software patent document that I just edited. I know it can be worked around by adding an empty comment after the separator line, but I don't understand why it should be necessary: Conclusions ----------- blah blah -------------------------------------- .. Differing opinion ================= blah blah blah blah - Jarno |
|
From: David G. <go...@py...> - 2004-03-31 21:57:40
|
Jarno Elonen wrote:
> Why is it that "(ERROR/3) Section may not end with a transition"?
From the spec:
Instead of subheads, extra space or a type ornament between
paragraphs may be used to mark text divisions or to signal
changes in subject or emphasis.
(The Chicago Manual of Style, 14th edition, section 1.80)
Transitions are commonly seen in novels and short fiction, as a
gap spanning one or more lines, with or without a type ornament
such as a row of asterisks. Transitions separate other body
elements. A transition should not begin or end a section or
document, nor should two transitions be immediately adjacent.
-- http://docutils.sf.net/spec/reStructuredText.html#transitions
> I think it's probably the most usual places where you might
> want to use one:
>
> Official statement about XYZ
> ============================
>
> blah blah
> blah blah
>
> Conclusions
> -----------
>
> blah blah
>
> --------------------------------------
>
> Differing opinion
> =================
>
> blah blah
> blah blah
That's not a "transition" (by my definition), that's a horizontal line
used as a design element. I don't understand the semantic role of the
line. What does it mean?
I'd suggest inserting an image of a line.
> This example is a simplification of one software patent document
> that I just edited. I know it can be worked around by adding an
> empty comment after the separator line, but I don't understand why
> it should be necessary:
Such usage would be abuse. It's only an accident that a transition
renders as a horizontal rule in HTML. In other output, it may render
as a large vertical gap or as three asterisks ("* * *").
--
David Goodger http://python.net/~goodger
For hire: http://python.net/~goodger/cv
|
|
From: Jarno E. <el...@ik...> - 2004-03-31 22:26:25
|
> I don't understand the semantic role of the
> line. What does it mean?
It separates two sub-documents (the statement and a differing opinion).
> Such usage would be abuse. It's only an accident that a transition
> renders as a horizontal rule in HTML. In other output, it may render
> as a large vertical gap or as three asterisks ("* * *").
I see. It's a bit misleading that the markup looks like a horizontal line,
though.
- Jarno
|
|
From: Felix W. <fel...@os...> - 2004-04-05 22:59:59
|
Jarno Elonen wrote:
>> I don't understand the semantic role of the
>> line. What does it mean?
>
> It separates two sub-documents (the statement and a differing
> opinion).
What is bad about that? If you have several headings per part, that
would IMO be a valid reason to use a transition at the end of a section.
Heading 1
=========
foo
Heading 2
=========
foo2
-------------------
Heading 3
=========
bar
Heading 4
=========
bar2
Even if the transition is rendered as a vertical gap, it still makes
sense.
>> Such usage would be abuse. It's only an accident that a transition
>> renders as a horizontal rule in HTML. In other output, it may
>> render as a large vertical gap or as three asterisks ("* * *").
What about simply documentating that? I think that it is not a good
idea to detain the user from doing that, if he really needs it.
--
http://www.ososo.de/
|
|
From: David G. <go...@py...> - 2004-04-06 00:32:00
|
[David Goodger]
>>> I don't understand the semantic role of the
>>> line. What does it mean?
[Jarno Elonen]
>> It separates two sub-documents (the statement and a differing
>> opinion).
[Felix Wiemann]
> What is bad about that? If you have several headings per part, that
> would IMO be a valid reason to use a transition at the end of a
> section.
>
> Even if the transition is rendered as a vertical gap, it still makes
> sense.
At first I thought, sure, we could loosen the document model and rip
out the code that prevents such usage. No big loss.
But on further reflection, I realized that the real problem is that in
the example given,
Heading 1
=========
foo
Heading 2
=========
foo2
-------------------
Heading 3
=========
bar
Heading 4
=========
bar2
the parse tree would look like this:
<document>
<section>
<title>
Heading 1
<paragraph>
foo
<section>
<title>
Heading 2
<paragraph>
foo2
<transition>
<section>
<title>
Heading 3
<paragraph>
bar
<section>
<title>
Heading 4
<paragraph>
bar2
Notice where the <transition> ends up? It's *not* between sections,
it's in the second section ("Heading 2"). To make it clearer, I'll
replace <title>s and <paragraph>s with "...":
<document>
<section>
...
<section>
...
<transition>
<section>
...
<section>
...
A transition, by definition, must come between two things. It cannot
begin or end a section. So the document model would be wrong!
The intention seems to be this:
<document>
<section>
<section>
<transition>
<section>
<section>
That might make sense, but there's no way to tell the parser that the
transition should be one level higher in the document tree. We could
add a directive, say "section-transition" [*]_, which could end the
previous section and insert a transition. A section would *have* to
follow such a directive though.
.. [*] Or a "section-end" directive, followed by a regular transition
construct.
>>> Such usage would be abuse. It's only an accident that a
>>> transition renders as a horizontal rule in HTML. In other output,
>>> it may render as a large vertical gap or as three asterisks ("* *
>>> *").
>
> What about simply documentating that?
It is: <http://docutils.sf.net/spec/doctree.html#transition>.
> I think that it is not a good idea to detain the user from doing
> that, if he really needs it.
But it's wrong, and it makes no sense to allow it.
--
David Goodger http://python.net/~goodger
For hire: http://python.net/~goodger/cv
|
|
From: David G. <go...@py...> - 2004-04-06 00:59:11
|
David Goodger wrote: [David Goodger] > The intention seems to be this: > > <document> > <section> > <section> > <transition> > <section> > <section> > > That might make sense, but there's no way to tell the parser that > the transition should be one level higher in the document tree. We > could add a directive, say "section-transition" [*]_, which could > end the previous section and insert a transition. Or, I suppose, a transition immediately preceding a section title could be interpreted as occurring outside of the section it's being parsed in. The context would obviate the need for a special directive. Worth thinking about. > A section would *have* to follow such a directive though. This is still true. It doesn't make sense for a transition to begin or end a container. -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv |
|
From: David G. <go...@py...> - 2004-04-01 17:02:38
|
Marcelo Huerta wrote: > As I would need a similar construct, I ask: Is the only way to get it > to resort to raw HTML? You could always insert an image of a horizontal line. It seems to me that this is a design issue. You could add use the "class" directive on the section titles you want lines *above*, and handle it in CSS. -- David Goodger |
Thanks for helping keep SourceForge clean.
X