Menu
▾
▴
docutils-users
|
From: Moore, P. <Pau...@at...> - 2003-05-08 08:36:32
|
From: Martin Blais [mailto:bl...@ir...]
> i was thinking of something with similar input recently: i wanted to =
have
> the quote's displayed aligned to the right. now i know how to do that =
with a
> CSS trick, but it wouldn't work in LaTeX for example.
>
> which got me thinking about... if it would be possible to find a way =
to
> recognize some text prefix within reST that would be "aligned" to the =
right,
> without a special directive... for example:
>=20
> | "I have made this letter longer than =
usual,
> | because I lack the time to make it =
short."
> | ---Blaise =
Pascal
>=20
> if i look at this within the text file, it appears to me as a blob of =
text
> that is aligned to the right.
Interesting. My immediate reaction was (probably the same as David's =
:-)) "Use
a directive". I'd suggest::
.. right::
| "I have made this letter longer than =
usual,
| because I lack the time to make it =
short."
| ---Blaise =
Pascal
where the "right" directive strips leading whitespace and "|" =
characters. This
preserves the look for plain text, while using the existing directive =
scheme
to present the right information to formatters.
The only problem is, I don't know what the directive should *output*. =
It's the
same old issue again, the docutils document tree is fixed, and =
right-aligned
blocks aren't a "known" construct. You could hijack an existing element =
(cite
seems the most appropriate) but that seems like a kludge. We're back to =
the
idea of allowing arbitrary classes on elements, maybe <cite =
class=3D"right"> in
this case, or if David wants to keep things controlled, a <div> =
equivalent.
Sigh. Maybe the doctree stuff is more flexible than I'm seeing (I'm not =
an XML
expert, and all the DTD stuff in the doctree spec confuses me rather =
than
helping :-() but it still seems to me like the flexibility bottleneck in =
all
this...
Paul.
|
|
From: Martin B. <bl...@ir...> - 2003-05-08 09:31:15
|
On Thursday 08 May 2003 18:36, Moore, Paul wrote: > From: Martin Blais [mailto:bl...@ir...] > > > i was thinking of something with similar input recently: i wanted to = have > > the quote's displayed aligned to the right. now i know how to do that > > with a CSS trick, but it wouldn't work in LaTeX for example. > > > > which got me thinking about... if it would be possible to find a way = to > > recognize some text prefix within reST that would be "aligned" to the > > right, > > > > without a special directive... for example: > > | "I have made this letter longer than > > | usual, because I lack the time to make = it > > | short." ---Blaise Pascal > > > > if i look at this within the text file, it appears to me as a blob of > > text that is aligned to the right. > > Interesting. My immediate reaction was (probably the same as David's :-= )) > "Use a directive". I'd suggest:: > > .. right:: > | "I have made this letter longer than > | usual, because I lack the time to make = it > | short." ---Blaise Pascal > > where the "right" directive strips leading whitespace and "|" character= s. > This preserves the look for plain text, while using the existing direct= ive > scheme to present the right information to formatters. personally, that's exactly what i would try as much as possible to avoid,= in=20 fact, i would go as far as to give up on my desire to have right-alignmen= t=20 capability at all if it was provided this way because it introduces yet e= ven=20 more markup (more below) > The only problem is, I don't know what the directive should *output*. I= t's > the same old issue again, the docutils document tree is fixed, and > right-aligned blocks aren't a "known" construct. You could hijack an > existing element (cite seems the most appropriate) but that seems like = a > kludge. We're back to the idea of allowing arbitrary classes on element= s, > maybe <cite class=3D"right"> in this case, or if David wants to keep th= ings > controlled, a <div> equivalent. i'm not familiar with the doctree data structures yet, and what i had in = mind=20 is for this to translate into a known construct, or perhaps like you sugg= est,=20 a citation or paragraph with a "right" attribute attached to it (but with= out=20 the need to add the directive) this may be a little bit off-subject: i feel that if by running "more" o= n the=20 file our brains can interpret that this is right-aligned, there must be a= way=20 that we can find minimal unambiguous notation (i.e. in this case the pipe= s,=20 not explicit markup) to make the parser add this information into the=20 doctree. more generally: shouldn't we strive to provide structure for much of what= can=20 be expressed reasonably within a plain text file ...rather than the=20 opposite? i see two directions that features are discovered/desired: 1) constructs commonly expressed within a text file recognized by the par= ser=20 and semantic added to it. in other words, we look at usual plain text fi= les,=20 and try to automatically extract as much meaning as possible from them. = if=20 some feature proves impossible to parse, we should offer the question: "h= ow=20 can we change the *notation* as little as possible to make it parseable a= nd=20 unambiguous, without jeopardizing parsing or other features?" (by the=20 previous use of "notation", i do not include things like directives) 2) a feature supported in the desired output format but is not obvious ho= w to=20 do in plain text is added with either special notation or markup; IMHO i don't see any problem in adding all the possible reasonable featur= es in=20 (1) to the parser and the doctree, while (2) worries me a great deal, bec= ause=20 that pushes towards adding markup (especially for features only available= in=20 certain output types), which goes against what i gather being the primary= =20 motivation for something like reST (i.e. convenience by minimizing markup= (i=20 personally read: removing markup)). A good example of an exception to this is "an image", because images are=20 immensely useful, so having a "directive" for that is entirely reasonable= ,=20 because of the great amount of expressiveness you gain with having images= in=20 your documents. However, if some output format support some rare construc= t=20 not available in "general documents", we should become suspicious (sorry = no=20 good example comes to mind right now). now to go back to the subject: i just wanted to say that i feel that the= =20 right-alignment as suggested above fits snuggly into (1). i can express = it=20 in plain text and everyone sees it for what it is in the source, thus it=20 seems reasonable to me that the doctree would be able to reflect this=20 meaning. (another debate is whether reST should separate form vs. function, in whi= ch=20 case some would argue that right-alignment is a matter of form and should= not=20 be in the source reST, but then again, that separation is one of the main= =20 motivations for markup languages... an interesting question is: on that=20 scale, where does reST lie? the answer is not obvious to me, since i do = care=20 that my source reST files look good and simple, so form matters in the so= urce=20 too...) cheers, |
|
From: David G. <go...@py...> - 2003-05-09 05:10:51
|
[Martin Blais]
>>> i was thinking of something with similar input recently: i wanted
>>> to have the quote's displayed aligned to the right. now i know how
>>> to do that with a CSS trick, but it wouldn't work in LaTeX for
>>> example.
>>>
>>> which got me thinking about... if it would be possible to find a
>>> way to recognize some text prefix within reST that would be
>>> "aligned" to the right,
>>>
>>> without a special directive... for example:
>>> | "I have made this letter longer than
>>> | usual, because I lack the time to make it
>>> | short." ---Blaise Pascal
>>>
>>> if i look at this within the text file, it appears to me as a blob
>>> of text that is aligned to the right.
To me, it looks more like a blob of text that's sort-of aligned to the
left but has a large left margin: a super-block-quote. Engelbert's
idea looks much more right-aligned::
"I have made this letter longer than usual, |
because I lack the time to make it short." |
|
---Blaise Pascal |
It would be a pain to edit though; almost as bad as editing ASCII
tables. In any case, I think this is a style issue which ought to be
dealt with via stylesheets.
[Paul Moore]
>> Interesting. My immediate reaction was (probably the same as
>> David's :-)) "Use a directive". I'd suggest::
>>
>> .. right::
>> | "I have made this letter longer than
>> | usual, because I lack the time to make it
>> | short." ---Blaise Pascal
>>
>> where the "right" directive strips leading whitespace and "|"
>> characters.
Of course, if there's a directive the vertical bars wouldn't be
*needed*; redundant.
[Martin Blais]
> personally, that's exactly what i would try as much as possible to
> avoid, in fact, i would go as far as to give up on my desire to have
> right-alignment capability at all if it was provided this way
> because it introduces yet even more markup (more below)
That's too bad, because the construct is of marginal value and
probably doesn't warrant new syntax. It doesn't represent a new idea,
just a variation on an existing element, a "right-aligned block
quote". To justify the new syntax I'd want to see a lot more use
cases and user demand.
A directive may be more markup in the document, but it's less syntax
in the spec and less code in the parser. Generally, it's better to
exercise *existing* syntax -- the directive mechanism, in this case --
instead of adding *new* syntax. New syntax can be added later if the
demand warrants it.
>> The only problem is, I don't know what the directive should
>> *output*.
Perhaps ``<block_quote class="right">``; it seems appropriate.
>> It's the same old issue again, the docutils document tree
>> is fixed, and right-aligned blocks aren't a "known" construct.
Are they a "known" construct in the real world? Or just a stylistic
variation?
The docutils document tree is only fixed in that it can't be altered
dynamically at run-time. But we're always altering it, whenever new
constructs are incoporated.
>> You could hijack an existing element (cite seems the most
>> appropriate) but that seems like a kludge. We're back to the idea
>> of allowing arbitrary classes on elements,
We never left that idea. It already exists in Docutils; it's been
there for a long time. I don't consider it a kludge, but a mechanism
for flexibility.
>> Sigh. Maybe the doctree stuff is more flexible than I'm seeing (I'm
>> not an XML expert, and all the DTD stuff in the doctree spec
>> confuses me rather than helping :-() but it still seems to me like
>> the flexibility bottleneck in all this...
The DTD & doctree spec are simply the expression of what we *choose*
to allow or support in our documents. They do not limit us. If they
do, we alter them such that the limitations disappear.
> this may be a little bit off-subject: i feel that if by running
> "more" on the file our brains can interpret that this is
> right-aligned, there must be a way that we can find minimal
> unambiguous notation (i.e. in this case the pipes, not explicit
> markup) to make the parser add this information into the doctree.
You may be surprised by how easy it is for our brains to interpret
plaintext, and how difficult it is to get software to emulate this
interpretation.
> more generally: shouldn't we strive to provide structure for much of
> what can be expressed reasonably within a plain text file ...rather
> than the opposite?
In general, yes. I don't have a problem with the syntax per se. The
syntax -- particularly the bars-on-the-right variation -- seems
reasonable, and could be implemented in time. The problem I have is
two-fold: I don't think the functionality represented by the syntax is
a worthy addition to the reStructuredText; and even if it were, I
don't think it is worth the effort. (Have you seen the to-do list
lately? ;-) It would be a relatively simple task to add a "right"
directive, but a significant effort to add support for new specialized
syntax. *I* don't need it enough to do the work!
Patches are welcome, of course, and a patch would make it a lot easier
to accept a new feature. I can't guarantee that such a patch would be
applied though.
> i see two directions that features are discovered/desired:
>
> 1) constructs commonly expressed within a text file recognized by
> the parser and semantic added to it. in other words, we look at
> usual plain text files, and try to automatically extract as much
> meaning as possible from them. if some feature proves impossible to
> parse, we should offer the question: "how can we change the
> *notation* as little as possible to make it parseable and
> unambiguous, without jeopardizing parsing or other features?" (by
> the previous use of "notation", i do not include things like
> directives)
Directives are what I've called "explicit markup". Your use of
"notation" is what I've referred to as "implicit markup":
Simple, implicit markup is used to indicate special constructs,
such as section headings, bullet lists, and emphasis. The markup
used is as minimal and unobtrusive as possible. Less often-used
constructs and extensions to the basic reStructuredText syntax may
have more elaborate or explicit markup.
(From <http://docutils.sf.net/spec/rst/reStructuredText.html>)
I agree in principle with what you write. Have you read
<http://docutils.sf.net/spec/rst/introduction.html#goals>? If not,
please do [#]_. Here's goal #5:
5. Intuitive. Markup should be as obvious and easily remembered
as possible, for the author as well as for the reader.
Constructs should take their cues from such naturally occurring
sources as plaintext email messages, newsgroup postings, and
text documentation such as README.txt files.
.. [#] If you haven't, there's no point in continuing this discussion.
Please absorb the Docutils and reStructuredText specs; read through
the entire spec/ directory, every file. Take note of anything you
take exception to, but keep it to yourself until you've absorbed
and understood the entire spec. Anything you don't understand,
please ask about immediately; I'll try to answer and incorporate
those answers back into the docs, hopefully improving them.
> 2) a feature supported in the desired output format but is not
> obvious how to do in plain text is added with either special
> notation or markup;
By which you mean explicit markup, correct?
> IMHO i don't see any problem in adding all the possible reasonable
> features in (1) to the parser and the doctree,
What are the criteria for "reasonable"? Right now, I decide. Ideas
that come with a patch seem much more "reasonable" to me than those
without. ;-) "Adding all the possible reasonable features" sounds
like a lot of work.
> while (2) worries me a great deal, because that pushes towards
> adding markup (especially for features only available in certain
> output types), which goes against what i gather being the primary
> motivation for something like reST (i.e. convenience by minimizing
> markup (i personally read: removing markup)).
Goal #2:
2. Unobtrusive. The markup that is used should be as simple and
unobtrusive as possible. The simplicity of markup constructs
should be roughly proportional to their frequency of use. The
most common constructs, with natural and obvious markup, should
be the simplest and most unobtrusive. Less common constructs,
for which there is no natural or obvious markup, should be
distinctive.
Here, "distinctive" markup means explicit markup.
> However, if some output format support some rare construct not
> available in "general documents", we should become suspicious (sorry
> no good example comes to mind right now).
Suspicious of what? I'm not following you here.
> now to go back to the subject: i just wanted to say that i feel that
> the right-alignment as suggested above fits snuggly into (1). i can
> express it in plain text and everyone sees it for what it is in the
> source, thus it seems reasonable to me that the doctree would be
> able to reflect this meaning.
There is no intrinsic *meaning* though. It doesn't represent a
distinct document element. It's merely style, a variation in form.
> (another debate is whether reST should separate form vs. function,
I'd call it substance (structure, meaning) vs. style. As much as
possible, they should be separate.
> in which case some would argue that right-alignment is a matter of
> form and should not be in the source reST, but then again, that
> separation is one of the main motivations for markup languages... an
> interesting question is: on that scale, where does reST lie? the
> answer is not obvious to me, since i do care that my source reST
> files look good and simple, so form matters in the source too...)
It's a matter of balance. We choose where to put our limited effort.
ReStructuredText extracts structure from formalized style clues in
formatted text, but there's a limit to how much structure *can* be
extracted.
--
David Goodger http://starship.python.net/~goodger
Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
|
|
From: Aahz <aa...@py...> - 2003-05-08 14:28:39
|
On Thu, May 08, 2003, Moore, Paul wrote: > > The only problem is, I don't know what the directive should > *output*. It's the same old issue again, the docutils document tree > is fixed, and right-aligned blocks aren't a "known" construct. You > could hijack an existing element (cite seems the most appropriate) but > that seems like a kludge. We're back to the idea of allowing arbitrary > classes on elements, maybe <cite class="right"> in this case, or if > David wants to keep things controlled, a <div> equivalent. > > Sigh. Maybe the doctree stuff is more flexible than I'm seeing > (I'm not an XML expert, and all the DTD stuff in the doctree spec > confuses me rather than helping :-() but it still seems to me like the > flexibility bottleneck in all this... It's even more complicated than that. Those of us who write books for publishers often need to work with an existing style template, so we need mechanisms for generating that output. (For example, I am currently dealing with a situation where blocks often need one style for the first line, another style for the last line, and a third style for the lines between.) -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93 |
|
From: <eng...@ss...> - 2003-05-08 16:03:14
|
On Thu, 8 May 2003, Aahz wrote: > It's even more complicated than that. Those of us who write books for > publishers often need to work with an existing style template, so we > need mechanisms for generating that output. (For example, I am > currently dealing with a situation where blocks often need one style for > the first line, another style for the last line, and a third style for > the lines between.) how does one know what the last line is before typesetting ? -- BINGO: Einphasen --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6170 Zirl Innweg 5b / Tel. ++43-5238-93535 ---+ |
|
From: Aahz <aa...@py...> - 2003-05-08 16:44:07
|
On Thu, May 08, 2003, eng...@ss... wrote: > On Thu, 8 May 2003, Aahz wrote: >> >> It's even more complicated than that. Those of us who write books for >> publishers often need to work with an existing style template, so we >> need mechanisms for generating that output. (For example, I am >> currently dealing with a situation where blocks often need one style for >> the first line, another style for the last line, and a third style for >> the lines between.) > > how does one know what the last line is before typesetting ? They're lines of code (or sets of bullet points), so technically it's multiple paragraphs in a block. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93 |
|
From: David G. <go...@py...> - 2003-05-10 19:02:34
|
[William Dode]
> I found them in docbook :
>
> exergue = epigraph
> chapeau = highlights
> inter-titre = bridgehead
Thanks. It really helps to have common terminology to use, and a
standard to refer to.
It seems to me that epigraph/exergue and highlights/chapeau are
variations on block quotes. The implementation will use "class"
attributes to differentiate. I've added an "attribution" element to
block quotes, and I'll add a directive for it too.
[David Goodger]
>> I suspect the "class" directive may be able to handle these cases
>> easily.
>
> But a generic class attribute will not change a lot from doing a
> customized directive like i did (really easy).
The advantage of the "class" attribute/directive is that the *next*
time somebody needs a specialized construct, they won't need to write
a directive. Adding support may be as simple as editing the
stylesheet. Touching less code is better.
Implementing using a "class" directive::
ordinary text
.. class:: epigraph
Structured text is really a great idea for certain situations;
reST is a much better implementation of the idea than any
versions I've seen before.
.. attribution:: Guido van Rossum on Python-Dev, 2002-04-04
Implementing using an "epigraph" directive::
ordinary text
.. epigraph::
Structured text is really a great idea for certain situations;
reST is a much better implementation of the idea than any
versions I've seen before.
.. attribution:: Guido van Rossum on Python-Dev, 2002-04-04
Note the position of the initial directive. In the first example,
it's *inside* the block quote, while in the second, it *introduces*
it. The advantage of the dedicated directive is that the
"attribution" parsing could be built-in::
ordinary text
.. epigraph::
Structured text is really a great idea for certain situations;
reST is a much better implementation of the idea than any
versions I've seen before.
-- Guido van Rossum on Python-Dev, 2002-04-04
Perhaps the attribution parsing could become an integral part of block
quote parsing? (Iff the last paragraph begins with "--", it becomes
an attribution. Any issues?) This goes back to Paul Moore's initial
"Using blockquote element for quotes" post (2003-04-18).
[re: intertitre/bridgehead]
> I think it's more like a body element, just a different paragraph.
Yes, I think so too. I think it warrants a new doctree element
though. I don't like the name "bridgehead", because it has nothing
whatsoever to do with the dictionary definition (m-w.com):
1 a : a fortification protecting the end of a bridge nearest an
enemy b : an area around the end of a bridge
2 : an advanced position seized in hostile territory
But if we can't come up with a clearly superior term, we should use
"bridgehead" because of DocBook precedent. I can't find any
authoritative reference. The best I can find in `The Chicago Manual
of Style` is "subhead". Any ideas?
> epigraph and highlights are generaly in begin of a section but i
> don't see reason to don't let us use it everywhere.
OK
> like you will see in the code, exergue is generaly a
> FixedTextElement. <pre>
I don't see any reason to limit it this way. If it's useful enough,
an "epigraph" directive could grow a "line-block" option.
> please comment on my code, i really don't know if it's "the good
> way"...
They're fine, if all you want is single-paragraph contents. I think
epigraph/exergue and highlights/chapeau should be containers, based on
block_quote. The HTML Wrier code is fine too.
--
David Goodger http://starship.python.net/~goodger
Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
|
|
From: William D. <wi...@fl...> - 2003-05-08 09:17:38
|
"Moore, Paul" <Pau...@at...> writes: > From: Martin Blais [mailto:bl...@ir...] > > i was thinking of something with similar input recently: i wanted to have > > the quote's displayed aligned to the right. now i know how to do that with a > > CSS trick, but it wouldn't work in LaTeX for example. > > > > which got me thinking about... if it would be possible to find a way to > > recognize some text prefix within reST that would be "aligned" to the right, > > without a special directive... for example: > > > > | "I have made this letter longer than usual, > > | because I lack the time to make it short." > > | ---Blaise Pascal > > > > if i look at this within the text file, it appears to me as a blob of text > > that is aligned to the right. > > Interesting. My immediate reaction was (probably the same as David's :-)) "Use > a directive". I'd suggest:: > > .. right:: > | "I have made this letter longer than usual, > | because I lack the time to make it short." > | ---Blaise Pascal In french this is an "exergue"... I did a directive for this, but only for html writer. What is the policy to include new directives in the core ? With a book publisher we explore what we could need that are not in the core of docutils, and finaly there is only : exergue chapeau (litle text of introduction, not sub-title, longer) intertitre (text between two paragraph, but not sub-section, often used in newspaper) an example with chapeau (in bold) and intertitre (in red in the text): http://cequilfautdetruire.org/zero/airbus.html http://cequilfautdetruire.org/zero/__airbus.rst And after, really not often, esoteric class, that could be done with the futur class attribute. So, do you think theses directives could be put in the core ? -- William Dode - http://flibuste.net |
|
From: David G. <go...@py...> - 2003-05-09 15:13:44
|
William Dode wrote:
> What is the policy to include new directives in the core ?
If they're generally useful, properly written and documented, send
them in! I need to fully understand what they are and do though.
References to document standards help, such as The Chicago Manual of
Style or the Docbook DTD. There must be such standards for
journalists and/or for French-language documentation.
> With a book publisher we explore what we could need that are not in
> the core of docutils, and finaly there is only :
Thanks for the links to examples.
> exergue
> chapeau (litle text of introduction, not sub-title, longer)
How is "chapeau" different from "exergue"? Do you have an example
containing both?
I suspect the "class" directive may be able to handle these cases
easily. There was an issue that was delaying the implementation of
"class": what to apply it to? Enclosing element, or preceding, or
following? I recently had an idea that may resolve the issue:
Idea: if the "class" directive has no content, it applies to the
enclosing element; useful for structural elements & containers
(sections, block quotes, etc.). With content, it applies to the
content; useful for body elements (paragraphs, lists, etc.).
(From <http://docutils.sf.net/spec/notes.html#misc-class>)
> intertitre (text between two paragraph, but not sub-section, often
> used in newspaper)
This seems to correspond to the DocBook `bridgehead element
<http://www.docbook.org/tdg/en/html/bridgehead-x.html>`_. I don't see
a problem adding a "bridge" or "bridgehead" element to the Docutils
doctree. The only question is, is it a structural element (like a
section or transition) or is it a body element (like a paragraph)? If
a body element, it could occur anywhere, including inside block quotes
and table cells. If a structural element, it can only occur at the
top level of sections.
> So, do you think theses directives could be put in the core ?
Send me the code and examples and I'll take a look.
--
David Goodger http://starship.python.net/~goodger
Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
|
|
From: William D. <wi...@fl...> - 2003-05-10 07:49:01
|
David Goodger <go...@py...> writes: > William Dode wrote: > > What is the policy to include new directives in the core ? > > If they're generally useful, properly written and documented, send > them in! I need to fully understand what they are and do though. > References to document standards help, such as The Chicago Manual of > Style or the Docbook DTD. There must be such standards for > journalists and/or for French-language documentation. I found them in docbook : exergue = epigraph chapeau = highlights inter-titre = bridgehead > > > With a book publisher we explore what we could need that are not in > > the core of docutils, and finaly there is only : > > Thanks for the links to examples. > > > exergue > > chapeau (litle text of introduction, not sub-title, longer) > > How is "chapeau" different from "exergue"? Do you have an example > containing both? exergue is like "to my mother" or something like that chapeau is a bigger text of introduction > > I suspect the "class" directive may be able to handle these cases > easily. There was an issue that was delaying the implementation of > "class": what to apply it to? Enclosing element, or preceding, or > following? I recently had an idea that may resolve the issue: > > Idea: if the "class" directive has no content, it applies to the > enclosing element; useful for structural elements & containers > (sections, block quotes, etc.). With content, it applies to the > content; useful for body elements (paragraphs, lists, etc.). > > (From <http://docutils.sf.net/spec/notes.html#misc-class>) But a generic class attribute will not change a lot from doing a customized directive like i did (really easy). In the opposite, class attribute will help to do differents rendering of epigraph... > > > intertitre (text between two paragraph, but not sub-section, often > > used in newspaper) > > This seems to correspond to the DocBook `bridgehead element > <http://www.docbook.org/tdg/en/html/bridgehead-x.html>`_. I don't see > a problem adding a "bridge" or "bridgehead" element to the Docutils > doctree. The only question is, is it a structural element (like a > section or transition) or is it a body element (like a paragraph)? If > a body element, it could occur anywhere, including inside block quotes > and table cells. If a structural element, it can only occur at the > top level of sections. I think it's more like a body element, just a different paragraph. epigraph and highlights are generaly in begin of a section but i don't see reason to don't let us use it everywhere. like you will see in the code, exergue is generaly a FixedTextElement. <pre> > > > So, do you think theses directives could be put in the core ? > > Send me the code and examples and I'll take a look. please comment on my code, i really don't know if it's "the good way"... # # # CUSTOMIZED DIRECTIVES # # from docutils import nodes class exergue_node(nodes.General, nodes.FixedTextElement): pass class intertitre_node(nodes.General, nodes.TextElement): pass class chapeau_node(nodes.General, nodes.TextElement): pass def exergue(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): if not content: warning = state_machine.reporter.warning( 'Content block expected for the "%s" directive; none found.' % name, nodes.literal_block(block_text, block_text), line=lineno) return [warning] text = '\n'.join(content) text_nodes, messages = state.inline_text(text, lineno) node = exergue_node(text, '', *text_nodes) return [node] + messages exergue.content = 1 def chapeau(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): if not content: warning = state_machine.reporter.warning( 'Content block expected for the "%s" directive; none found.' % name, nodes.literal_block(block_text, block_text), line=lineno) return [warning] text = '\n'.join(content) text_nodes, messages = state.inline_text(text, lineno) node = chapeau_node(text, '', *text_nodes) return [node] + messages chapeau.content = 1 def intertitre(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): if not content: warning = state_machine.reporter.warning( 'Content block expected for the "%s" directive; none found.' % name, nodes.literal_block(block_text, block_text), line=lineno) return [warning] text = '\n'.join(content) text_nodes, messages = state.inline_text(text, lineno) node = intertitre_node(text, '', *text_nodes) return [node] + messages intertitre.content = 1 # # # CUSTOMIZED HTML WRITER (INLINE) # # import sys import os import time import re from types import ListType import docutils from docutils import nodes, utils, writers, languages from docutils.writers import html4css1 class Writer(html4css1.Writer): supported = ('html_wilk') """Formats this writer supports.""" def __init__(self): writers.Writer.__init__(self) self.translator_class = HTMLTranslator class HTMLTranslator(html4css1.HTMLTranslator): def astext(self): return ''.join(self.body) return ''.join( self.body_pre_docinfo + self.docinfo + self.body + self.body_suffix) def visit_exergue_node(self,node): self.body.append(self.starttag(node, 'pre', CLASS="exergue")) def depart_exergue_node(self,node): self.body.append('</pre>\n') def visit_chapeau_node(self,node): self.body.append(self.starttag(node, 'p', CLASS="chapeau")) def depart_chapeau_node(self,node): self.body.append('</p>\n') def visit_intertitre_node(self,node): self.body.append(self.starttag(node, 'p', CLASS="intertitre")) def depart_intertitre_node(self,node): self.body.append('</p>\n') -- William Dode - http://flibuste.net |
|
From: Magnus <ma...@th...> - 2003-05-11 19:03:01
|
D. G. wrote: > > But if we can't come up with a clearly superior term, we should use > > "bridgehead" because of DocBook precedent. I can't find any > > authoritative reference. The best I can find in `The Chicago Manual > > of Style` is "subhead". Any ideas? At 19:57 2003-05-11 +0200, William Dode wrote: >inter-title ? But "title" is typically used only for the document title in the terminology we use, right? In Swedish, this thing is usually called "mellanrubrik", which you could translate to "between-heading", which is not quite the same as "underrubrik" (sub heading). The thing is that it's typically not a heading for a sub-section of a document, but rather something you insert at more or less regular intervals in a journalistic text to break it into more digestable pieces. It doesn't really imply structure in the way sections in a technical or legal document usually does. You wouldn't use it in a table of contents for instance. It's a little heading between paragraphs, and the way I was taught to write articles and press realeases etc, I should extract the most important things in the article, perhaps pure quotes of the text, and place them as "mellanrubrik" at some fitting pause a few sentences before the place where they occur in the text. These things can be seen as some kind of appetizers. Things that catch the eye of a reader, and make them want to read, rather than a section heading, which is intended to make the reader know *where* to read. For me, bridgehead only has a military meaning, so it doesn't ring any bell for me in this situation, but lacking anything else, I could buy that. I like "mellanrubrik", but I guess it's even more problematic with Swedish terms than with Latin ones. ;) Or will this be our next export after Ombudsman and Smorgasbord? :) -- Magnus Lycka (It's really Lyckå), ma...@th... Thinkware AB, Sweden, www.thinkware.se I code Python ~ The shortest path from thought to working program |
|
From: David G. <go...@py...> - 2003-05-11 22:29:18
|
[David Goodger]
>>> But if we can't come up with a clearly superior term, we should
>>> use "bridgehead" because of DocBook precedent. I can't find any
>>> authoritative reference. The best I can find in `The Chicago
>>> Manual of Style` is "subhead". Any ideas?
[Magnus Lyckå]
> But "title" is typically used only for the document title
> in the terminology we use, right?
Well, each section has a title too.
> In Swedish, this thing is usually called "mellanrubrik",
You've written a perfect description of this thing. I'm glad you
answered! And the name "mellanrubrik" brought to mind the English
word "rubric". Looking it up in the dictionary, we have:
rubric n. 1. a title, heading, or the like, in a manuscript, book,
statute, etc., written or printed in red or otherwise
distinguished from the rest of the text. ...
-- Random House Webster's College Dictionary, 1991
They must have the same root: the Latin "rubrica" ("red ochre"), a
pigment that was probably used in manuscript ink.
"Rubric" seems like the perfect term. A quick web search reveals that
almost all current usage of the term is of another definition: "an
established rule, tradition, or custom". Unfortunate, but not
critical.
--
David Goodger http://starship.python.net/~goodger
Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
|
|
From: Magnus <ma...@th...> - 2003-05-11 23:16:21
|
At 18:28 2003-05-11 -0400, David Goodger wrote: >>But "title" is typically used only for the document title >>in the terminology we use, right? > >Well, each section has a title too. Ok. As I look at the "quickstart" it seems you use both section header and section title. actually I thought you had called it heading as in HTML. >You've written a perfect description of this thing. I'm glad you >answered! And the name "mellanrubrik" brought to mind the English >word "rubric". Looking it up in the dictionary, we have: Great. It will at least be fairly clear to Swedes. :) -- Magnus Lycka (It's really Lyckå), ma...@th... Thinkware AB, Sweden, www.thinkware.se I code Python ~ The shortest path from thought to working program |
|
From: David G. <go...@py...> - 2003-05-12 01:42:16
|
Magnus Lyckå wrote: > Ok. As I look at the "quickstart" it seems you use both > section header and section title. actually I thought you > had called it heading as in HTML. Richard Jones wrote that, with terminology a bit different from mine. The difference is not significant though; they're synonyms. -- David Goodger |
|
From: Aahz <aa...@py...> - 2003-05-12 02:57:54
|
On Sun, May 11, 2003, Magnus Lyck=E5 wrote: > > In Swedish, this thing is usually called "mellanrubrik", which > you could translate to "between-heading", which is not quite the > same as "underrubrik" (sub heading). >=20 > The thing is that it's typically not a heading for a sub-section > of a document, but rather something you insert at more or less > regular intervals in a journalistic text to break it into more > digestable pieces. It doesn't really imply structure in the way > sections in a technical or legal document usually does. You wouldn't > use it in a table of contents for instance. >=20 > It's a little heading between paragraphs, and the way I was taught > to write articles and press realeases etc, I should extract the > most important things in the article, perhaps pure quotes of the > text, and place them as "mellanrubrik" at some fitting pause a > few sentences before the place where they occur in the text. My take is that in American publishing usage, this would be a "callout" or "sidebar" (depending on whether it were interstitial or on the side). --=20 Aahz (aa...@py...) <*> http://www.pythoncraft.= com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93 |
|
From: William D. <wi...@fl...> - 2003-05-11 17:58:05
|
David Goodger <go...@py...> writes: > [William Dode] > > I found them in docbook : > > > > exergue = epigraph > > chapeau = highlights > > inter-titre = bridgehead > > Thanks. It really helps to have common terminology to use, and a > standard to refer to. > > It seems to me that epigraph/exergue and highlights/chapeau are > variations on block quotes. The implementation will use "class" > attributes to differentiate. I've added an "attribution" element to > block quotes, and I'll add a directive for it too. > > [David Goodger] > >> I suspect the "class" directive may be able to handle these cases > >> easily. > > > > But a generic class attribute will not change a lot from doing a > > customized directive like i did (really easy). > > The advantage of the "class" attribute/directive is that the *next* > time somebody needs a specialized construct, they won't need to write > a directive. Adding support may be as simple as editing the > stylesheet. Touching less code is better. > > Implementing using a "class" directive:: > > ordinary text > > .. class:: epigraph > > Structured text is really a great idea for certain situations; > reST is a much better implementation of the idea than any > versions I've seen before. > > .. attribution:: Guido van Rossum on Python-Dev, 2002-04-04 > > Implementing using an "epigraph" directive:: > > ordinary text > > .. epigraph:: > > Structured text is really a great idea for certain situations; > reST is a much better implementation of the idea than any > versions I've seen before. > > .. attribution:: Guido van Rossum on Python-Dev, 2002-04-04 > > Note the position of the initial directive. In the first example, > it's *inside* the block quote, while in the second, it *introduces* > it. The advantage of the dedicated directive is that the > "attribution" parsing could be built-in:: > > ordinary text > > .. epigraph:: > > Structured text is really a great idea for certain situations; > reST is a much better implementation of the idea than any > versions I've seen before. > > -- Guido van Rossum on Python-Dev, 2002-04-04 This last example is really beautiful and simple. I vote for this one ;-) I'm not sure to understand the first example... With a class directive, it will be not sure that all the writers implement it. I thought that the class directive will be for exceptional case... > > Perhaps the attribution parsing could become an integral part of block > quote parsing? (Iff the last paragraph begins with "--", it becomes > an attribution. Any issues?) This goes back to Paul Moore's initial > "Using blockquote element for quotes" post (2003-04-18). why not... > > [re: intertitre/bridgehead] > > I think it's more like a body element, just a different paragraph. > > Yes, I think so too. I think it warrants a new doctree element > though. I don't like the name "bridgehead", because it has nothing > whatsoever to do with the dictionary definition (m-w.com): > > 1 a : a fortification protecting the end of a bridge nearest an > enemy b : an area around the end of a bridge > 2 : an advanced position seized in hostile territory > > But if we can't come up with a clearly superior term, we should use > "bridgehead" because of DocBook precedent. I can't find any > authoritative reference. The best I can find in `The Chicago Manual > of Style` is "subhead". Any ideas? inter-title ? > > > epigraph and highlights are generaly in begin of a section but i > > don't see reason to don't let us use it everywhere. > > OK > > > like you will see in the code, exergue is generaly a > > FixedTextElement. <pre> > > I don't see any reason to limit it this way. If it's useful enough, > an "epigraph" directive could grow a "line-block" option. sure > > > please comment on my code, i really don't know if it's "the good > > way"... > > They're fine, if all you want is single-paragraph contents. I think > epigraph/exergue and highlights/chapeau should be containers, based on > block_quote. The HTML Wrier code is fine too. sure, but i must learn how to do containers... -- William Dode - http://flibuste.net |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X