Menu
▾
▴
Re: [Docutils-users] Using blockquote element for quotes
|
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
|
