From: Edward L. <ed...@gr...> - 2004-04-19 04:31:46
|
> I have some questions for everyone. But first, some deep background: > > In writing the "role" directive, I realized that the API of role > functions needs to be expanded. For example, in:: > > .. role:: custom > > the role function generated by the directive needs to know that the > "class" attribute of the generated "inline" element must be set to > "custom". I accomplished this by adding an "attributes={}" parameter > to the "generic_role" helper function and the dynamically defined role > functions that call "generic_role":: > > def generic_role_helper(node_class, role, rawtext, text, lineno, inliner, > attributes={}): > return [node_class(rawtext, text, **attributes)], [] I'm not entirely happy w/ a generic "attributes" parameter. It doesn't seem like it will always be clear what to do with these attributes, especially if anyone defines a role function that doesn't always return exatly one node. I would rather have all extra options be role-specific (including even "basic" options like "class"). So how about this: * Each role can define a function attribute "options", specifying options that it can take. These options are only set when creating derived roles. * The role directive looks like this:: .. role:: <newrole>[(<baserole>)] :option1: value1 :option2: value2 ... :optionN: valueN Where... - <newrole> is the name of the new role. - <baserole> is the name of the base role (defaults to "inline") - <option1>...<optionN> are options to the *role* - The parens around <baserole> are supposed to be suggestive of base classes in class definitions. To implement this, we would need to define the role directive as taking no options (the options are for the *role*, not for the *directive*), so the main body of the directive would be sent directly to the role directive function, without processing the options. Some example uses: .. role:: custom :class: custom .. role: alias(pep-reference) .. role: mypep(pep) :base-uri: /foo/bar/baz/ .. role: apiref(uri-reference) :base-uri: http://myapi.com/cgi-bin/get-apidocs?obj= .. role: apiref(uri-reference) :uri-template: http://myapi.com/bar/baz/$(TEXT).html Some example role functions: # Used to define most simple roles: def generic_role(node_class, role, rawtext, text, lineno, inliner, options): node = node_class(rawtext, text) if options.has_key('class'): node['class'] = options['class'] return [node], [] generic_role.options = {'class': class_option} def uri_reference_role(role, rawtext, text, lineno, inliner, options): node = node_class(rawtext, text) if options.has_key('uri-template'): uri = uri_template.replace('$(TEXT)', text) elif options.has_key('base-uri'): uri = base_uri + options['base-uri'] else: uri = text return [nodes.reference(rawtext, text, refuri=uri)], [] uri_reference_role.options = {'base-uri': unchanged, 'uri-template': unchanged} -Edward |
From: David G. <go...@py...> - 2004-04-20 21:17:00
|
Edward Loper wrote: > I'm not entirely happy w/ a generic "attributes" parameter. It > doesn't seem like it will always be clear what to do with these > attributes, especially if anyone defines a role function that > doesn't always return exatly one node. That's true, but I think it's an issue either way. Whether the data is passed in as an "attributes" dictionary or as an "options" dictionary, such a role function will have that issue. We'll deal with it when it arises. > I would rather have all extra options be role-specific (including > even "basic" options like "class"). So how about this: > > * Each role can define a function attribute "options", specifying > options that it can take. These options are only set when > creating derived roles. > > * The role directive looks like this:: > > .. role:: <newrole>[(<baserole>)] > :option1: value1 > :option2: value2 > ... > :optionN: valueN ... > To implement this, we would need to define the role directive as > taking no options (the options are for the *role*, not for the > *directive*), so the main body of the directive would be sent > directly to the role directive function, without processing the > options. Interesting idea. There are some issues: 1. I have a mild objection to putting so much syntax into the directive argument ("<newrole>[(<baserole>)]"). The base role would normally be a directive option, especially since it's optional. But the base role *has* to be in the argument for the options to be known before they're parsed. That's OK, except... 2. It's a bit fragile. Some people code Python with a space between class and superclass (``class SubClass (SuperClass):``). But we can't say "newrole (baserole)", because the space breaks the syntax if there's only 1 required argument. So we'd have to * specify that spaces are illegal, or * handle the parsing separately (by specifying that the role and baserole must appear on the first line, for example), or * specify 1 required and 1 optional argument. The last option won't work, because... 3. Using the directive contents for the role options, we would have to require they be separated from the first line of the directive by a blank line: Arguments and options must form a contiguous block beginning on the first or second line of the directive; a blank line indicates the beginning of the directive content block. If either arguments and/or options are employed by the directive, a blank line must separate them from the directive content. -- http://docutils.sf.net/spec/rst/reStructuredText.html#directives This would mean that the role directive would look very different from all the other directives. *Unless* we have all parsing of arguments/options done by the directive function itself (rather than by the code that *calls* the directive function, as it is currently). We'd have to declare the role directive as containing only content (no arguments or options). If we implement this idea, I think that's the solution: have only contents (no arguments *or* options) on the "role" directive, and parse the arguments and options separately. Shouldn't take long to build the required infrastructure (refactored from docutils.parsers.rst.states.Body.parse_directive etc.). -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv |
From: David G. <go...@py...> - 2004-04-27 20:26:56
|
[Edward Loper] >> I would rather have all extra options be role-specific (including >> even "basic" options like "class"). An updated API has been checked in. The implementation took a bit longer than I thought it would (doesn't it always?). I've also update the docs. Please take a look: the "role" directive http://docutils.sf.net/spec/rst/directives.html#role interpreted text roles http://docutils.sf.net/spec/rst/interpreted.html Creating reStructuredText Interpreted Text Roles http://docutils.sf.net/spec/howto/rst-roles.html -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv |
From: David P. <pr...@sf...> - 2004-04-29 05:05:54
|
I work almost exclusively in print media. Print media simply doesn't work on a "dots per inch" basis when placing images. I've no idea whether the output is going to an old 300dpi laser or a newfangled 3000dpi imagesetter. The dots are simply the dots: it's the width and height, measured in something rather more standardized (in, cm, pt), that really counts. With that in mind, I'd like to suggest that DocUtils be a bit more flexible in its field parsing for the width and height components of the image & figure directives. Let's let us specify a unit measure. In my XSL:FO templates, I desperately want to test for a unit measure. It would be *so* easy to implement good XSL:FO layout if DocUtils does units. I'm certain the LaTeX folk would equally benefit. Even the HTML guys can make use of this, if "scale" is treated as a %age if it has a % sign, and as dpi if there is no symbol. A 3" graphic, with a scale of 72dpi (Mac World) would be 3x72 pixels wide. I don't know whether the units measure should be restricted to in/cm/pt/px/(blank = px) or whether em/en should also be included. Doesn't really matter to me, just so long as I can have inches... |
From: Fred L. D. Jr. <fd...@ac...> - 2004-04-29 18:24:18
|
On Thursday 29 April 2004 01:05 am, David Priest wrote: > With that in mind, I'd like to suggest that DocUtils be a bit more > flexible in its field parsing for the width and height components of the > image & figure directives. Let's let us specify a unit measure. ... > Even the HTML guys can make use of this, if "scale" is treated as a %age > if it has a % sign, and as dpi if there is no symbol. A 3" graphic, with > a scale of 72dpi (Mac World) would be 3x72 pixels wide. +1 > I don't know whether the units measure should be restricted to > in/cm/pt/px/(blank = px) or whether em/en should also be included. I don't see any particular need to em/en to be supported. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation |
From: David G. <go...@py...> - 2004-04-30 12:53:57
|
David Priest wrote: > With that in mind, I'd like to suggest that DocUtils be a bit more > flexible in its field parsing for the width and height components of > the image & figure directives. Let's let us specify a unit measure. This has come up before: <http://article.gmane.org/gmane.text.docutils.user/154>. There's a mention of it in the to-do list. I'm for it, but I haven't needed it, therefore *I* haven't implemented it yet. > Even the HTML guys can make use of this, if "scale" is treated as a > %age if it has a % sign, and as dpi if there is no symbol. Problem: "scale" is already treated as a percentage, without a "%". You're assigning a different meaning to the word "scale". Perhaps "resolution" instead? Is there a better, more precise term ("pixels-per-unit")? So, how to implement it? * Modify the "image" & "figure" directives: - New "unit" option that applies to both height & width? - Tack the units onto the height/width values? (Would the units of both height & width have to match?) * How should the HTML writer handle units *other* than pixels? - Require a "resolution" option to convert to pixels? - Or ignore height/width with units without "resolution"? * Issues with other writers? > I don't know whether the units measure should be restricted to > in/cm/pt/px/(blank = px) or whether em/en should also be included. I agree with Fred; em/en aren't needed. Being so subjective, they'd be too difficult to handle anyhow. -- David Goodger |
From: Felix W. <Fel...@gm...> - 2004-04-30 18:52:30
|
David Goodger schrieb: > David Priest wrote: > >> I'd like to suggest that DocUtils be a bit more flexible in its field >> parsing for the width and height components of the image & figure >> directives. Let's let us specify a unit measure. I'd only like it if it's easy to implement, because otherwise, it makes writing new writers difficult and bloats the code. > So, how to implement it? > > * Modify the "image" & "figure" directives: > > - New "unit" option that applies to both height & width? Too clumsy. > - Tack the units onto the height/width values? Yes. > (Would the units of both height & width have to match?) I don't see any reason for that. > * How should the HTML writer handle units *other* than pixels? CSS. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-04-30 20:19:29
|
[David Goodger] >> * How should the HTML writer handle units *other* than pixels? [Felix Wiemann] > CSS. Could you elaborate, with an example perhaps? -- David Goodger |
From: Felix W. <Fel...@gm...> - 2004-04-30 23:14:11
|
David Goodger wrote: >>> * How should the HTML writer handle units *other* than pixels? >> >> CSS. > > Could you elaborate, with an example perhaps? <img style="width: 12in; height: 8in;" src="image.png" alt="" /> See <http://www.htmlhelp.com/reference/css/units.html#length>. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-05-01 01:23:58
|
Felix Wiemann wrote: >> Could you elaborate, with an example perhaps? > > <img style="width: 12in; height: 8in;" src="image.png" alt="" /> > > See <http://www.htmlhelp.com/reference/css/units.html#length>. Thanks for jogging my memory (I *think* I once knew about this ;-). It's also covered in the CSS1 spec: <http://www.w3.org/TR/REC-CSS1#length-units>. -- David Goodger |
From: David G. <go...@py...> - 2004-04-30 20:17:00
|
David Priest wrote (off-list; quoting with permission): > On Fri, 30 Apr 2004 08:53:46 -0400, David Goodger <go...@py...> > wrote: > >> Problem: "scale" is already treated as a percentage, without a "%". >> You're assigning a different meaning to the word "scale". Perhaps >> "resolution" instead? Is there a better, more precise term >> ("pixels-per-unit")? > > If we're held back by legacy support requirements, then: > :scale: > - blank = percentage > - % = percentage > - in = inches > - cm = centimeters > - px = pixels > - dpi = resolution I don't understand. "Scale" here means reduce/enlarge by a percentage. What would ":scale: 3in" mean? Some writers will be fine with ":width: 3in" as-is, but HTML needs pixels, so to convert inches to pixels it needs to know the resolution of the image: how many pixels per inch or centimeter or point. Perhaps a ":resolution: 300px/in" option? Don't some image formats know their own resolution? Perhaps we could use PIL to find out if nothing is specified. > Another issue: > > .. class: `knights grail bunny` > > Results in an error message. Yet in the world of XML and CSS2, it > isn't uncommmon to `assign multiple classes`__ to a single tag. That's true. I'll add support for multiple classes to the to-do list. > To match a subset of "class" values, each value must be preceded > by a ".", in any order. > > For example, the following rule matches any P element whose > "class" attribute has been assigned a list of space-separated values > that includes "pastoral" and "marine": > > p.pastoral.marine { color: green } > > This rule matches when class="pastoral blue aqua marine" but > does not match for class="pastoral blue". > > The fix is easy: allow more than one class argument, leaving spaces > as spaces. > > __`http://www.w3.org/TR/CSS21/selector.html#class-html` > > Also, I don't know if what I just did there for the anonymous link > is correct, No, it should have been this: __ http://www.w3.org/TR/CSS21/selector.html#class-html > but it should be. It exactly mirrors the convention for specifying > a link inline I don't think so. For one thing, it's a URI, and URIs never need quoting, whether inline or standalone. > Nice orthogonality that way. *Very* important, is orthogonality. Yes, but only when appropriate. This isn't. > I wish all email clients supported RST. It'd look so good. :-) -- David Goodger |
From: David P. <pr...@sf...> - 2004-04-30 20:28:18
|
On Fri, 30 Apr 2004 16:16:49 -0400, David Goodger <go...@py...> wrote: > I don't understand. "Scale" here means reduce/enlarge by a > percentage. What would ":scale: 3in" mean? It'd be meaningless. So much for that idea. > Some writers will be fine with ":width: 3in" as-is, but HTML needs > pixels, so to convert inches to pixels it needs to know the resolution > of the image: how many pixels per inch or centimeter or point. That's when you'd need to use the scale for dpi, perhaps. Given an inch width and a dpi scale, it can calculate the pixel width. > > Nice orthogonality that way. *Very* important, is orthogonality. > > Yes, but only when appropriate. This isn't. Why wasn't that (__`url:`) appropriate? It makes the markup more orthogonal, which makes it easier to remember, and it doesn't make it more difficult to read. What important appropriateness-rule is it breaking? Thanks for adding multiple classes. There are a few cases where that will make my XSL:FO much, *MUCH* easier. Wanna see a large PDF that's being autogenerated from RST->DocUtils->XSL:FO->XEP->PDF? This system is working so incredibly well. |
From: David G. <go...@py...> - 2004-04-30 21:16:31
|
David Priest wrote: > Why wasn't that (__`url:`) appropriate? Some background first. The trailing underscore is used to indicate a named hyperlink reference: a reference name_ Backquotes are used for phrase references, or to disambiguate: a `phrase reference`_ and a `name`_ The backqoutes quote the reference name. Inline targets use a leading underscore (think of an underscore as a right-pointing arrow, "->"). an _`inline target` Inline targets require the backquotes to quote the target name because leading underscores are too common in technical language (like "_variable"). Now my rationale: In none of the cases above are URIs alone ever quoted, only names. There's no need to quote the URI in a named or anonymous target: .. _name: http://example.org __ http://example.org There's no precedent, so there's no orthogonality. ***** I feel there's a need to explain my obstinacy here and in other recent cases. I consider the established reStructuredText syntax to be pretty mature. I am loathe to change the syntax, because any change would imply breakage. It would take an *extremely* convincing and objective argument to make me even consider changing the syntax. So be warned, any syntax change proposals will require an active champion who had better be prepared to defend their proposal vigorously. There are places where we can still *add* syntax, like "|" for line blocks and "_" for targets, both recently proposed. Adding syntax shouldn't break existing documents, so it's much easier to do. But removing or changing syntax is much harder, requiring the initial syntax to be well thought out, which takes time. ***** > Wanna see a large PDF that's being autogenerated from > RST->DocUtils->XSL:FO->XEP->PDF? Sure. > This system is working so incredibly well. Glad to hear it! -- David Goodger |
From: David P. <pr...@sf...> - 2004-04-30 21:38:37
|
On Fri, 30 Apr 2004 17:16:22 -0400, David Goodger <go...@py...> wrote: > Now my rationale: > > In none of the cases above are URIs alone ever quoted, only names. > There's no need to quote the URI in a named or anonymous target: > > .. _name: http://example.org > __ http://example.org > > There's no precedent, so there's no orthogonality. What is a URI but the name of something? There is no *need* to quote URIs but consistency in markup would require the ability to do so. I'm going to be radical and suggest that *all* links, no matter how short, be quoted. The backtick serves as an indicator to the reader that the next bit of text is somehow special. In that regard it operates a bit like the upside-down question mark used in Spanish, which precedes the sentence so that you know it's a question long before you get to the end of it and have to rethink your understanding of what you just read. I'm not going to argue comprehensively about this, because what we have now works "good enough." I do find it jarring to not be able to apply my knowledge of `links`_, which I use all the time in text (especially as links to a section title) to the use of _`destinations`. |
From: David G. <go...@py...> - 2004-04-30 22:37:23
|
David Priest wrote: > What is a URI but the name of something? There is no *need* to > quote URIs but consistency in markup would require the ability to do > so. There's a need *not* to quote URIs. If we quote URIs, how do we differentiate between a _`named destination` and a _`http://example.org/URI`? Currently, they look different. Here are two anonymous targets: __ `named destination`_ __ http://example.org/URI If you get rid of the whitespace and require backquotes, it becomes very difficult to tell the difference. We can't rely on URI schemes (the "http:" part) because: __ this_is_a_relative_URI > I'm going to be radical and suggest that *all* links, no matter how > short, be quoted. I'm going to be blunt and say no. I hope my counterexample above convinced you. If it didn't, that's just because I'm unable to express the rationale clearly enough. In any case, this particular syntax is not going to change now. Orthogonality is important and useful, but being able to differentiate between different cases is more important. -- David Goodger |
From: David P. <pr...@sf...> - 2004-04-30 23:47:34
|
On Fri, 30 Apr 2004 18:37:12 -0400, David Goodger <go...@py...> wrote: > __ `named destination`_ > __ http://example.org/URI > > If you get rid of the whitespace and require backquotes, it becomes > very difficult to tell the difference. Well, heck. Again, you are right. It's a damn good thing you're project lead! :-) |
From: Brent C. <bus...@ya...> - 2004-04-30 20:34:29
|
On Fri, 30 Apr 2004, David Goodger wrote: > David Priest wrote (off-list; quoting with permission): > > On Fri, 30 Apr 2004 08:53:46 -0400, David Goodger <go...@py...> > > wrote: > > > >> Problem: "scale" is already treated as a percentage, without a "%". > >> You're assigning a different meaning to the word "scale". Perhaps > >> "resolution" instead? Is there a better, more precise term > >> ("pixels-per-unit")? > > > > If we're held back by legacy support requirements, then: > > :scale: > > - blank = percentage > > - % = percentage > > - in = inches > > - cm = centimeters > > - px = pixels > > - dpi = resolution > > I don't understand. "Scale" here means reduce/enlarge by a > percentage. What would ":scale: 3in" mean? > > Some writers will be fine with ":width: 3in" as-is, but HTML needs > pixels, so to convert inches to pixels it needs to know the resolution > of the image: how many pixels per inch or centimeter or point. > > Perhaps a ":resolution: 300px/in" option? Don't some image formats > know their own resolution? Perhaps we could use PIL to find out if > nothing is specified. > The HTML writer already uses PIL to determine image size in pixels and writes derived height and width attributes when scale is specified, scaling by pixel %age. - Brent |
From: Fred L. D. Jr. <fd...@ac...> - 2004-04-30 21:10:19
|
On Friday 30 April 2004 08:53 am, David Goodger wrote: > - Tack the units onto the height/width values? > (Would the units of both height & width have to match?) This is the way to go. > I agree with Fred; em/en aren't needed. Being so subjective, they'd > be too difficult to handle anyhow. I didn't say they were subjective! They *might* even make sense for images embedded inline with text, but they only make sense when there's a clear and specific association with text, because the actual size can only be computed from the font metrics. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation |
From: David G. <go...@py...> - 2004-04-30 21:26:18
|
Fred L. Drake, Jr. wrote: >> I agree with Fred; em/en aren't needed. Being so subjective, >> they'd be too difficult to handle anyhow. > > I didn't say they were subjective! No, I did. ;-) Perhaps I should have said "indirect and complicated to evaluate", since they'd require knowledge that Docutils cannot hope to have. Em/en might be useful for some output formats, but I can't imagine trying to implement them for HTML. But I've been wrong before, and I'm sure to be wrong again. -- David Goodger |