From: David G. <go...@py...> - 2005-10-29 00:22:19
Attachments:
signature.asc
|
Today I checked in several changes, two of which I'll discuss here. First, a new generic "container" element and directive. This was discussed early this months as a possible fix to a problem that turned out not to be Docutils' problem. However, it has been discussed (under various terms) now and then, and I've been thinking about it for a while, and decided that it would make a worthy addition. Basically, it gives us the block/body equivalent of the generic "inline" element: a do-nothing element that's just a place to hang a "class" attribute. In other words, an extension mechanism for users and applications. Second, an update to Chris Liechti's S5/HTML slide show writer (in sandbox/cliechti/slideshow). S5 1.1 was released recently by Eric Meyers. He added some features, and took the package into the Public Domain. I updated Chris' code to take advantage of the S5 1.1 changes, and removed the remaining wart that prevented it from being added to the Docutils core: the "handout" directive. In S5, any HTML element with a class="handout" attribute only displays in handout mode & printouts. Chris' "handout" directive put its contents into a block quote with a class="handout" attribute, which was obviously a workaround. The new "container" element & directive neatly obviates this awkward workaround. I expect to add S5 to the Docutils core before too long. In fact, I hope to be using it (and perhaps even speaking about it!) at PyCon next year. -- David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2005-10-29 17:51:23
|
On Fri, 28 Oct 2005, David Goodger apparently wrote: > I expect to add S5 to the Docutils core before too long. > In fact, I hope to be using it (and perhaps even speaking > about it!) at PyCon next year. In full screen mode (FireFox) I'm seeing the bottom of the last bullet text clipped on some pages of the sample presentation (presentation.txt, with the handouts directives removed). I'd love to use this ... Cheers, Alan Isaac |
From: Felix W. <Fel...@gm...> - 2005-10-31 20:38:59
|
David Goodger wrote: > First, a new generic "container" element and directive. I'd like to raise my concerns about how you added it: * There was thread about that where I objected to the container element, and the last posting was written by you. ISTR we agreed that silence does not imply agreement. I simply hadn't gotten around to writing a reply yet. I'm generally fine with the addition of the container element, but I would have appreciated if you had quickly asked before via IM if there are any objections left. * I think the "container" directive is wrongly implemented and overall unnecessary. I will explain my objections below, but prior discussion about the syntax of the container directive would have been helpful. By the way, you advocated that feature additions be implemented on a branch. Now you just checked in a change to the trunk that hasn't even been discussed. Could you please explain what you actually want? Now, regarding the technical details: IMO the class of the container element should not be passed as a directive argument. That looks inintuitive -- we normally do not pass classes in the directive argument except for the "class" directive, where it's obvious that the argument is a class. Furthermore, I do not see a need for the "container" directive. The "class" directive allows to pass contents, so instead of setting the class for each element, we could as well wrap the contents in a container element and apply the class to that element. I find that more logical, and it certainly looks better. Compare :: .. container:: :class: handout Contents and :: .. class:: handout Contents I think the latter variant is much more concise and easier to remember. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: David G. <go...@py...> - 2005-11-01 01:44:06
Attachments:
signature.asc
|
[Felix Wiemann] > I'd like to raise my concerns about how you added it: > > * There was thread about that where I objected to the container > element, and the last posting was written by you. In that last message (the "Multiple Elements With class directive" thread on docutils-users), I provided two opportunities. First: I have actually implemented a "container" directive, element, HTML support, and docs in my local checkout. All I've done is to define "container" as follows: <!ELEMENT container (%body.elements;)+> <!ATTLIST container %basic.atts;> and to add "container" to the list of %body.elements;. Shall I check it in on a branch? The second opportunity: ... [Felix] > Would you object to removing the to-do list entry about a > generic block-level container? Yes; please leave it (or add your comments). I'm nowhere near convinced it's a bad thing. All it would have taken was a "yes, please" to the branch question or adding your comments to the to-do list. That last message was posted on October 3. I waited almost 4 weeks; how long should one be expected to wait? As I heard nothing since, and I had a pressing need for it (the S5 writer, which I was actively developing), I went ahead and added it. Note that it was a simple addition, not an API change, and would have no impact on any existing code. Since October 3 I had been thinking it over, and convinced myself that this was the correct approach. A block/body equivalent of the generic "inline" element has been discussed before; this was the right time for it. Since it was a simple addition, I didn't see the need to put it on a branch. And it was to be used by code in a sandbox. It seems silly to make a branch for a sandbox. As chief architect, I trust my own judgement. I hope you would too. > ISTR we agreed that silence does not imply agreement. I simply > hadn't gotten around to writing a reply yet. 26 days wasn't long enough? Even if you were away at EuroOSCON, you have participated in plenty of other discussions since. > I'm generally fine with the addition of the container element, but > I would have appreciated if you had quickly asked before via IM if > there are any objections left. I don't need your approval. > * I think the "container" directive is wrongly implemented and > overall unnecessary. > > I will explain my objections below, but prior discussion about the > syntax of the container directive would have been helpful. I laid out the document model precisely on October 3. If you wanted to see the implementation, a simple "yes" would have sufficed. > By the way, you advocated that feature additions be implemented on > a branch. Now you just checked in a change to the trunk that > hasn't even been discussed. Sure it was discussed. You dropped the ball. If you have an objection or concern, voice it early. As per my last message, I had assumed that this new policy would take effect with Docutils 0.4. > Now, regarding the technical details: > > IMO the class of the container element should not be passed as a > directive argument. That looks inintuitive -- we normally do not > pass classes in the directive argument except for the "class" > directive, where it's obvious that the argument is a class. With both the "container" and "class" directives, the class name is required information. Both directives are useless without it. A "required option" is a contradiction in terms, so the class name naturally became a required argument. > Furthermore, I do not see a need for the "container" directive. The > "class" directive allows to pass contents, so instead of setting the > class for each element, we could as well wrap the contents in a > container element and apply the class to that element. I find that > more logical, and it certainly looks better. Compare :: > > .. container:: > :class: handout > > Contents > > and :: > > .. class:: handout > > Contents > > I think the latter variant is much more concise and easier to > remember. That's a straw man argument. The actual implemented syntax is: .. container:: handout Contents The syntax difference is all of 4 characters! The real difference is that the "container" element can be used for further processing and rendering, such as putting a box around the contents. The "class" directive can only be applied to multiple individual elements, but not to a group of elements. For example, the "class" directive, .. class:: handout one two three produces: <paragraph classes="handout"> one <paragraph classes="handout"> two <paragraph classes="handout"> three While "container", .. class:: handout one two three produces: <container classes="handout"> <paragraph> one <paragraph> two <paragraph> three With "class", there's no indication that there's any association between the elements. With "container", the association is obvious and useful. -- David Goodger <http://python.net/~goodger> |
From: Nicola L. <ni...@te...> - 2005-11-01 07:41:03
|
> While "container", > > .. class:: handout This should obviously be: :-) .. container:: handout > one > > two > > three > > produces: > > <container classes="handout"> > <paragraph> > one > <paragraph> > two > <paragraph> > three I'd like to write multilanguage ReST documents. Would the "container" directive be a good way to specify the language of a paragraph or group of paragraph, similarly to the "lang" HTML attribute, or is there an even simpler way? (Wow, a *double* subject change in a thread, that's a first. ;-) ) -- Nicola Larosa - ni...@te... If there's one thing that religions are good at, it's giving people axioms, and axioms don't have to be rational. You can make up the craziest religion you can think of, and people will still follow it, because it makes them function better. -- Phillip J. Eby, August 2005 |
From: David G. <go...@py...> - 2005-11-01 15:07:10
Attachments:
signature.asc
|
[Nicola Larosa] > I'd like to write multilanguage ReST documents. Would the "container" > directive be a good way to specify the language of a paragraph or group of > paragraph, similarly to the "lang" HTML attribute, or is there an even > simpler way? What behavior do you want out of this? -- David Goodger <http://python.net/~goodger> |
From: Nicola L. <ni...@te...> - 2005-11-01 15:20:48
|
[Nicola Larosa] >> I'd like to write multilanguage ReST documents. Would the "container" >> directive be a good way to specify the language of a paragraph or group of >> paragraph, similarly to the "lang" HTML attribute, or is there an even >> simpler way? [David Goodger] > What behavior do you want out of this? I'd like to convert multilanguage ReST documents to monolanguage HTML ones, maybe by specifying an option to rst2html.py, or by passing a parameter to the appropriate method. I find it easier translating text when all languages reside side by side in the same document, avoiding the need to continuously switch between, and realing, different windows. OTOH, maybe a tool like Meld could ease working on two or three documents simultaneously, effectively rendering my request moot. :-) -- Nicola Larosa - ni...@te... If there's one thing that religions are good at, it's giving people axioms, and axioms don't have to be rational. You can make up the craziest religion you can think of, and people will still follow it, because it makes them function better. -- Phillip J. Eby, August 2005 |
From: David G. <go...@py...> - 2005-11-02 01:35:46
Attachments:
signature.asc
|
[Nicola Larosa] > I'd like to convert multilanguage ReST documents to monolanguage > HTML ones, maybe by specifying an option to rst2html.py, or by > passing a parameter to the appropriate method. ISTM that you're looking for the equivalent of XML "conditional sections". I don't think that's within Docutils' scope. I'd suggest using a templating system in front of Docutils. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-11-06 15:51:01
|
David Goodger wrote: > Felix Wiemann wrote: > >> I'd like to raise my concerns about how you added it: >> >> * There was thread about that where I objected to the container >> element, and the last posting was written by you. > > In that last message (the "Multiple Elements With class directive" > thread on docutils-users), I provided two opportunities. OK, it's partly my fault. Sorry. > [...] > > It seems silly to make a branch for a sandbox. Why? That's what we have the sandboxes below the trunk directory. > 26 days wasn't long enough? Even if you were away at EuroOSCON, you > have participated in plenty of other discussions since. I don't work through my email in chronologic order, by the way. Do you? [Policy discussions off-list. Keeping the technical stuff on the list.] > The real difference [between "class" and "container"] is that the > "container" element can be used for further processing and rendering, > such as putting a box around the contents. The "class" directive can > only be applied to multiple individual elements, but not to a group of > elements. My problem with the current "container" implementation is that it's not clear that the argument is a class. (Whereas with the "class" directive it is.) So I'd prefer to see either one of the following solutions: 1. Remove the "container" directive and make the "class" directive add a container around its contents. The logic of the class directive would then be "apply the class to the contents as a whole" (using a container) instead of the current implementation "apply the class to each contained element". This would mean we don't have to add another directive ("container"), thus avoiding adding more and more directives. 2. Make the class of the "container" directive optional, making the class an option. This would have the disadvantage that the syntax becomes a bit more unwieldy since you'd have to write:: .. container:: :class: handout ... contents ... However, the advantages are that it's explicit, and you can have a container without a class. I can actually see use cases for that: * For a presentation I want all elements inside a section to be displayed sequentially. So I could write:: Slide Title =========== At first only the slide title is displayed. When I press space-bar, this paragraph is displayed. Next time I press space-bar, this paragraph is displayed. .. container:: Next time I press space-bar, two paragraphs are displayed! This is the second paragraph and it's displayed together with the previous one. This is the last paragraph on the slide. * Another use case: I remember someone asking for a possibility to add set an ID on every paragraph, for whatever reason. Now given that possibility, you might want to set an ID on two paragraphs that belong together, like so:: This paragraph gets an ID. This one, too. .. container:: These two paragraphs get an ID combined. This is because the ID is set on the container element. Last paragraph. This solution is also more orthogonal: The "class" directive is for setting a class, and the "container" directive is for creating a container. Neither of both forces you to do the other thing. I think the second solution (making the class optional for "container") is *slightly* better, but I'd like to hear your opinion. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: David G. <go...@py...> - 2005-11-08 01:37:59
Attachments:
signature.asc
|
[David Goodger] >> It seems silly to make a branch for a sandbox. [Felix Wiemann] > Why? That's what we have the sandboxes below the trunk directory. They both have the same purpose: freedom of exploration. A branch of a sandbox is redundant. And now that we have easier branches, I expect sandboxes will be used less. In fact, the next stage of the S5 work will require a branch, so I will make one and ignore or remove the sandbox. > I don't work through my email in chronologic order, by the way. Do > you? Not always, although I try to. In any case, we've seen that long delays cause problems. I'll try to keep up on my mail if you will :-) >> The real difference [between "class" and "container"] is that the >> "container" element can be used for further processing and rendering, >> such as putting a box around the contents. The "class" directive can >> only be applied to multiple individual elements, but not to a group of >> elements. > > My problem with the current "container" implementation is that it's > not clear that the argument is a class. (Whereas with the "class" > directive it is.) What's not clear about it? When using any directive, knowledge of that directive's arguments and options is required. In other words, we have to read the docs. Arguments are preferred over options. Arguments *must* be used for required information. Options are best used for infrequently specified information. When there's frequently-specified but optional information that *can* be given as arguments, it should be. > So I'd prefer to see either one of the following solutions: > > 1. Remove the "container" directive and make the "class" directive > add a container around its contents. The class directive doesn't require a container, and adding one would complicate its function. > The logic of the class directive would then be "apply the class > to the contents as a whole" (using a container) instead of the > current implementation "apply the class to each contained > element". But sometimes we *do* want to apply the class to each contained element. For example, for a presentation: .. class:: incremental paragraph to be displayed first to be displayed second etc. > This would mean we don't have to add another directive > ("container"), thus avoiding adding more and more directives. This is exaggeration. It's not "more and more directives". We're only talking about *one* directive. > 2. Make the class of the "container" directive optional, making the > class an option. The class argument *is* already optional. You can make a class-less container if you like. However, since the main function of a container element is to hold a class attribute, it's natural for the class to be specified in the simplest way possible. Thus, an argument. > This would have the disadvantage that the syntax becomes a bit > more unwieldy since you'd have to write:: > > .. container:: > :class: handout > > ... contents ... Yes, exactly. That's unnecessarily verbose. > However, the advantages are that it's explicit, Overly and unnecesarily explicit. There's no need for the explicit option -- no ambiguity, and no competing use for the directive argument. > and you can have a container without a class. As shown above, this is already possible. > I can actually see use cases for that: > > * For a presentation I want all elements inside a section to be > displayed sequentially. So I could write:: > > Slide Title > =========== > > At first only the slide title is displayed. When I press > space-bar, this paragraph is displayed. > > Next time I press space-bar, this paragraph is displayed. > > .. container:: > > Next time I press space-bar, two paragraphs are > displayed! > > This is the second paragraph and it's displayed together > with the previous one. > > This is the last paragraph on the slide. Good example. All that's necessary is the "incremental" class. This is already possible: Slide Title =========== .. class:: incremental At first only the slide title is displayed. When I press space-bar, this paragraph is displayed. Next time I press space-bar, this paragraph is displayed. .. container:: Next time I press space-bar, two paragraphs are displayed! This is the second paragraph and it's displayed together with the previous one. This is the last paragraph on the slide. > * Another use case: I remember someone asking for a possibility to > add set an ID on every paragraph, for whatever reason. > > Now given that possibility, you might want to set an ID on two > paragraphs that belong together, like so:: The container directive/element could be used for that as it stands (if the ID functionality existed, that is). > This solution is also more orthogonal: The "class" directive is > for setting a class, and the "container" directive is for creating > a container. Neither of both forces you to do the other thing. This *is* already the case. > I think the second solution (making the class optional for > "container") is *slightly* better, but I'd like to hear your > opinion. Given that the class already *is* optional (an optional argument), are your objections addressed? I hope so. Let's consider this issue closed. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-11-08 12:42:11
|
David Goodger writes: > [Sandboxes and branches] both have the same purpose: freedom of > exploration. A branch of a sandbox is redundant. Not quite. Sometimes you may want to try new things out in a sandbox without messing up your existing sandbox code in the trunk. That's when you'd branch a sandbox (even though we never had that case IIRC). But more often, branching sandboxes is helpful when you make changes to the trunk that affect sandbox code as well. (I remember this happening when I did the multiple-IDs refactoring.) I usually branch the whole trunk regardless of whether I need the sandboxes or not to make diffing and merging simpler (because I don't have to think about which part of the tree I branched). >> I don't work through my email in chronologic order, by the way. Do >> you? > > Not always, although I try to. Maybe I should, too... Regarding the "container" directive: >> 1. Remove the "container" directive and make the "class" directive >> add a container around its contents. > > But sometimes we *do* want to apply the class to each contained > element. For example, for a presentation: > > .. class:: incremental Oh, yes. Good example. >> 2. Make the class of the "container" directive optional, making the >> class an option. > > The class argument *is* already optional. Oh, I see. I seemed to have inferred from one of your previous postings that it wasn't. > Given that the class already *is* optional (an optional argument), are > your objections addressed? Yup. Thanks. -- Felix Wiemann -- http://www.ososo.de/ |