From: David A. <da...@bo...> - 2002-12-15 01:10:21
|
The following line doesn't seem to format as expected: Those bracketed expressions are Python ``list``s. A ``list`` is I just wanted the word "list" to appear twice as an inline literal, with the 's' following in a normal font. Is there a way to do this? -- David Abrahams da...@bo... * http://www.boost-consulting.com Boost support, enhancements, training, and commercial distribution |
From: David G. <go...@py...> - 2002-12-15 02:21:58
|
David Abrahams wrote: > The following line doesn't seem to format as expected: > > Those bracketed expressions are Python ``list``s. A ``list`` is > > I just wanted the word "list" to appear twice as an inline literal, > with the 's' following in a normal font. Is there a way to do this? reStructuredText's inline markup is designed to work at the phrase-level, not at the character level. So no, you can't do it, at least not directly. However, there is a work-around; certain punctuation characters *are* allowed adjacent to inline markup end-strings, such as apostrophes. So you could write it like this: Those bracketed expressions are Python ``list``'s. A ``list`` is (^ note the apostrophe) This rule allows for text like "Use double backquotes ("``") for inline literals." For all the gory details, see http://docutils.sf.net/spec/rst/reStructuredText.html#inline-markup -- David Goodger <go...@py...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
From: David A. <da...@bo...> - 2002-12-15 03:15:20
|
David Goodger <go...@py...> writes: > David Abrahams wrote: >> The following line doesn't seem to format as expected: >> >> Those bracketed expressions are Python ``list``s. A ``list`` is >> >> I just wanted the word "list" to appear twice as an inline literal, >> with the 's' following in a normal font. Is there a way to do this? > > reStructuredText's inline markup is designed to work at the phrase-level, > not at the character level. So no, you can't do it, at least not directly. > However, there is a work-around; certain punctuation characters *are* > allowed adjacent to inline markup end-strings, such as apostrophes. So you > could write it like this: > > Those bracketed expressions are Python ``list``'s. A ``list`` is > (^ note the apostrophe) > > This rule allows for text like "Use double backquotes ("``") for inline > literals." For all the gory details, see > > http://docutils.sf.net/spec/rst/reStructuredText.html#inline-markup David, Thanks for your reply. When I try your workaround I still get a grammatically incorrect apostrophe in the word "lists". Would it break anything if you added the backslash to the list of "certain punctuation characters"? That way, I could write ``list``\s and get exactly the effect I want. -- David Abrahams da...@bo... * http://www.boost-consulting.com Boost support, enhancements, training, and commercial distribution |
From: David G. <go...@py...> - 2002-12-15 05:24:20
|
David Abrahams wrote: > Thanks for your reply. When I try your workaround I still get a > grammatically incorrect apostrophe in the word "lists". Would it > break anything if you added the backslash to the list of "certain > punctuation characters"? That way, I could write ``list``\s and get > exactly the effect I want. Interesting idea. May work. I'll have to think it through. There may be adverse side-effects due to the way backslash-escapes are handled internally (they're converted to \x00 null bytes, which I've always thought was a bit of a kludge, but it's worked thus far). -- David Goodger go...@py... |
From: David G. <go...@py...> - 2002-12-17 02:34:11
|
[David Abrahams] > When I try your workaround I still get a grammatically incorrect > apostrophe in the word "lists". The apostrophe was inserted to provide a word boundary, but has no other meaning as markup. In other words, it's not supposed to disappear, so it doesn't. > Would it break anything if you added the backslash to the list of > "certain punctuation characters"? That way, I could write > ``list``\s and get exactly the effect I want. [David Goodger] > Interesting idea. May work. I'll have to think it through. There > may be adverse side-effects due to the way backslash-escapes are > handled internally (they're converted to \x00 null bytes, which I've > always thought was a bit of a kludge, but it's worked thus far). I tried it, it does work, and I can't think of any nasty side-effects. This neat trick allows for arbitrary text after inline markup: Those bracketed expressions are Python ``list``\s. So I've checked it in. Available now from CVS or in 20 minutes from the snapshot. I don't see a good way to allow for arbitrary text *before* inline markup though. Is there a need? We can't use a simple backslash, since that says "the following is *not* markup". Perhaps a certain escape sequence can be defined as "disappearing", like "\-" or "\." or "\'". ("\ " has already been proposed as a way to indicate non-breaking space; not implemented yet. After looking this up, it seems the "disappearing" idea isn't new either: <http://docutils.sf.net/spec/notes.html#character-processing>.) -- David Goodger <go...@py...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
From: David A. <da...@bo...> - 2002-12-18 21:45:03
|
David Goodger <go...@py...> writes: > [David Abrahams] >> When I try your workaround I still get a grammatically incorrect >> apostrophe in the word "lists". > > The apostrophe was inserted to provide a word boundary, but has no > other meaning as markup. In other words, it's not supposed to > disappear, so it doesn't. > >> Would it break anything if you added the backslash to the list of >> "certain punctuation characters"? That way, I could write >> ``list``\s and get exactly the effect I want. > > [David Goodger] >> Interesting idea. May work. I'll have to think it through. There >> may be adverse side-effects due to the way backslash-escapes are >> handled internally (they're converted to \x00 null bytes, which I've >> always thought was a bit of a kludge, but it's worked thus far). > > I tried it, it does work, and I can't think of any nasty side-effects. > This neat trick allows for arbitrary text after inline markup: > > Those bracketed expressions are Python ``list``\s. > > So I've checked it in. Available now from CVS or in 20 minutes from > the snapshot. Rock me, Amadeus. > I don't see a good way to allow for arbitrary text *before* inline > markup though. Is there a need? We can't use a simple backslash, > since that says "the following is *not* markup". But... inline markup doesn't happen within markup does it? the simple backslash outside of markup could mean "begin markup" if it precedes "``". 'course I'm probably missing something. > Perhaps a certain > escape sequence can be defined as "disappearing", like "\-" or "\." or > "\'". ("\ " has already been proposed as a way to indicate > non-breaking space; not implemented yet. After looking this up, it > seems the "disappearing" idea isn't new either: > <http://docutils.sf.net/spec/notes.html#character-processing>.) > -- > David Goodger <go...@py...> Open-source projects: > - Python Docutils: http://docutils.sourceforge.net/ > (includes reStructuredText: http://docutils.sf.net/rst.html) > - The Go Tools Project: http://gotools.sourceforge.net/ > > > > ------------------------------------------------------- > This sf.net email is sponsored by: > With Great Power, Comes Great Responsibility > Learn to use your power at OSDN's High Performance Computing Channel > http://hpc.devchannel.org/ -- David Abrahams da...@bo... * http://www.boost-consulting.com Boost support, enhancements, training, and commercial distribution |
From: David G. <go...@py...> - 2002-12-19 00:43:54
|
[David Goodger] >> So I've checked it in. Available now from CVS or in 20 minutes from >> the snapshot. [David Abrahams] > Rock me, Amadeus. Never thought I'd hear that again. Now I kinda wish I hadn't. >> I don't see a good way to allow for arbitrary text *before* inline >> markup though. Is there a need? We can't use a simple backslash, >> since that says "the following is *not* markup". > > But... inline markup doesn't happen within markup does it? Inline markup doesn't nest. Is that what you mean? > the simple backslash outside of markup could mean "begin markup" if it > precedes "``". > > 'course I'm probably missing something. The main reason for backslash-escapes to exist is to *prevent* markup recognition when it's not wanted:: Various forms of \*ML abound. The backslash "escapes" the normal meaning of whatever follows it. In this case:: Use brackets for Python ``list``\s we've extended the meaning of the backslash to escape the normal "text" meaning of the "s" to make it into a word-boundary. To do the same thing before the inline markup, I can only think of introducing a "disappearing escape sequence", like this: *re*\'``Structured``\'*Text* (italic "re" + monospaced "Structured" + italic "Text") That's awfully ugly though. -- David Goodger <go...@py...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
From: David A. <da...@bo...> - 2002-12-19 00:53:03
|
David Goodger <go...@py...> writes: > [David Abrahams] >> Rock me, Amadeus. > > Never thought I'd hear that again. Now I kinda wish I hadn't. Sorry ;-) >>> I don't see a good way to allow for arbitrary text *before* inline >>> markup though. Is there a need? We can't use a simple backslash, >>> since that says "the following is *not* markup". >> >> But... inline markup doesn't happen within markup does it? > > Inline markup doesn't nest. Is that what you mean? Yeah. >> the simple backslash outside of markup could mean "begin markup" if it >> precedes "``". >> >> 'course I'm probably missing something. > > The main reason for backslash-escapes to exist is to *prevent* markup > recognition when it's not wanted:: > > Various forms of \*ML abound. > > The backslash "escapes" the normal meaning of whatever follows it. In this > case:: > > Use brackets for Python ``list``\s > > we've extended the meaning of the backslash to escape the normal "text" > meaning of the "s" to make it into a word-boundary. To do the same thing > before the inline markup, I can only think of introducing a "disappearing > escape sequence", like this: > > *re*\'``Structured``\'*Text* > (italic "re" + monospaced "Structured" + italic "Text") > > That's awfully ugly though. It could be worse. I can think of one way to beautify cases like this: introduce a kind of quotation which removes all spaces in what it surrounds as a postprocessing step. ''*re* ``Structured`` *Text'' This would be analogous to re.VERBOSE, if memory serves. -- David Abrahams da...@bo... * http://www.boost-consulting.com Boost support, enhancements, training, and commercial distribution |
From: David A. <da...@bo...> - 2002-12-19 00:57:23
|
David Abrahams <da...@bo...> writes: > I can think of one way to beautify cases like this: introduce a kind > of quotation which removes all spaces in what it surrounds as a > postprocessing step. > > ''*re* ``Structured`` *Text'' Oops. ''*re* ``Structured`` *Text*'' ^ of course. -- David Abrahams da...@bo... * http://www.boost-consulting.com Boost support, enhancements, training, and commercial distribution |
From: David G. <go...@py...> - 2002-12-19 01:07:14
|
David Abrahams wrote: > I can think of one way to beautify cases like this: introduce a kind > of quotation which removes all spaces in what it surrounds as a > postprocessing step. > > ''*re* ``Structured`` *Text'' > > This would be analogous to re.VERBOSE, if memory serves. I'll add it to the character processing discussion in the To Do list, but I doubt the feature is worth the cost. -- David Goodger go...@py... |
From: David A. <da...@bo...> - 2003-03-10 13:31:21
|
David Goodger <go...@py...> writes: > David Abrahams wrote: >> I can think of one way to beautify cases like this: introduce a kind >> of quotation which removes all spaces in what it surrounds as a >> postprocessing step. >> >> ''*re* ``Structured`` *Text'' >> >> This would be analogous to re.VERBOSE, if memory serves. > > I'll add it to the character processing discussion in the To Do list, > but I doubt the feature is worth the cost. Has any progress been made in this general area? I am finding myself with the need for much finer character processing control, like the ability to switch between ``code`` and normal text on character boundaries, super/subscripts, and bold-italic fonts. It's very disappointing when I run up against limitations of ReST since it is otherwise such a pleasure. TIA, -- Dave Abrahams Boost Consulting www.boost-consulting.com |
From: David G. <go...@py...> - 2003-03-10 17:31:22
|
[David Abrahams] >>> I can think of one way to beautify cases like this: introduce a kind >>> of quotation which removes all spaces in what it surrounds as a >>> postprocessing step. >>> >>> ''*re* ``Structured`` *Text'' >>> >>> This would be analogous to re.VERBOSE, if memory serves. [David Goodger] >> I'll add it to the character processing discussion in the To Do list, >> but I doubt the feature is worth the cost. [David Abrahams] > Has any progress been made in this general area? No. I did add your idea to the To Do list, after this: - Escaped period or quote or dash as a disappearing catalyst to allow character-level inline markup? (<http://docutils.sf.net/spec/notes.html#character-processing>) I have strong reservations about the use of double-single-quotes as syntax, since they may be used in unrelated ways: as ''double quotes''; as empty strings as in text=''; or in ``TeX-style quotes'', although these have other problems. > I am finding myself > with the need for much finer character processing control, like the > ability to switch between ``code`` and normal text on character > boundaries, super/subscripts, and bold-italic fonts. How do you do super/subscripts in reStructuredText? Could you show us specific examples where you'd like to do character-level markup? > It's very disappointing when I run up against limitations of ReST since > it is otherwise such a pleasure. reStructuredText is inherently limited due to its WYSIWYG nature. To get past these limitations, ugly workarounds have to be added. Here's another idea: a "squeeze" directive used in a substitution:: Here's how to make |reStructuredText| do character-level markup. .. |reStructuredText| squeeze:: *re* ``Structured`` *Text* "Squeeze" will remove whitespace from its contents. ----------- Unfortunately for Docutils, I'm currenly trying to fulfill a low-level need [*]_ (get a job), so I don't feel much impetus to fulfill higher-level needs like writing open-source software. .. [*] http://chiron.valdosta.edu/whuitt/col/regsys/maslow.html -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: David A. <da...@bo...> - 2003-03-10 17:56:45
|
David Goodger <go...@py...> writes: > [David Abrahams] >>>> I can think of one way to beautify cases like this: introduce a kind >>>> of quotation which removes all spaces in what it surrounds as a >>>> postprocessing step. >>>> >>>> ''*re* ``Structured`` *Text'' >>>> >>>> This would be analogous to re.VERBOSE, if memory serves. > > [David Goodger] >>> I'll add it to the character processing discussion in the To Do list, >>> but I doubt the feature is worth the cost. > > [David Abrahams] >> Has any progress been made in this general area? > > No. I did add your idea to the To Do list, after this: > > - Escaped period or quote or dash as a disappearing catalyst to > allow character-level inline markup? > > (<http://docutils.sf.net/spec/notes.html#character-processing>) > > I have strong reservations about the use of double-single-quotes as syntax, > since they may be used in unrelated ways: as ''double quotes''; as empty > strings as in text=''; or in ``TeX-style quotes'', although these have other > problems. I'm not wedded to the syntax. ``` could work. >> I am finding myself with the need for much finer character >> processing control, like the ability to switch between ``code`` and >> normal text on character boundaries, super/subscripts, and >> bold-italic fonts. > > How do you do super/subscripts in reStructuredText? A1: You don't A2: See below > Could you show us specific examples where you'd like to do character-level > markup? In a pseudocode example, F(a1, a2,... aN) you might want most of the 'a's to be represented as ``code`` while the numbers and the 'N' are represented in an italic variable-width font (subscripted). >> It's very disappointing when I run up against limitations of ReST since >> it is otherwise such a pleasure. > > reStructuredText is inherently limited due to its WYSIWYG nature. To get > past these limitations, ugly workarounds have to be added. I think it might be enough to add a generalized escape which allows arbitrary ugliness when it's absolutely needed. That would still allow the rest of our ReST to stay pretty. Just off-the-cuff: ``X``..[subscript]*1*..[], ``X``..[subscript]*2*..[],...``X``..[subscript]*N*..[] > Here's another idea: a "squeeze" directive used in a substitution:: > > Here's how to make |reStructuredText| do character-level markup. > > .. |reStructuredText| squeeze:: > > *re* ``Structured`` *Text* > > "Squeeze" will remove whitespace from its contents. The problem is that it squeezes a whole paragraph. Unless... maybe we could have a category of directive which embeds a paragraph in the surrounding ones. That would allow nearly arbitrary markup changes without adding too much ugliness to the ReST language. > ----------- > > Unfortunately for Docutils, I'm currenly trying to fulfill a > low-level need [*]_ (get a job), so I don't feel much impetus to > fulfill higher-level needs like writing open-source software. Sorry to hear that; I wish I could help you. -- Dave Abrahams Boost Consulting www.boost-consulting.com |
From: David G. <go...@py...> - 2003-03-10 18:53:37
|
David Abrahams wrote: > I'm not wedded to the syntax. ``` could work. That would be ambiguous. Currently, to mark up a backquote as an inline literal, you'd use:: ````` That wouldn't be possible if we adopted ``` as "squeezing" markup. >> Could you show us specific examples where you'd like to do character-level >> markup? > > In a pseudocode example, > > F(a1, a2,... aN) > > you might want most of the 'a's to be represented as ``code`` while > the numbers and the 'N' are represented in an italic variable-width > font (subscripted). Thanks; good example. > I think it might be enough to add a generalized escape which allows > arbitrary ugliness when it's absolutely needed. That would still > allow the rest of our ReST to stay pretty. There is already such a generalized (although verbose) mechanism for inline markup: interpreted text with roles. They could be done like this:: subscript: `1`:sub: or :sub:`1` superscript: `2`:sup: or :sup:`2` There's still the problem of character-level markup though: whitespace is required. One of the tricks listed in the To Do list is to use an escaped character: Escaped period or quote or dash as a disappearing catalyst to allow character-level inline markup? Escaped dash isn't a good choice (may be useful as a soft hyphen). Periods are used as markup (explicit markup start, ".. "), so might legitimately be escaped without the intention of the period "disappearing". That leaves the quote. The idea was that this could be used as markup:: F(``a``\'`1`:sub:, ``a``\'`2`:sub:, ... ``a``\'`N`:sub:) Exceedingly ugly, don't you think? But combining this idea with setting up a "squeeze environment", I came up with this:: F(\"``a`` `1`:sub:\", \"``a`` `2`:sub:\", ... \"``a`` `N`:sub:\") Here, the escaped-double-quote sequence acts as "squeeze delimiters". Add in escaped spaces as non-breaking spaces, and the above could be condensed to:: \"F(``a`` `1`:sub:,\ ``a`` `2`:sub:,\ ...\ ``a`` `N`:sub:)\" Also ugly, but less obtrusively so (maybe). It's ugly, but specialized and obscure enough that it may not matter. Another example:: \"*re* ``Structured`` *Text*\" >> Here's another idea: a "squeeze" directive used in a substitution:: >> >> Here's how to make |reStructuredText| do character-level markup. >> >> .. |reStructuredText| squeeze:: >> >> *re* ``Structured`` *Text* >> >> "Squeeze" will remove whitespace from its contents. > > The problem is that it squeezes a whole paragraph. Only the "*re* ``Structured`` *Text*" paragraph, which is inserted into the preceding paragraph by the substitution mechanism. Yes, this example is a bit of a kludge. > Unless... maybe we could have a category of directive which embeds > a paragraph in the surrounding ones. Not sure what you mean. A directive can emit a paragraph; all directives used in substitutions have to. > That would allow nearly arbitrary markup changes > without adding too much ugliness to the ReST language. The processing of a directive's contents are up to the directive, so anything goes. >> ----------- >> >> Unfortunately for Docutils, I'm currenly trying to fulfill a >> low-level need [*]_ (get a job), so I don't feel much impetus to >> fulfill higher-level needs like writing open-source software. > > Sorry to hear that; I wish I could help you. Thanks. Wasn't meant to be a complaint, just a warning. Should have added: "Therefore don't expect a quick response". In any case, this would be a major syntax addition that needs to be well thought out. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: David A. <da...@bo...> - 2003-03-10 19:31:55
|
David Goodger <go...@py...> writes: > David Abrahams wrote: >> I'm not wedded to the syntax. ``` could work. > > That would be ambiguous. Currently, to mark up a backquote as an inline > literal, you'd use:: > > ````` > > That wouldn't be possible if we adopted ``` as "squeezing" markup. > >>> Could you show us specific examples where you'd like to do character-level >>> markup? >> >> In a pseudocode example, >> >> F(a1, a2,... aN) >> >> you might want most of the 'a's to be represented as ``code`` while >> the numbers and the 'N' are represented in an italic variable-width >> font (subscripted). > > Thanks; good example. > >> I think it might be enough to add a generalized escape which allows >> arbitrary ugliness when it's absolutely needed. That would still >> allow the rest of our ReST to stay pretty. > > There is already such a generalized (although verbose) mechanism for inline > markup: interpreted text with roles. They could be done like this:: > > subscript: `1`:sub: or :sub:`1` > superscript: `2`:sup: or :sup:`2` Nice! > There's still the problem of character-level markup though: whitespace is > required. > > One of the tricks listed in the To Do list is to use an escaped character: > > Escaped period or quote or dash as a disappearing catalyst to > allow character-level inline markup? > > Escaped dash isn't a good choice (may be useful as a soft hyphen). Periods > are used as markup (explicit markup start, ".. "), so might legitimately be > escaped without the intention of the period "disappearing". That leaves the > quote. The idea was that this could be used as markup:: > > F(``a``\'`1`:sub:, ``a``\'`2`:sub:, ... ``a``\'`N`:sub:) > > Exceedingly ugly, don't you think? Yes, but serviceable. Did we discuss the idea that escaped whitespace disappears? F(``a``\ `1`:sub:, ``a``\ `2`:sub:, ... ``a``\ `N`:sub:) > But combining this idea with setting up a "squeeze environment", I came up > with this:: > > F(\"``a`` `1`:sub:\", \"``a`` `2`:sub:\", ... \"``a`` `N`:sub:\") > > Here, the escaped-double-quote sequence acts as "squeeze > delimiters". Icky (IMO). > Add in escaped spaces as non-breaking spaces, and the above could be > condensed to:: > > \"F(``a`` `1`:sub:,\ ``a`` `2`:sub:,\ ...\ ``a`` `N`:sub:)\" > > Also ugly, but less obtrusively so (maybe). Yes. It's unfortunate that you really want '\ ' for a , since the need for breaking non-space comes up much more often in my work. > It's ugly, but specialized and > obscure enough that it may not matter. Another example:: > > \"*re* ``Structured`` *Text*\" > >>> Here's another idea: a "squeeze" directive used in a substitution:: >>> >>> Here's how to make |reStructuredText| do character-level markup. >>> >>> .. |reStructuredText| squeeze:: >>> >>> *re* ``Structured`` *Text* >>> >>> "Squeeze" will remove whitespace from its contents. >> >> The problem is that it squeezes a whole paragraph. > > Only the "*re* ``Structured`` *Text*" paragraph, which is inserted into the > preceding paragraph by the substitution mechanism. Yes, this example is a > bit of a kludge. Ah! I missed the substitution mechanism. >> Unless... maybe we could have a category of directive which embeds >> a paragraph in the surrounding ones. > > Not sure what you mean. A directive can emit a paragraph; all directives > used in substitutions have to. I think I just meant "substitution" ;-) > In any case, this would be a major syntax addition that needs to be > well thought out. There's the rub, eh? -- Dave Abrahams Boost Consulting www.boost-consulting.com |
From: David G. <go...@py...> - 2003-03-10 21:20:13
|
David Abrahams wrote: > Did we discuss the idea that escaped whitespace disappears? > > F(``a``\ `1`:sub:, ``a``\ `2`:sub:, ... ``a``\ `N`:sub:) No, I don't think we have. It's a definite possibility. There are many different ways to approach the problem. This one seems to be the most elegant so far. Writing the roles first makes it read better:: F(``a``\ :sub:`1`, ``a``\ :sub:`2`, ... ``a``\ :sub:`N`) > It's unfortunate that you really want '\ ' for a , I believe some people have expressed a desire for a non-breaking space in the past. If it was "really wanted", it would already be there. ;-) We're just talking now; no decisions yet. With Unicode and encodings available (UTF-8, Latin-1, etc.), we can directly code as \u00A0 or \xA0. Same with soft hyphens (­: \u00AD or \xAD), and any other Unicode character. This lessens (eliminates?) the need for the "escape sequence -> concrete character" kind of character processing. We're left with functional character processing, which is much more limited in scope. > since the need for breaking non-space comes up much more often in my work. What do you mean by "breaking non-space"? Do you mean "zero-width space", \u200B? -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: David A. <da...@bo...> - 2003-03-10 23:11:17
|
David Goodger <go...@py...> writes: > What do you mean by "breaking non-space"? Do you mean "zero-width space", > \u200B? No, I mean, "acts like whitespace as far as docutils parsing is concerned, but isn't whitespace in the output" -- Dave Abrahams Boost Consulting www.boost-consulting.com |