From goodger@python.org Mon Feb 3 20:07:57 2003 From: goodger@python.org (David Goodger) Date: Mon, 03 Feb 2003 15:07:57 -0500 Subject: [Doc-SIG] master plan for interpreted text? Message-ID: In response to a request for a new interpreted text role, I recently wrote, I don't want to let in all kinds of inline elements with marginal uses. I think this needs further discussion. In `The Chicago Manual of Style`, the section "Distinctive Treatment of Words" (6.62 through 6.91 in 14th ed.) lists many cases: * emphasis * foreign words * special terminology & technical terms * words used as words * letters as letters * musical dynamics (pianissimo as italic "pp" etc.) * letters indicating ryme schemes (as "aabba" for a limerick) All of these are mapped to italics. Should we have roles for each of them? Even if we combine closely-related cases (words as words & letters as letters; musical dynamics as a case of foreign words), we have 4 or 5 cases here. DocBook has dozens more inline elements. How far should we go? Apart from the purely-functional markup (hyperlink-related, substitutions), we have 4 types of inline markup: ``inline literals`` *emphasis* **strong** `interpreted text` *Emphasis* and **strong** are probably the most common inline markup used; they're also the most vaguely-defined. They're typically (but not always!) mapped as emphasis -> italic, and strong -> boldface. Should we have a slew of inline elements, with interpreted text roles mapping to them? The advantage is that the Docutils doc model becomes very rich, allowing fine distinctions of nuance. The disadvantage is code bloat: a lot more elements the Writers have to handle. If we want to set a limit, where? The to-do list has this item: add a runtime setting (directive and/or command-line option) to set the default role of interpreted text. I.E., map "`" to something. Should we have a directive to map other inline markup (i.e., "*" & "**", maybe even "``") to arbitrary inline element types? There are two sides to be considered: the reStructuredText markup, and the Docutils document model. Currently they can be considered two aspects of one system, but in the future there may be more markup languages supported. The reStructuredText markup is merely an interface to the document model, and the document model shouldn't pander to the markup too much. Comments? -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv From b.fallenstein@gmx.de Mon Feb 3 21:36:27 2003 From: b.fallenstein@gmx.de (Benja Fallenstein) Date: Mon, 03 Feb 2003 22:36:27 +0100 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: References: Message-ID: <3E3EE0DB.6050905@gmx.de> David Goodger wrote: > In `The Chicago Manual of Style`, the section "Distinctive Treatment > of Words" (6.62 through 6.91 in 14th ed.) lists many cases: > > * emphasis > * foreign words > * special terminology & technical terms > * words used as words > * letters as letters > * musical dynamics (pianissimo as italic "pp" etc.) > * letters indicating ryme schemes (as "aabba" for a limerick) > > All of these are mapped to italics. Should we have roles for each of > them? Even if we combine closely-related cases (words as words & > letters as letters; musical dynamics as a case of foreign words), we > have 4 or 5 cases here. DocBook has dozens more inline elements. How > far should we go? I'm thinking that following HTML's model may make sense: in addition to *emphasis* and **strong**, have `italics`:i: and `bold`:b:. So if there is no semantic class matching what you need, you just use one of these two. Another option would be being able to declare your own interpreted text roles and assigning them a class: Then, the writers would handle all of these in the same way, and the decision on how to render them would be a stylesheet issue. E.g., :: .. role:: foreign f This is the `de facto`:f: standard. And in a CSS stylesheet:: .foreign { font-style: italic } > The to-do list has this item: add a runtime setting (directive and/or > command-line option) to set the default role of interpreted text. > I.E., map "`" to something. Should we have a directive to map other > inline markup (i.e., "*" & "**", maybe even "``") to arbitrary inline > element types? This doesn't make sense to me; when I read a reST source, I parse the asterisks and backquotes in a certain way, and if a text would arbitrarily redefine them, the benefit would be lost. -1... - Benja From ianb@colorstudy.com Mon Feb 3 22:56:05 2003 From: ianb@colorstudy.com (Ian Bicking) Date: Mon, 3 Feb 2003 16:56:05 -0600 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: Message-ID: On Monday, February 3, 2003, at 02:07 PM, David Goodger wrote: > * emphasis > * foreign words > * special terminology & technical terms > * words used as words > * letters as letters > * musical dynamics (pianissimo as italic "pp" etc.) > * letters indicating ryme schemes (as "aabba" for a limerick) > > All of these are mapped to italics. Should we have roles for each of > them? Even if we combine closely-related cases (words as words & > letters as letters; musical dynamics as a case of foreign words), we > have 4 or 5 cases here. DocBook has dozens more inline elements. How > far should we go? I think there should be some plan in place to add extra types, but only add them as people request them. The richer the formatting, the less likely different people's markup will match each other -- in one place someone might use `pp`:music:, where another just uses *pp*, etc. The lack of semantic markup in the current version (I certainly think of *emphasis* and **strong** more in terms of their rendering and physical look than any semantics) makes this less of a problem, because semantics are highly ambiguous while rendered look is concrete. But if `something`:type: is valid for any "type", then I suppose it doesn't matter, so long as the output format has some way of identifying the proper styling. As I think about it though, it's non-trivial to effect any output but HTML. Anyway, in summary: just because you *can* identify a semantic classification doesn't mean you should. I seldom see the benefit, and before introducing more complexity into the system there should be a concrete reason someone wants to do so. E.g., they want to mark glossary terms for later compilation -- a very concrete desire. But if it is more work to restrict the kinds of semantic inline markups then to allow arbitrary semantics, then perhaps arbitrary semantics make more sense. In which case perhaps there should be a directive to give rendering hints (and hopefully definition hints!) in the document itself, as otherwise the document won't be portable. Ian From cben@techunix.technion.ac.il Mon Feb 3 23:08:32 2003 From: cben@techunix.technion.ac.il (Beni Cherniavsky) Date: Tue, 4 Feb 2003 01:08:32 +0200 (IST) Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: <3E3EE0DB.6050905@gmx.de> References: <3E3EE0DB.6050905@gmx.de> Message-ID: On 2003-02-03, Benja Fallenstein wrote: > David Goodger wrote: > > The to-do list has this item: add a runtime setting (directive and/or > > command-line option) to set the default role of interpreted text. > > I.E., map "`" to something. Should we have a directive to map other > > inline markup (i.e., "*" & "**", maybe even "``") to arbitrary inline > > element types? > > This doesn't make sense to me; when I read a reST source, I parse the > asterisks and backquotes in a certain way, and if a text would > arbitrarily redefine them, the benefit would be lost. -1... > I don't think that "*", "**", "``" should be re-definable but they should boil down to fixed interpreted text roles. Simplifies the internal document model. [If that's already the case, excuse my ignorance :-]. -- Beni Cherniavsky Gigga incognita :-) From a.schmolck@gmx.net Mon Feb 3 23:11:24 2003 From: a.schmolck@gmx.net (Alexander Schmolck) Date: 03 Feb 2003 23:11:24 +0000 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: References: Message-ID: David Goodger writes: > * emphasis > * foreign words > * special terminology & technical terms > * words used as words > * letters as letters > * musical dynamics (pianissimo as italic "pp" etc.) > * letters indicating ryme schemes (as "aabba" for a limerick) > > All of these are mapped to italics. Should we have roles for each of > them? Even if we combine closely-related cases (words as words & > letters as letters; musical dynamics as a case of foreign words), we > have 4 or 5 cases here. DocBook has dozens more inline elements. How > far should we go? -1 Of all the possible roles above only terminology (and/or acronyms) would seem to potentially profit from being specifically semantically tagged as such. Who is going to write a reST document in which he needs to process "musical dynamics" or "letters indicating ryme schemes" separately from emphasized text? If the need really arises then the user can always specify his own role tags. > The to-do list has this item: add a runtime setting (directive and/or > command-line option) to set the default role of interpreted text. > I.E., map "`" to something. Should we have a directive to map other > inline markup (i.e., "*" & "**", maybe even "``") to arbitrary inline > element types? +1 Obviously these should only be remapped to related element types (i.e. self-defined ones for special applications), but since the number of available lightweight markup elements is severely limited and readability of reST documents is an important goal, allowing the user the option to leverage these for his own purposes seems like a good thing to me. alex From goodger@python.org Tue Feb 4 05:26:24 2003 From: goodger@python.org (David Goodger) Date: Tue, 04 Feb 2003 00:26:24 -0500 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: <3E3EE0DB.6050905@gmx.de> Message-ID: Benja Fallenstein wrote: > I'm thinking that following HTML's model may make sense: in addition to > *emphasis* and **strong**, have `italics`:i: and `bold`:b:. So if there > is no semantic class matching what you need, you just use one of these two. I'm reluctant to enable explicit italic & bold roles. Even in HTML, their use is discouraged (although not deprecated... yet). > Another option would be being able to declare your own interpreted text > roles and assigning them a class: Then, the writers would handle all of > these in the same way, and the decision on how to render them would be a > stylesheet issue. E.g., :: > > .. role:: foreign f > > This is the `de facto`:f: standard. > > And in a CSS stylesheet:: > > .foreign { font-style: italic } That might be OK for HTML, but wouldn't apply to other formats. And how would it be represented in the intermediate data structure (the doctree)? As ````? That's the equivalent of ````, which was dropped in favour of concrete elements (e.g., ````). It might be feasible to declare a new role which is a modification of an existing role with a "class" attribute. Something like:: .. role:: foreign f :base: emphasis :class: foreign This would result in ```` when used. It would need a good use case though. And it would still be problematic for non-HTML output. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv From goodger@python.org Tue Feb 4 05:28:54 2003 From: goodger@python.org (David Goodger) Date: Tue, 04 Feb 2003 00:28:54 -0500 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: Message-ID: Ian Bicking wrote: > I think there should be some plan in place to add extra types, but only > add them as people request them. ... > Anyway, in summary: just because you *can* identify a semantic > classification doesn't mean you should. I seldom see the benefit, and > before introducing more complexity into the system there should be a > concrete reason someone wants to do so. E.g., they want to mark > glossary terms for later compilation -- a very concrete desire. That's reasonable. But what I'm trying to establish is where to draw the line? How much demand is enough to allow a new role in? It's been up to my judgement so far. Unless I hear some compelling arguments otherwise, I suppose it will remain that way. > But if `something`:type: is valid for any "type", It's not. "type" has to be one of a pre-defined set of roles for which there is parser and doctree support. Each role will have an associated method or function that understands the role's semantics. > then I suppose it doesn't matter, so long as the output format has > some way of identifying the proper styling. As I think about it though, > it's non-trivial to effect any output but HTML. ("Effect" or "affect"? Completely changes the meaning of the last sentence.) > But if it is more work to restrict the kinds of semantic inline markups then > to allow arbitrary semantics, then perhaps arbitrary semantics make more > sense. In which case perhaps there should be a directive to give rendering > hints (and hopefully definition hints!) in the document itself, as otherwise > the document won't be portable. There won't be arbitrary semantics, and there's no need or room for rendering hints in the markup. That's really basic: keep the style separate from the structure. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv From Paul.Moore@atosorigin.com Tue Feb 4 09:10:14 2003 From: Paul.Moore@atosorigin.com (Moore, Paul) Date: Tue, 4 Feb 2003 09:10:14 -0000 Subject: [Doc-SIG] master plan for interpreted text? Message-ID: <16E1010E4581B049ABC51D4975CEDB886199D2@UKDCX001.uk.int.atosorigin.com> From: David Goodger [mailto:goodger@python.org] > In `The Chicago Manual of Style`, the section "Distinctive Treatment > of Words" (6.62 through 6.91 in 14th ed.) lists many cases: > > * emphasis > * foreign words > * special terminology & technical terms > * words used as words > * letters as letters > * musical dynamics (pianissimo as italic "pp" etc.) > * letters indicating ryme schemes (as "aabba" for a limerick) I think there's a *very* good case for the "special terminology" case - so good, that I'd argue that it should be the default role in 99% of cases. Consider - what does a document use `...` for? The best answer (IMHO) would be "special words, in the context of this document". Which pretty much qualifies as "special terminology". We already have emphasis. I don't see the need for the others. Just possibly for foreign words, but I have to admit that I don't tend to bother with that level of precision myself. > Apart from the purely-functional markup (hyperlink-related, > substitutions), we have 4 types of inline markup: > > ``inline literals`` > *emphasis* > **strong** > `interpreted text` > *Emphasis* and **strong** are probably the most common inline markup > used; they're also the most vaguely-defined. I'd say that they are very precisely defined, just that they are the most often misused for things which are not their defined purpose! The *least* well defined is interpreted text - at least, I never know how I should use it! (That's probably because it's still in flux). And on the other hand, the one logical element of my documents I always have trouble marking up is "special terms". I'd love interpreted text (in the default case) to take on that role for me. > The to-do list has this item: add a runtime setting (directive and/or > command-line option) to set the default role of interpreted text. > I.E., map "`" to something. Should we have a directive to map other > inline markup (i.e., "*" & "**", maybe even "``") to arbitrary inline > element types? -1. The other inline markup has strongly defined, fixed meaning. Don't change this. Paul. From Mark.Nodine@mot.com Tue Feb 4 17:57:44 2003 From: Mark.Nodine@mot.com (Mark Nodine) Date: Tue, 04 Feb 2003 11:57:44 -0600 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? References: Message-ID: <3E3FFF18.78316993@somerset.sps.mot.com> David Goodger wrote: > > But if `something`:type: is valid for any "type", > > It's not. "type" has to be one of a pre-defined set of roles for which > there is parser and doctree support. Each role will have an associated > method or function that understands the role's semantics. I'm confused. There seems to be parser and doctree support, since it winds up in the pseudo-XML as:: Can't the role be any string consisting of [a-zA-Z0-9_.-]+ ? --Mark From goodger@python.org Tue Feb 4 18:03:00 2003 From: goodger@python.org (David Goodger) Date: Tue, 04 Feb 2003 13:03:00 -0500 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: <3E3FFF18.78316993@somerset.sps.mot.com> Message-ID: Mark Nodine wrote: > David Goodger wrote: >> It's not. "type" has to be one of a pre-defined set of roles for which >> there is parser and doctree support. Each role will have an associated >> method or function that understands the role's semantics. > > I'm confused. There seems to be parser and doctree support, since it winds > up in the pseudo-XML as:: > > > > Can't the role be any string consisting of [a-zA-Z0-9_.-]+ ? You must be looking at old code. That was never intended to be the final implementation, just a temporary placeholder. The spec & code were revised about a month ago. See my Jan 9 post, 'Docutils update: "interpreted text" reimplemented'. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv From cben@techunix.technion.ac.il Tue Feb 4 22:05:14 2003 From: cben@techunix.technion.ac.il (Beni Cherniavsky) Date: Wed, 5 Feb 2003 00:05:14 +0200 (IST) Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: References: Message-ID: On 2003-02-04, David Goodger wrote: > Benja Fallenstein wrote: > > I'm thinking that following HTML's model may make sense: in addition to > > *emphasis* and **strong**, have `italics`:i: and `bold`:b:. So if there > > is no semantic class matching what you need, you just use one of these two. > > I'm reluctant to enable explicit italic & bold roles. Even in HTML, their > use is discouraged (although not deprecated... yet). > IIRC, XHTML 2 does this bold step. No physicall formating provided (CSS can do it all anyway). -- Beni Cherniavsky If somebody builds a time machine he can gateway the Internet to itself with a time offset. I wonder what implications that would have... From cben@techunix.technion.ac.il Tue Feb 4 22:15:56 2003 From: cben@techunix.technion.ac.il (Beni Cherniavsky) Date: Wed, 5 Feb 2003 00:15:56 +0200 (IST) Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: References: Message-ID: On 2003-02-04, David Goodger wrote: > Ian Bicking wrote: > > I think there should be some plan in place to add extra types, but only > > add them as people request them. > ... > > Anyway, in summary: just because you *can* identify a semantic > > classification doesn't mean you should. I seldom see the benefit, and > > before introducing more complexity into the system there should be a > > concrete reason someone wants to do so. E.g., they want to mark > > glossary terms for later compilation -- a very concrete desire. > > That's reasonable. But what I'm trying to establish is where to draw the > line? How much demand is enough to allow a new role in? It's been up to my > judgement so far. Unless I hear some compelling arguments otherwise, I > suppose it will remain that way. > You can draw quite a good line for the commonly needed roles. The ones you throw out are not appropriate for the common implementation but are specific people will want them for themselves. Any big document / group of documents has roles specific to it. > > But if it is more work to restrict the kinds of semantic inline markups then > > to allow arbitrary semantics, then perhaps arbitrary semantics make more > > sense. In which case perhaps there should be a directive to give rendering > > hints (and hopefully definition hints!) in the document itself, as otherwise > > the document won't be portable. > > There won't be arbitrary semantics, and there's no need or room for > rendering hints in the markup. That's really basic: keep the style separate > from the structure. > Great idea. But for doing it, you must be able to define your own classes of structure. Think of it: would CSS be useful without classes and ids? -- Beni Cherniavsky If somebody builds a time machine he can gateway the Internet to itself with a time offset. I wonder what implications that would have... From fdrake@acm.org Tue Feb 4 22:22:14 2003 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Tue, 4 Feb 2003 17:22:14 -0500 Subject: [Doc-SIG] Re: [Docutils-develop] master plan for interpreted text? In-Reply-To: References: Message-ID: <15936.15638.962192.246733@grendel.zope.com> Beni Cherniavsky writes: > IIRC, XHTML 2 does this bold step. No physicall formating provided (CSS > can do it all anyway). Yes, XHTML 2 looks like an improvement (finally). Unfortunately, the weight of the installed base of browsers is enough that some of us have pretty much given up on anything derived from HTML. -Fred -- Fred L. Drake, Jr. PythonLabs at Zope Corporation From master@89894.com Tue Feb 11 03:01:17 2003 From: master@89894.com (½Å¿ë ö) Date: Tue, 11 Feb 2003 12:01:17 +0900 Subject: [Doc-SIG] (no subject) Message-ID: <278700-2200322113117609@89894.com>

=C1=A4=BA=B8=C5=EB=BD=C5=BA=CE =B1=C7=B0=ED =BB=E7=C7=D7=BF= =A1 =C0=C7=B0=C5 =C1=A6=B8=F1=BF=A1 [=B1=A4=B0=ED]=B6=F3=B0=ED =C7=A5=B1=E2=C7=D1 =B1=A4=B0=ED =B8=DE=C0= =CF=C0=D4=B4=CF=B4=D9=2E
=BC=F6=BD=C5=C0=BB =BF=F8=C4=A1 =BE=CA=C0=B8=BD= =C3=B8=E9 = =BC=F6=BD=C5=B0=C5=BA=CE=B8=A6 =B4=AD=B7=AF=C1=D6=BC=BC=BF=E4

 

[=B0=FA=C7=D0]  =B2=DE=C0=C7 =BF=A1=B3=CA=C1=F6 =B9=AB=C7=D1 =B5=BF= =B7=C2

=B9=AB=C7=D1 =B5=BF=B7=C2=C0=BA =B2=DE=C0=C7 =BF=A1=B3=CA=C1=F6=B0=A1 =BE= =C6=B4=D2 =BC=F6 =BE=F8=BD=C0=B4=CF=B4=D9=2E=2E=2E=2E
=C8=AD=BC=AE =BF=AC= =B7=E1=B8=A6 =BB=E7=BF=EB=C7=CF=C1=F6 =BE=CA=B0=ED,
=BF=AC=B7=E1=B0=A1=BE=F8=C0=CC =B5=B9=BE=C6=B0=A1=B4=C2 = =BF=A3=C1=F8=C0=CC =C0=D6=B4=D9=B8=E9 =BF=A1=B3=CA=C1=F6=BF=A1=20 =B4=EB=C7=D1 =B9=AE=C1=A6=B4=C2 =B8=F0=B5=CE =C7=D8=B0=E1=B5=C9 =BC=F6 =C0= =D6=B0=DA=C1=F6=BF=E4=2E
=C0=DA=B5=BF=C2=F7=B0=A1 =B1=E2=B8=A7=C0=CC =BE= =F8=C0=CC =B4=DE=B8=B1 =BC=F6=C0=D6=B4=D9=B8=E9=2E=2E=2E=2E=2E?
=BF=AC=B7=E1=B8=A6 =BE=B2=C1=F6= =BE=CA=B0=ED =B9=DF=C0=FC=B1=E2=BF=A1=BC=AD =B9=AB=C7=D1=C1=A4 =C0=FC=B1=E2= =B0=A1=20 =B9=DF=BB=FD=B5=C8=B4=D9=B8=E9 =B1=D7 =BE=EE=B5=F0=BF=A1=BC=AD=B5=E7=C1=F6= =C0=CE=B0=A3=C0=C7 =BB=EE=C0=BA =C7=B3=BF=E4=B7=CE=BF=EF=B0=CD=C0=CC=B8=E7= ,
=C8=AD=BC=AE =BF=AC=B7=E1=C0=C7 =B8=C5=BF=AC =B0=F8=C7=D8=B9=AE=C1=A6=B4=C2 =B4=F5 =C0=CC=BB=F3=C0=C7 =BF=AC=B1=B8 =B4=EB= =BB=F3=C0=CC =B5=C9 =BC=F6 =BE=F8=C0=B8=B8=E7=2E=2E=2E=2E=2E

=B1=D7=B7=AF=B3=AA =BE=D6=BC=AE =C7=CF=B0=D4=B5=B5 =BE=C6=C1=F7 =BF=EC=B8= =AE =C0=CE=B7=F9=B4=C2  =C0=CC =B9=AB=C7=D1 =B5=BF=B7=C2=C0=BB =B0=B3= =B9=DF=C0=BB =BC=BA=B0=F8 =C7=CF=C1=F6 =B8=F8=C7=DF=BD=C0=B4=CF=B4=D9=2E=2E=2E=2E=2E

=B8=B9=C0=BA =BB=E7=B6=F7=C0=CC =BF=A9=B1=E2=BF=A1 =B5=B5=C0=FC=C0=BB =C7= =CF=B0=ED =C0=D6=C0=B8=B8=E7 =BC=BA=B0=F8=C0=C7 =B1=D7 =BC=F8=B0=A3  = =C0=CE=B7=F9=C0=C7 =C7=E0=BA=B9=C0=CF=B0=CD=C0=D4=B4=CF=B4=D9=2E=2E=2E=2E
=C0=CE=B0=A3=C0=BA= =C0=FA =B9=AB=C7=D1=C0=C7 =B0=F8=B0=A3=20
=BF=EC=C1=D6=B7=CE  =BF=EC=C1=D6=B7=CE =B0=C5=C4=A7=BE=F8=C0=CC =B9= =DF=C0=FC=C7=D8 =B3=AA=B0=A5 =B0=CD=C0=D4=B4=CF=B4=D9=2E=2E=2E

=C0=CC=B4=C2 =B0=F8=B0=A3 =C1=A6=C7=D1=C0=BB =B9=E7=C1=F6=BE=CA=B0=ED =BF= =A1=B3=CA=C1=F6=B8=A6 =B9=AB=C7=D1=BB=FD=BB=EA=C7=D2 =BC=F6 =C0=D6=B4=C2 =B9= =AB=C7=D1 =B5=BF=B7=C2=C0=CC =C0=D6=C0=BB =B0=E6=BF=EC=BF=A1=B8=B8 =B0=A1=B4=C9=C7=D1 =C0=CF=C0=D4=B4=CF=B4=D9=2E=2E= =2E

=BF=A9=B1=E2=BF=A1 =B0=ED=C1=A4 =BF=A1=B3=CA=C1=F6=B8=A6 =C0=CC=BF=EB=C7= =D1 =BF=A3=C1=F8=C0=BB 16=B3=E2=B0=A3=BF=A1=B0=C9=C3=C4 =B2=D9=C1=D8=C8=F7= =B0=B3=B9=DF=C7=CF=B0=ED=C0=D6=C0=B8=B8=E7 =C3=D6=B1=D9 5=B3=E2=BF=A9=B5=BF=BE=C8 6=C8=B8=BF=A1=B0=C9=C3=C4 =BA=CE=BA= =D0 =BA=CE=BA=D0=C0=BB =C1=A6=C0=DB=C7=CF=BF=A9 =B0=CB=C1=F5=C0=BB =C7=D8=BF= =C2=B9=D9=20 =C1=F6=B1=DD=C0=BA =BC=B3=B0=E8=B0=A1 =B8=B6=B9=AB=B8=AE=B5=C7=BE=EE =C1=BE= =C7=D5 =C0=FB=C0=CE =C1=A6=C0=DB =B0=FA=C1=A4=BF=A1 =BF=CD=C0=D6=C0=B8=B8=E7= ,

=BA=B8=B4=D9 =B8=B9=C0=BA =C0=CC =B5=E9=B7=CE=BA=CE=C5=CD =C7=D4=B2=B2 = =C7=CF=B0=ED=C0=DA =C4=AB=C6=E4 =BB=E7=C0=CC=C6=AE=B8=A6 =B0=B3=BC=B3=C7=CF= =BF=A9 =B5=BF=C8=A3=C0=CE=C0=C7 =B2=DE=C0=BB =B8=B8=B5=E9=BE=EE =B0=A1=B0=ED=C0=DA =C7=D5=B4=CF=B4=D9=2E=2E=2E

=C4=AB=C6=E4 =BB=E7=C0=CC=C6=AE :  cafe=2Edaum=2Enet/106030 =C0=D4= =B4=CF=B4=D9=2E

=B8=B9=C0=CC =B9=E6=B9=AE=C7=CF=BD=C3=BE=EE =C0=DA=B7=E1 =B0=CB=BB=F6=C7= =CF=BD=C3=B0=ED =B6=C7 =B1=DB=C0=BB =B8=B9=C0=CC =BF=C3=B7=C1 =C1=D6=BC=BC= =BF=E4=2E=2E=2E=2E

  ^^ ** ^^   ^^ ** ^^  

tel : 011-281-1434  =BD=C5  =BF=EB  =C3=B6


From smerten@oekonux.de Mon Feb 24 22:57:56 2003 From: smerten@oekonux.de (Stefan Merten) Date: Mon, 24 Feb 2003 23:57:56 +0100 Subject: [Doc-SIG] reStructuredText: What a cool idea!! Message-ID: <200302242257.h1OMvu031049@rosalu.merten-home.de> -----BEGIN PGP SIGNED MESSAGE----- Hi hackers and others, first of all I'd like to apologize if this is off-topic on this list. If so it would be nice if someone could tell me, where this belongs to. I don't know whether you already know, but reStructuredText is mentioned on http://www.ibm.com/developerworks/library/x-matters24/ I saw it there, read the specification and some more - and I'm absolutely delighted :-) !! First, I'd like to tell you a bit about my background. I love the Perl idea of embedding documentation in the source code using POD. To me it became a habit documenting everything while or often even before coding something. I guess that was, what Larry had in mind when inventing POD :-) . Another nice aspect of POD is, that it's ASCII based and thus it is useful to use CVS on it and/or the miracles of the Emacs' ediff package. And of course you do not need any special editor to work with this format. Instead every editor supporting plain ASCII works. And nonetheless you can produce lots of output formats. By a simple `make' call if you like. All in all POD allowed for a lot of nice features with a high degree if automatization, versioning and so on. So I started to write all my documents in POD. However, POD is a rather limited markup format. If you want to write something different from a manual page you'll immediately run into a number of limitations. So I looked for an alternative. I found SDF [http://search.cpan.org/author/IANC/sdf-2.001/, the original site doesn't exist any more but it is embedded in the package]. SDF is a rather great tool very much in the spirit of reStructuredText. One feature I particularly like is, that it is possible to embed (Perl) code in your text document to do some very specific job. Anyway it is easy to combine SDF with Perl to create really great stuff. The most elaborated thing I did with SDF were some filters which take a high level interface description for an API and produce include files for C, C++, Sicstus Prolog, and Java. Well, since I discovered SDF I'm using SDF for nearly everything. In particular the web sites I'm maintaining are all created by SDF and `make'. However, SDF has a number of drawbacks: * The code is based on Perl 4 (before references were invented in Perl) and it's - ummm - somewhat ugly. I thought about rewriting it from scratch but I've got no time for such a task. * There is a great number of nice ideas but there is not much of an overall concept. * No community developed - at least no community visible to me. This may be partly because the maintainer Ian Clatworthy (thanks Ian for all of your efforts) seemingly gave up the project shortly after I discovered it (in 1999). (I never contacted him, so I could not have been the reason ;-) .) * It did not reach a wide distribution and thus virtually nobody is used to using it. So though personally I'm rather happy with SDF I don't like the thought of being trapped in a evolutionary dead end. And now I found reStructuredText. I read the specification and though today reStructuredText misses some things of what SDF has, I see that there is a potential for reStructuredText for being a very powerful tool - much more than SDF ever was. Particularly because there seems to be an active maintainer (thanks David Goodger and all for the *great* web site, I particularly like that the discussion of alternatives is listed) and seemingly a very interested community. Personally I think it would be a great gift to the world to establish a text format which is easy to write but yet powerful. In short: I fully support all the goals listed for reStructuredText. I think over time I'll reformat all my sources to use reStructuredText. Ahmm - as you may have noted I'm coming from the Perl community and I don't know Python yet and at the moment I'm not planning to change that. But when talking about a format this is of little importance of course. Well, now you know why I'm here :-) . Now for the question part of this mail. Indeed I have a number of questions about reStructuredText and it's implementation. I'm sorry if any of these questions is already answered on one some web page. I did not read all of the pages yet. * Is there a Perl implementation already? Does anybody plan such a beast? Admittedly I thought of doing it - but my time is *very* limited :-( . However, that's a itch I'd like to scratch. * Is there a Emacs mode already? Particularly it there `font-lock' support for reStructuredText documents available? Personally I got used so much to font-locking I find it an unbearable pain to read text containing formal syntax without appropriate coloring. If no such thing is available I could give it a try. * Are there transformation tools from OpenOffice format to reStructuredText? This question may need some explanation. I have the problem, that sometimes I receive M$ `.doc's and `.ppt's or `.rtf's I'd like to transform to SDF to embed them in a web site. Before OpenOffice and it's XML based document format this was a difficult task needing a lot of unautomatable work. I wrote a tool for RTF but Powerpoint was beyond automatization. For SDF lately I created a suite of XSLT style sheets which transform the `styles.xml' and `content.xml' contained in `.sxw' and `.sxc' to SDF. Though this involves some post processing by hand it is *much* easier than anything I did before. In effect by (ab)using the input filters of OpenOffice I now have a whole lot of formats I can transform to SDF with reasonable effort. Of course I'd like to see this for reStructuredText as well. If no-one did this until know, I could rewrite my XSLT scripts a bit to support reStructuredText. * Is there a transformation for Docutils Document Tree documents in XML to a reStructuredText source form? Or following PEP 258: Is there a writer for reStructuredText? If so the Docutils Document Tree could be used as an XML based representation and all the nice things of XML are available. For instance one could write an XSLT transformation from an OpenOffice format to Docutils Document Tree format and transformations in all thinkable directions are possible. * Are there plans to support embedded code in reStructuredText documents? The embedded code needs access to the embedding document of course. May be this is similar to JavaScript embedded in HTML pages. Of course I'd prefer support for Perl ;-) . * Are there writers for plain text and/or manual pages? Finally I'd like to draw your attention to http://template-toolkit.org/ It's a very cool tool which allows for a wide range of automation. It virtually adds a powerful macro language to every ASCII based format. One thing I particularly liked with SDF is the feature to embed SDF or other stuff in anything which supports comments. This way you were able to embed for instance POD documentation in a C++ file. One of the nice features is, that it rearranges the embedded code allowing you to write your documentation at the place of the definition and nonetheless get every piece of documentation at the right place in the final document. However, as SDF is usually not available this feature is of limited use if you're going to share your source with others :-( . In the free software project I started lately [http://savannah.nongnu.org/projects/mamo/] I created a plug-in for the Template Toolkit which exactly does this sort of gathering of snippets of documentation from an arbitrary source file [http://savannah.nongnu.org/cgi-bin/viewcvs/mamo/mamo/lib/perl5/Mamo/Temp= late/Plugin/Gather.pm]. Thinking reStructuredText and Docutils it might qualify as the input part of a reader. Mit Freien Gr=FC=DFen Stefan -----BEGIN PGP SIGNATURE----- Version: 2.6.3in Charset: noconv Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface iQCVAwUBPlqjdAnTZgC3zSk5AQGjVgQArL3NYg0OThGf7Xi++LJPUgKnS0HyRfT6 bek6sjLiYOSfDLQPFAfWjeVhRKaMt4P+nKhIqVPuT/Jfe3nj/LgxTOMdWspjE7gU CT6VA2qKNpuAAvoIc9BoW9nL4bQE3fgnETENtdZROlg4kiQLwGKzTr1VWs+uLvqt nSzPi3EddpI=3D =3DalwL -----END PGP SIGNATURE----- From goodger@python.org Thu Feb 27 04:39:34 2003 From: goodger@python.org (David Goodger) Date: Wed, 26 Feb 2003 23:39:34 -0500 Subject: [Doc-SIG] reStructuredText: What a cool idea!! In-Reply-To: <200302242257.h1OMvu031049@rosalu.merten-home.de> Message-ID: Stefan Merten wrote: > first of all I'd like to apologize if this is off-topic on this > list. Not really off-topic here, but there are two Docutils-specific lists also: for usage questions, and for developers. Recent archives are also available at . This list is more general and it has a greater readership. > I don't know whether you already know, but reStructuredText is > mentioned on > > http://www.ibm.com/developerworks/library/x-matters24/ Yes, it's a good article. A few details could be corrected, but nothing major. > I saw it there, read the specification and some more - and I'm > absolutely delighted :-) !! Glad you like it. > * Is there a Perl implementation already? Does anybody plan such a > beast? Mark Nodine is working on a Perl implementation of the reStructuredText parser. He hasn't released any code yet, though. > * Is there a Emacs mode already? Not yet. There are a few functions in tools/editors/emacs/restructuredtext.el, available from CVS or the snapshot (). > Particularly it there `font-lock' > support for reStructuredText documents available? No. It's an interesting idea, although I'm not sure how it would work. > If no such thing is available I could give it a try. Please do! > * Are there transformation tools from OpenOffice format to > reStructuredText? There is work being done on OpenOffice.org XML *writers*, but nothing to my knowledge the other way. > For SDF lately I created a suite of XSLT style sheets which > transform the `styles.xml' and `content.xml' contained in `.sxw' > and `.sxc' to SDF. Though this involves some post processing by > hand it is *much* easier than anything I did before. Sounds like a good approach. I've heard of people setting up semi-automated systems to assist with conversion. > Of course I'd like to see this for reStructuredText as well. If > no-one did this until know, I could rewrite my XSLT scripts a bit > to support reStructuredText. Such code would be welcome. > * Is there a transformation for Docutils Document Tree documents in > XML to a reStructuredText source form? Or following PEP 258: Is > there a writer for reStructuredText? There has been some discussion about a generic to-reStructuredText conversion system, perhaps a Docutils "Writer", but no implementation yet. > * Are there plans to support embedded code in reStructuredText > documents? I believe Mark Nodine's Perl implementation has it. There are notes about at . Such a feature is inherently dangerous though, and there have to be safeguards in place to prevent reStructuredText/Docutils being used as a vector for viruses & trojans. > * Are there writers for plain text and/or manual pages? Not that I know of. I recall some discussion, but nothing concrete. > Finally I'd like to draw your attention to > > http://template-toolkit.org/ Looks useful, but templating systems are plentiful. > One thing I particularly liked with SDF is the feature to embed SDF > or other stuff in anything which supports comments. This way you > were able to embed for instance POD documentation in a C++ file. One > of the nice features is, that it rearranges the embedded code > allowing you to write your documentation at the place of the > definition and nonetheless get every piece of documentation at the > right place in the final document. Sounds like "literate programming". Do you have a link to a description of how SDF accomplishes this rearranging? > In the free software project I started lately > [http://savannah.nongnu.org/projects/mamo/] I created a plug-in for > the Template Toolkit which exactly does this sort of gathering of > snippets of documentation from an arbitrary source file ... > Thinking reStructuredText and Docutils it might qualify as the input > part of a reader. I don't understand the implications. Can you describe this for us? -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv