From: Moore, P. <Pau...@at...> - 2003-05-22 14:07:43
|
From: David Goodger [mailto:go...@py...] > I don't see how we can eliminate case 1. We need case 1 to set > the "class" attribute on a section, because a section cannot be > the content of a directive. However, a paragraph cannot contain a > directive, therefore case 2 is needed. Only case 3 is redundant. I think the biggest problem I have with this (and maybe it explains William's concern as well) is that the proposal is *highly* indentation sensitive. Specifically, the cases only differ in the indentation of the directive. Look at the following:: This is an example of case 1. I'm currently writing a simple paragraph, and nothing much is going to affect that, so that's OK, at least. .. class:: special This blockquote element is of class "special". Well, I guess that's OK. This looks pretty much identical, but is an example of case 2. .. class:: special Hang on - this isn't a blockquote any more! It's still class "special", but where did the blockquote go? I never changed this paragraph! Oh, hang on. I lost the indentation in the directive above. This looks pretty much identical to case 2 above, but is *now* an example of case 3. .. class:: special Hang on - this isn't a blockquote any more! It's still class "special", but where did the blockquote go? I never changed this paragraph! Oh, hang on. I lost the indentation in the directive above. Oy! It just became a blockquote again. I still didn't change the above paragraph, but I added a second one below. It's the changing status of the paragraph (non-technical sense) just after the directive which makes all of this messy. And this is with me carefully using 4-space indents everywhere. If the indentation is messy or mistaken, it's *very* easy to lose any idea of the real intent. Hence your question to William, of whether he had got his indentation right... It's arguable that all of this is caused by the fact that the blockquote element is defined *solely* by its indentation. That's been the case since day 1, but I'd have to admit to having no real use case for blockquotes, so the only effect of this on me, is to make the indentation rules more fragile than they should be. I assume that there's no chance, at this late stage, of deprecating the indentation-only blockquote element in favour of an explicit "blockquote" directive :-( Back to reality - I think the class directive is probably OK when used in conjunction with things *other* than blockquotes. So maybe it's just your choice of example that is the problem. Could you recast your examples without blockquotes? Alternatively, why can't the "class" directive simply be a simple directive allowing no content, which sets the class of the immediately following element. Then you have:: Case 1, a section head with a class attibute .. class:: special This has class special ---------------------- Blah, blah Case 2, a paragraph with a special class .. class:: special It's *this* paragraph that has the special class, not the one before the directive. As this is regular, this should be no big deal. Of course, this paragraph does not have the class. No big deal, if you want multiple paragraphs with a special class, you should probably be writing a custom directive anyway. Otherwise, just repeat the class directive. But how do we get a blockquote with a class? Easy - same as for the normal rule for following a contentless directive with indented text, just do the following .. class:: special .. This is a blockquote, with class special. See the empty comment, which is how the reST spec says you should separate indented = text from a contentless directive. This is still the first element after the directive (comments don't count) so the class applies here as we require. How does this look? It feels *far* more regular, and easy to remember, than your suggestion. Paul |
From: Aahz <aa...@py...> - 2003-05-23 02:36:49
|
On Thu, May 22, 2003, Moore, Paul wrote: > > It's arguable that all of this is caused by the fact that the > blockquote element is defined *solely* by its indentation. That's > been the case since day 1, but I'd have to admit to having no real > use case for blockquotes, so the only effect of this on me, is to > make the indentation rules more fragile than they should be. I > assume that there's no chance, at this late stage, of deprecating > the indentation-only blockquote element in favour of an explicit > "blockquote" directive :-( Speaking as someone who does use block quotes, I'd be highly amenable to requiring block quotes be a directive. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93 |
From: David G. <go...@py...> - 2003-05-23 18:29:16
|
Aahz wrote: > Speaking as someone who does use block quotes, I'd be highly > amenable to requiring block quotes be a directive. For the sake of argument, let's say that block quotes were implemented only with a directive:: .. block-quote:: Block quote text here. What then would an indented block of text mean? For example:: Ordinary, unindented paragraph text. Indented text. What should the parser do with this? Back to ordinary text. I'm just curious. I don't intend to change the implementation of block quotes in any way. -- David Goodger |
From: Aahz <aa...@py...> - 2003-05-23 18:37:27
|
On Fri, May 23, 2003, David Goodger wrote: > > For the sake of argument, let's say that block quotes were implemented > only with a directive:: > > .. block-quote:: > > Block quote text here. > > What then would an indented block of text mean? Let's take a step back for a sec: as pointed out with the confusion surrounding the ``class`` directive, the first question is, "*Should* undecorated indented blocks of text mean anything?" I am somewhat persuaded that the correct answer is "no". We already use indentation to link blocks of text to their preceding directive; requiring indentation to *always* be linked to a directive makes nested directives much easier to support. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93 |
From: David G. <go...@py...> - 2003-05-23 18:58:52
|
Aahz wrote: > Let's take a step back for a sec: as pointed out with the confusion > surrounding the ``class`` directive, the first question is, "*Should* > undecorated indented blocks of text mean anything?" > > I am somewhat persuaded that the correct answer is "no". I disagree. I think block quotes are useful enough to deserve their own syntax, and indentation is a good fit. > We already use indentation to link blocks of text to their preceding > directive; requiring indentation to *always* be linked to a directive > makes nested directives much easier to support. I was unaware of any difficulty with nested directives now:: .. topic:: title text .. image:: picture.png At this point, it would take some really convincing arguments to change the markup. If anyone wants to spend the time and effort, I promise to keep an open mind. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: Aahz <aa...@py...> - 2003-05-23 19:25:39
|
On Fri, May 23, 2003, David Goodger wrote: > > I was unaware of any difficulty with nested directives now:: > > .. topic:: title > > text > > .. image:: picture.png Sure, but then there's the question of whether the intent is:: .. topic:: title text .. image:: picture.png And what happens if it gets changed to:: text .. image:: picture.png Getting indentation correct in prose is a much more fraught undertaking IMO than in Python code. For example, in the fragment above, you're using what I consider inappropriate indentation of three spaces. There's also the issue that one is more likely to shift multiple paragraphs in prose. Anyway, I'm off for a nice weekend. See you later. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93 |
From: David G. <go...@py...> - 2003-05-23 19:48:39
|
[David Goodger] >> I was unaware of any difficulty with nested directives now:: >> >> .. topic:: title >> >> text >> >> .. image:: picture.png [Aahz] > Sure, but then there's the question of whether the intent is:: > > .. topic:: title > > text > > .. image:: picture.png How would you suggest clarifying the intent? > And what happens if it gets changed to:: > > text > > .. image:: picture.png > > Getting indentation correct in prose is a much more fraught > undertaking IMO than in Python code. For example, in the fragment > above, you're using what I consider inappropriate indentation of > three spaces. Inappropriate how? If it's the number of spaces, it doesn't have to be 3; 4 would be fine, or 8, as long as it's consistent. > There's also the issue that one is more likely to > shift multiple paragraphs in prose. I don't see the point of all this. ReStructuredText uses indentation to indicate local containment in constructs. That's not going to change. We're not going to switch to begin/end markers. -- David Goodger |
From: Aahz <aa...@py...> - 2003-07-26 15:52:04
|
[cleaning old mail] On Fri, May 23, 2003, David Goodger wrote: > [Aahz] >> [David Goodger] >>> >>> I was unaware of any difficulty with nested directives now:: >>> >>> .. topic:: title >>> >>> text >>> >>> .. image:: picture.png >> >> Sure, but then there's the question of whether the intent is:: >> >> .. topic:: title >> >> text >> >> .. image:: picture.png > > How would you suggest clarifying the intent? Actually, I mis-spoke. The problem comes with :: .. topic:: title text block-quote How should that block-quote be indicated? If it's nested inside a directive sometimes and not others, reST loses some of its visual readability. We don't have that problem with ``::``, because its level of indentation is always the same. >> Getting indentation correct in prose is a much more fraught >> undertaking IMO than in Python code. For example, in the fragment >> above, you're using what I consider inappropriate indentation of >> three spaces. > > Inappropriate how? If it's the number of spaces, it doesn't have to > be 3; 4 would be fine, or 8, as long as it's consistent. Python-standard indentation is four spaces. I think it's wise to encourage that standard for reST. >> There's also the issue that one is more likely to >> shift multiple paragraphs in prose. > > I don't see the point of all this. ReStructuredText uses indentation > to indicate local containment in constructs. That's not going to > change. We're not going to switch to begin/end markers. We've *already* got begin markers. The question is, to what extent should indentation itself be a begin marker? -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ This is Python. We don't care much about theory, except where it intersects with useful practice. --Aahz |
From: David G. <go...@py...> - 2003-07-29 04:25:08
|
Aahz wrote: > [cleaning old mail] I'll say! <reviews months-old thread...> > The problem comes with > > :: > > .. topic:: title > > text > > block-quote > > How should that block-quote be indicated? If it's a block quote inside the topic:: .. topic:: title text block-quote If the block quote is outside and following the topic:: .. topic:: title text .. block-quote The "empty comment" (".." followed by a blank line) serves to disambiguate indentation. It terminates preceding indented blocks, and consumes no following indented block. > If it's nested inside a directive sometimes and not others, reST > loses some of its visual readability. We don't have that problem > with ``::``, because its level of indentation is always the same. I don't follow. What's "it's"? I don't get the "::" reference either. > Python-standard indentation is four spaces. I think it's wise to > encourage that standard for reST. Python is program; reStructuredText is documentation. The level of structure and strictness is very different. IMO you're applying an inappropriate standard. > We've *already* got begin markers. The question is, to what extent > should indentation itself be a begin marker? I see no reason for change. There is some overloading of the meaning of indentation: local containment in construct context, and block quotes for "standalone" indentation otherwise. Empty comments serve to disambiguate in the relatively rare case of conflict. If this doesn't convince, could you provide a precis of your position so we don't have to refer back to the old thread? -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: Magnus <ma...@th...> - 2003-05-23 21:47:05
|
To me, it seems logical that "class" would be an attribute to a directive, just as it is an attribute to a tag in HTML, rather than a directive on it's own. You could have .. contents:: Brief Table of Contents :depth: 1 :class: brief-toc .. contents:: Detailed Table of Contents :depth: 3 :class: detailed-toc or .. sidebar:: Sidebar Title :subtitle: Optional Sidebar Subtitle :class: right-aligned Subsequent indented lines comprise the body of the sidebar, and are interpreted as body elements. or .. DANGER:: :class: extra-strong Beware killer rabbits! The problem is then how to handle the document elements that we construct without using a directive, such as block quotes or paragraphs. Being a complete novice with no insight in the docutils implemen- tation (which is sometimes an advantage :) I see two options. Either use the attribute alone as in :class: blue Here is a paragraph in the blue class. :class: red Here is a block quote in the red class. The other option would be to have optional directives for paragraph and blockquote that you only use if you want to indicate a class attribute, or othewise disambiguate things in some way. ..paragraph:: :class: blue Here is a paragraph in the blue class. ..blockquote:: :class: red Here is a block quote in the red class. I have to admit that I don't know rst enough to really grok whether a block quote after a paragraph is part of that paragraph or not. If it's not, I guess the above should be: ..paragraph:: :class: blue Here is a paragraph in the blue class. ..blockquote:: :class: red Here is a block quote in the red class. -- Magnus Lycka (It's really Lyckå), ma...@th... Thinkware AB, Sweden, www.thinkware.se I code Python ~ The shortest path from thought to working program |
From: David G. <go...@py...> - 2003-05-24 00:07:04
|
Magnus Lyckå wrote: > To me, it seems logical that "class" would be an attribute > to a directive, just as it is an attribute to a tag in HTML, > rather than a directive on it's own. That's already on the to-do list: - Add a "class" option to many/most directives...? I think we can drop the "?" now; it will happen. I've been thinking about the implementation. > The problem is then how to handle the document elements that we > construct without using a directive, such as block quotes or > paragraphs. Exactly. That's why a separate "class" directive is necessary. > Being a complete novice with no insight in the docutils implemen- > tation (which is sometimes an advantage :) I see two options. Either > use the attribute alone as in > > :class: blue > Here is a paragraph in the blue class. ":class: blue" is the syntax for a field list item. Field list syntax is used for directive options, but the directive part is required. > The other option would be to have optional directives for paragraph > and blockquote that you only use if you want to indicate a class > attribute, or othewise disambiguate things in some way. I would find that onerous. > I have to admit that I don't know rst enough to really grok whether > a block quote after a paragraph is part of that paragraph or not. It's not. They're separate elements. Paragraphs cannot contain any other body elements, only text and inline elements. -- David Goodger |
From: Mark N. <no...@so...> - 2003-05-23 23:23:47
|
David Goodger wrote: > > Aahz wrote: > > Speaking as someone who does use block quotes, I'd be highly > > amenable to requiring block quotes be a directive. > > For the sake of argument, let's say that block quotes were implemented > only with a directive:: > > .. block-quote:: > > Block quote text here. > > What then would an indented block of text mean? For example:: > > Ordinary, unindented paragraph text. > > Indented text. > > What should the parser do with this? > > Back to ordinary text. > > I'm just curious. I don't intend to change the implementation of block > quotes in any way. What if we leave the current interpretation of indented text blocks as block quotes alone, but add a directive as an alternate way of specifying a block quote? Then the class directive can apply to whatever follows, with the caveat that if you want to attach the class to a block quote, you'll have to use an explicit directive to specify the block quote. I think everything else falls out for free. --Mark |
From: David G. <go...@py...> - 2003-05-24 00:15:01
|
Mark Nodine wrote: > What if we leave the current interpretation of indented text blocks > as block quotes alone, There are no plans to change that. > but add a directive as an alternate way of specifying a block quote? > Then the class directive can apply to whatever follows, with the > caveat that if you want to attach the class to a block quote, you'll > have to use an explicit directive to specify the block quote. We could add one, but a new "block-quote" directive is not a necessity. I would find it onerous to have to use a directive in such a case. Here's the latest text from spec/rst/directives.txt: The "class" directive sets a "class" attribute value on the first immediately following non-comment element [#]_. For details of the "class" attribute, see `its entry`__ in `The Docutils Document Tree`_. Examples:: .. class:: special This is a "special" paragraph. .. class:: exceptional An Exceptional Section ====================== This is an ordinary paragraph. The text above is parsed and transformed into this doctree fragment:: <paragraph class="special"> This is a "special" paragraph. <section class="exceptional"> <title> An Exceptional Section <paragraph> This is an ordinary paragraph. .. [#] To set a "class" attribute value on a block quote, the "class" directive must be followed by an empty comment:: .. class:: highlights .. Block quote text. The directive doesn't allow content, therefore an empty comment is required to terminate the directive. Without the empty comment, the block quote text would be interpreted as the "class" directive's content, and the parser would complain. -- David Goodger |
From: David G. <go...@py...> - 2003-05-23 02:51:21
|
Paul Moore wrote: > I think the biggest problem I have with this (and maybe it explains > William's concern as well) is that the proposal is *highly* > indentation sensitive. Specifically, the cases only differ in the > indentation of the directive. It seemed simple enough to me, but I'm the first to admit that sometimes I'm too close to the implementation to see the forest for the trees. Literally. I tend think of documents in terms of trees, but I can see how my initial idea may be too difficult to deal with in practice. > I assume that there's no chance, at this late stage, of deprecating > the indentation-only blockquote element in favour of an explicit > "blockquote" directive :-( I think that's correct. The block quote construct gets good use > Back to reality - I think the class directive is probably OK when > used in conjunction with things *other* than blockquotes. So maybe > it's just your choice of example that is the problem. Could you > recast your examples without blockquotes? I could, but... > Alternatively, why can't the "class" directive simply be a simple > directive allowing no content, which sets the class of the immediately > following element. This may be better. It's also similar to the way that explicit hyperlink targets work [#]_. This way is a bit more work (a transform will have to be involved, since the parser doesn't *know* what the immediately following element is when it sees the directive), but that's OK. .. [#] Actually, explicit hyperlink targets merely *appear* to the user to work that way. In reality, they create empty point elements that don't interact with the immediately following element; they're just adjacent, and so work the same way. > Then you have:: ... > But how do we get a blockquote with a class? Easy - same as for > the normal rule for following a contentless directive with > indented text, just do the following > > .. class:: special > > .. > > This is a blockquote, with class special. See the empty > comment, which is how the reST spec says you should separate > indented text from a contentless directive. This is still > the first element after the directive (comments don't count) > so the class applies here as we require. That will have to be a special case, since empty comments *do* count -- at least, they're kept in the doctree. Hmm... Perhaps they ought to be removed at the earliest opportunity? > How does this look? It feels *far* more regular, and easy to > remember, than your suggestion. Perhaps. I'll mull it over. Meanwhile, further comments and ideas are welcome. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |