You can subscribe to this list here.
2002 |
Jan
|
Feb
|
Mar
|
Apr
(5) |
May
(27) |
Jun
(22) |
Jul
(72) |
Aug
(82) |
Sep
(86) |
Oct
(138) |
Nov
(100) |
Dec
(62) |
---|---|---|---|---|---|---|---|---|---|---|---|---|
2003 |
Jan
(122) |
Feb
(147) |
Mar
(92) |
Apr
(82) |
May
(101) |
Jun
(153) |
Jul
(37) |
Aug
(34) |
Sep
(46) |
Oct
(46) |
Nov
(6) |
Dec
(38) |
2004 |
Jan
(64) |
Feb
(81) |
Mar
(36) |
Apr
(194) |
May
(329) |
Jun
(272) |
Jul
(68) |
Aug
(74) |
Sep
(150) |
Oct
(57) |
Nov
(62) |
Dec
(63) |
2005 |
Jan
(78) |
Feb
(30) |
Mar
(137) |
Apr
(78) |
May
(54) |
Jun
(122) |
Jul
(72) |
Aug
(110) |
Sep
(80) |
Oct
(75) |
Nov
(125) |
Dec
(79) |
2006 |
Jan
(100) |
Feb
(15) |
Mar
(41) |
Apr
(67) |
May
(30) |
Jun
(11) |
Jul
(14) |
Aug
(22) |
Sep
(20) |
Oct
(14) |
Nov
(11) |
Dec
(15) |
2007 |
Jan
(17) |
Feb
(16) |
Mar
(35) |
Apr
(21) |
May
(33) |
Jun
(50) |
Jul
(12) |
Aug
(7) |
Sep
(2) |
Oct
(6) |
Nov
(5) |
Dec
(2) |
2008 |
Jan
(14) |
Feb
(20) |
Mar
(35) |
Apr
(9) |
May
(57) |
Jun
(21) |
Jul
(42) |
Aug
(4) |
Sep
(13) |
Oct
(76) |
Nov
(40) |
Dec
(55) |
2009 |
Jan
(26) |
Feb
(15) |
Mar
(3) |
Apr
(67) |
May
(32) |
Jun
(39) |
Jul
(59) |
Aug
(31) |
Sep
(59) |
Oct
(64) |
Nov
(21) |
Dec
(10) |
2010 |
Jan
(21) |
Feb
(3) |
Mar
(116) |
Apr
(33) |
May
(9) |
Jun
(28) |
Jul
(21) |
Aug
(23) |
Sep
(146) |
Oct
(70) |
Nov
(31) |
Dec
(57) |
2011 |
Jan
(33) |
Feb
(22) |
Mar
(11) |
Apr
(21) |
May
(51) |
Jun
(47) |
Jul
(35) |
Aug
(26) |
Sep
(25) |
Oct
(34) |
Nov
(61) |
Dec
(51) |
2012 |
Jan
(75) |
Feb
(31) |
Mar
(26) |
Apr
(16) |
May
(24) |
Jun
(24) |
Jul
(31) |
Aug
(46) |
Sep
(36) |
Oct
(28) |
Nov
(37) |
Dec
(21) |
2013 |
Jan
(16) |
Feb
(56) |
Mar
(31) |
Apr
(44) |
May
(45) |
Jun
(29) |
Jul
(38) |
Aug
(18) |
Sep
(12) |
Oct
(16) |
Nov
(21) |
Dec
(11) |
2014 |
Jan
(13) |
Feb
(14) |
Mar
(28) |
Apr
(7) |
May
(72) |
Jun
(33) |
Jul
(21) |
Aug
(1) |
Sep
(6) |
Oct
(14) |
Nov
(18) |
Dec
(22) |
2015 |
Jan
(23) |
Feb
(108) |
Mar
(76) |
Apr
(114) |
May
(60) |
Jun
(9) |
Jul
(8) |
Aug
(9) |
Sep
(42) |
Oct
(9) |
Nov
|
Dec
(7) |
2016 |
Jan
(6) |
Feb
(15) |
Mar
(7) |
Apr
|
May
(33) |
Jun
(3) |
Jul
(19) |
Aug
(12) |
Sep
(6) |
Oct
(16) |
Nov
(17) |
Dec
(125) |
2017 |
Jan
(66) |
Feb
(98) |
Mar
(29) |
Apr
(32) |
May
(63) |
Jun
(98) |
Jul
(26) |
Aug
(33) |
Sep
(19) |
Oct
(77) |
Nov
(31) |
Dec
(27) |
2018 |
Jan
(32) |
Feb
(11) |
Mar
(5) |
Apr
(12) |
May
(4) |
Jun
(9) |
Jul
(9) |
Aug
(13) |
Sep
(11) |
Oct
(6) |
Nov
(23) |
Dec
(2) |
2019 |
Jan
(26) |
Feb
(12) |
Mar
(20) |
Apr
(18) |
May
(7) |
Jun
(22) |
Jul
(81) |
Aug
(129) |
Sep
(32) |
Oct
(18) |
Nov
(11) |
Dec
(44) |
2020 |
Jan
(19) |
Feb
(10) |
Mar
(38) |
Apr
(4) |
May
(9) |
Jun
(15) |
Jul
(29) |
Aug
(79) |
Sep
(12) |
Oct
(22) |
Nov
(10) |
Dec
(37) |
2021 |
Jan
(16) |
Feb
(14) |
Mar
(20) |
Apr
(100) |
May
(21) |
Jun
(19) |
Jul
(13) |
Aug
(13) |
Sep
(37) |
Oct
(112) |
Nov
(64) |
Dec
(22) |
2022 |
Jan
(209) |
Feb
(38) |
Mar
(11) |
Apr
(10) |
May
(55) |
Jun
(104) |
Jul
(35) |
Aug
(10) |
Sep
(21) |
Oct
(21) |
Nov
(50) |
Dec
(12) |
2023 |
Jan
(6) |
Feb
|
Mar
(3) |
Apr
(41) |
May
(48) |
Jun
(9) |
Jul
(6) |
Aug
(25) |
Sep
(3) |
Oct
(22) |
Nov
(56) |
Dec
(12) |
2024 |
Jan
(5) |
Feb
(5) |
Mar
(38) |
Apr
(62) |
May
(12) |
Jun
(10) |
Jul
(3) |
Aug
(59) |
Sep
(1) |
Oct
|
Nov
|
Dec
|
From: David G. <go...@py...> - 2004-09-02 21:30:40
|
[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: > > This is a paragraph with an > > .. parsed-literal:: > :embedded: > > embedded-display > > inside it. -1. Too much magic. So far, the directive name contenders are: * compound * paragraph * block I like "compound_paragraph" for the element name, but there could be something better. -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-09-02 21:15:13
|
[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> |
From: David G. <go...@py...> - 2004-09-02 21:11:23
|
[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:: She asked me to stop at the store and pick up 1) a quart of milk 2) a loaf of bread 3) a stick of butter on the way home. You could modify a Writer to render that list in-line. We'll gloss over the complexities, like inserting an "and" between items 2 & 3. I wouldn't want to do that, but that's just me. ;-) > Then by your own words, reST has nothing whatsoever to do with > WYSIWYG. "nothing whatsoever to do with WYSIWYG" on the **output** side, maybe. Everything to do with WYSIWYG **input**. ReST is WYSIWYG plaintext markup. Says so at the top of the homepage. > The reST visual markup does not dictate the visual appearance of the > final product. Correct. > output may be informed by reST but is not mandated by reST That's a good way of putting it. -- David Goodger <http://python.net/~goodger> |
From: David P. <pr...@sf...> - 2004-09-02 20:56:54
|
On Thu, 02 Sep 2004 16:25:00 -0400, David Abrahams <da...@bo...> wrote: > "David Priest" <pr...@sf...> 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. I could also use ..class: to add a "inline" attribute to select reST vertical lists. In the subsequent transformation, I could then differentiate vertical and inline lists and render them as is visually appropriate. Or not. My final product output may be informed by reST but is not mandated by reST. As for block elements within paragraphs: I am now agnostic. In my technical documentation there are a good number of instances where I could make use of block elements within a paragraph. That said, I've yet to encounter a situation in which I can't work around Docutils'/reST's limitations on such. |
From: David P. <pr...@sf...> - 2004-09-02 20:40:32
|
On Thu, 02 Sep 2004 16:25:43 -0400, David Abrahams <da...@bo...> wrote: > David Goodger <go...@py...> 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 |
From: David A. <da...@bo...> - 2004-09-02 20:30:25
|
"David Priest" <pr...@sf...> 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 |
From: David A. <da...@bo...> - 2004-09-02 20:26:08
|
David Goodger <go...@py...> 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 |
From: David P. <pr...@sf...> - 2004-09-02 20:06:36
|
> [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? > > 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 > its interface to the internal representation, the doc tree. ReST has > nothing whatsoever to do with the output or its rendering. Then by your own words, reST has nothing whatsoever to do with WYSIWYG. The visual appearance of a reST file is *not* indicative of the visual appearance of the final product. As described above, despite the reST visual of a vertical list, the final product may render an inline list. reST appearance != product appearance. > Yes, of course that's true. But that's at the output/writer end. > What I'm saying is that there's a strong link between the visual > nature of the markup and the internal representation (the doc tree), > at the parser end. That's why reST is a limited markup medium; > there's only so far you can go with WYSIWYG implicit markup. The more > that explicit markup is necessary to get the job done, the less > incentive there is to use reST in the first place. Agreed. 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. |
From: David G. <go...@py...> - 2004-09-02 19:39:38
|
[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> |
From: David G. <go...@py...> - 2004-09-02 19:30:37
|
(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 its interface to the internal representation, the doc tree. ReST has nothing whatsoever to do with the output or its rendering. > My XSL:FO and HTML's CSS and LaTeX's whatever can make the rendered > file look like whatever we, the publishers, want it to look like, > with complete disregard for all the visual hinting ReST provides. Yes, of course that's true. But that's at the output/writer end. What I'm saying is that there's a strong link between the visual nature of the markup and the internal representation (the doc tree), at the parser end. That's why reST is a limited markup medium; there's only so far you can go with WYSIWYG implicit markup. The more that explicit markup is necessary to get the job done, the less incentive there is to use reST in the first place. > ReST's markup is logical markup that happens to make sense visually. It doesn't just "happen" to make sense visually. There's nothing accidental or coincidental about it. It's by design. That's its strength. And its weakness. > It is *not* the determining factor in the visual appearance of the > final rendered product. Very true. Never said it was (I hope ;-). I hope I've expressed myself more clearly this time. -- David Goodger <http://python.net/~goodger> |
From: David A. <da...@bo...> - 2004-09-02 18:19:01
|
David Goodger <go...@py...> 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:: :embedded: embedded-display inside it. This is just about input syntax: it could have the same document structure we've been discussing for the "surrounding paragraph directive." -- Dave Abrahams Boost Consulting http://www.boost-consulting.com |
From: David A. <da...@bo...> - 2004-09-02 18:05:56
|
"David Priest" <pr...@sf...> writes: > On Thu, 02 Sep 2004 10:19:30 -0400, David Goodger <go...@py...> > 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 http://www.boost-consulting.com |
From: Aahz <aa...@py...> - 2004-09-02 17:33:30
|
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 (aa...@py...) <*> 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." --...@li... |
From: David G. <go...@py...> - 2004-09-02 16:32:45
|
[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. full-stops? That depends on natural language features, a level of control that I doubt Docutils will ever aspire to. Or the style of the enumerators, "(a)" vs. "a)"? Docutils could do that. > ReST's markup > a. Absolutely determines logical structure. It would be an > uncommon Docutils writer that makes deep changes to the structure. True. > b. Only *hints* at visual structure. It would be an uncommon > renderer that precisely replicates the ReST visual layout. I'd say reST does more than hint. ReST is WYSIWYG plaintext markup, so it is a very visual medium. -- David Goodger <http://python.net/~goodger> |
From: David P. <pr...@sf...> - 2004-09-02 16:04:07
|
On Thu, 02 Sep 2004 11:34:10 -0400, David Goodger <go...@py...> 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. |
From: David G. <go...@py...> - 2004-09-02 15:36:10
|
[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 non-paragraph cases? We already have an "inline" element for arbitrary text markup; this could be an arbitrary body/block-level element. > (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. -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-09-02 15:36:09
|
[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? -- David Goodger <http://python.net/~goodger> |
From: David P. <pr...@sf...> - 2004-09-02 15:09:57
|
On Thu, 02 Sep 2004 10:19:30 -0400, David Goodger <go...@py...> 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 |
From: David G. <go...@py...> - 2004-09-02 14:20:38
|
[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 think that's going too far, especially for Docutils. Document models must draw the line somewhere, and say "beyond this limit, the content needs no further markup". The document model for Docutils is heavily influenced by the needs and limitations of reStructuredText, so that limit may be reached earlier than for other, more complex models. The Docutils document model makes a very clear distinction between structural, block/body, and inline elements, as described in <http://docutils.sf.net/docs/ref/doctree.html>. -- David Goodger <http://python.net/~goodger> |
From: Fred L. D. Jr. <fd...@ac...> - 2004-09-02 14:18:32
|
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> |
From: David A. <da...@bo...> - 2004-09-02 11:55:21
|
David Goodger <go...@py...> 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 |
From: David G. <go...@py...> - 2004-09-02 04:50:58
|
[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. It's not simply a matter of stylesheet-fiddling. > If instead we think of the model as containing structural and > textual elements instead of block and inline elements, perhaps we > can avoid encumbering the model with presentational assumptions. I think certain basic presentational assumptions are unavoidable and intrinsic. A paragraph *is* a block element by definition; it cannot be rendered in any other way and remain a paragraph. -- David Goodger <http://python.net/~goodger> |
From: Fred L. D. Jr. <fd...@ac...> - 2004-09-02 03:49:01
|
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: ----------------------------------------------------------------------------- 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. ----------------------------------------------------------------------------- If instead we think of the model as containing structural and textual elements instead of block and inline elements, perhaps we can avoid encumbering the model with presentational assumptions. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> |
From: David G. <go...@py...> - 2004-09-02 03:11:18
|
[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 still have to be done; there would only be one paragraph, with the literal block inside. But a <compound> wrapper would make it easier -- no lookahead required. -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-09-01 17:30:13
|
[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. ;-) > but HTML doesn't support the model. That is a fact though. > I still don't know what a "compound" paragraph is. It *sounds* like > FUD. My definitions: compound paragraph A paragraph containing embedded block-level elements such as literal blocks, tables, lists, etc., in addition to directly containing text and inline elements. Compound paragraphs are typically rendered as multiple distinct text blocks. simple paragraph A paragraph which directly contains only text and inline elements (like "emphasis"). Simple paragraphs can always be rendered in a single contiguous text block. > There are many cases where structure exists within a paragraph > (lists, example code fragments, etc.); whether those are presented > as block-like displays is up to the presentation, not the model. The model has to make a choice of representation. For Docutils, I've chosen to represent elements as closely to their rendered form as possible, whenever possible. > Here's a real example of a paragraph containing a parsed-literal (in > docutils terms). ... > In spite of the command-line display in the middle, this is clearly > a single paragraph. > > -------------------------------------------------------------------- > The Python interpreter is usually installed as /usr/local/bin/python > on those machines where it is available; putting /usr/local/bin in > your Unix shell's search path makes it possible to start it by > typing the command > > python > > to the shell. Since the choice of the directory where the > interpreter lives is an installation option, other places are > possible; check with your local Python guru or system > administrator. (E.g., /usr/local/python is a popular alternative > location.) > -------------------------------------------------------------------- Let's take a look at this example. How do we, as readers, *determine* that it's a single paragraph? By the fact that a sentence begun in the first part actually ends in the last. The hints provided are that the first fragment does not end with a period, the final fragment begins with a lower-case letter, and the sentence "reads well" across fragments. But look at the TeX source. It doesn't tell us anything. Sentences and ideas are not representable in the Docutils document model, nor in most document models. Let's re-write that example a bit: The Python interpreter is usually installed as /usr/local/bin/python on those machines where it is available; putting /usr/local/bin in your Unix shell's search path makes it possible to start it by typing the following command to the shell: python Since the choice of the directory where the interpreter lives is an installation option, other places are possible; check with your local Python guru or system administrator. (E.g., /usr/local/python is a popular alternative location.) Now, are these a single paragraph with an embedded literal block, or are they three separate elements? This is a reading comprehension issue, and is beyond the Docutils document model. The DocBook document model allows compound paragraphs, but Docutils is not DocBook, and never will be. DocBook is great, very useful, but not perfect. Adapting human-readable documents (developed over millennia of human history) to tree-shaped data structures is an exercise in compromise. They mostly fit, but not completely. [David Abrahams] > 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. I'm speaking from practical experience, not theory. I've tried to explain as best as I can, and if that's not convincing, then I'm sorry. All I can suggest is that if you work in documentation systems for a while, you may understand the issues better. I ain't no FUD-slinger! Them's fightin' words. ;-) -- David Goodger <http://python.net/~goodger> |