why docutils should reject Alan's proposal
Paul Tremblay <paulhtremblay <at> gmail.com>
2011-11-11 23:28:00 GMT
Docutils mailing list:
David Goodger has suggested that the two major reasons why
reStrucuredText is not used for scientific documentation is that it
cannot mange bibliographic references and it cannot include math.
Recently, there have been some good steps forward in implementing math
support (through converting LaTeX to MathML, for example).
There have been no steps forward to handle bibliographic management.
Alan Isaac has put forward some type of proposal, but I suggest docutils
reject this proposal.
In order for a proposal to be adopted, it must meet 2 criteria:
(1) It must thoroughly explore the problem. The proposal must not only
consider the actual reStructuredText syntax, but the needs of a
different users. For example, the developers have considered the problem
with tables and have realized that many users needed CSV tables, and
then implemented this feature. Thought was given to the needs of users
and the different scenarios.
(2) A proposal must include examples of reStructuredText syntax and
examples of how that syntax should be rendered in a tree. For example,
the reSructuredText pattern
Title
===
Gets rendered in the docutils tree as
<section>
<title>Title</title>
Imagine if docutils did not have the heading element, and someone
proposed that there should be a title just like in MS Word. What exactly
does that mean? Does the user want to create a section, for example?
Alan's proposal fails to meet either criteria.
(1) First, he has not thoroughly considered the problem at hand.
Bibliographic references can be quite complex. Consider:
As Bergonzi notes (*Anatomy of Rome*, p33)
As Bergonzi notes (*Anatomy of Rome*, p33-66)
As Bergonzi notes (*Anatomy of Rome*, p33, p66)
As Begonzi notes (*Anatomy of Rome*, p33-66, Vol1, p45, Vol 2)
As Bergonzi and Jensen note (*Anatomy of Rome*, p33-66, Vol1, p45;
*History of Italy*, p33)
And so fourth. I have done some work in the past on just this issue,
painstakingly going through style manuals gleaning examples. That is how
I know about the complexity of the issue.
Alan's proposal has not considered any of these issues. Instead of
presenting the full problem and then showing how his proposal would
handle them, he has merely given one or two examples, and then in a very
vague way. He has not presented proposed syntax for these examples.
Instead, he has presented rambling discourse on the need to accept his
proposal, and how it works in bibtex. Such a proposal neither addresses
the specific problem nor gives a solution. A serious proposal includes
specific syntax for all the potential situations. Alan either seems
unaware of the complexity of the problem, or does not care to address it.
(2) Alan proposes no idea of how the docutils tree should render his
proposal. As it stands now, the following syntax:
a refernece [foo]_
.. [foo] reference
Gets rendered as
<paragraph>a refernece <citation_reference ids="id1"
refid="foo">foo</citation_reference>
</paragraph>
<citation backrefs="id1" ids="foo" names="foo">
<label>foo</label>
<paragraph>reference</paragraph>
</citation>
No spaces are allowed, and brackets are not allowed. The text inside the
brackets gets assigned an ID, which should match a the backrefs
attribute in the citation element.
Alan suggests:
[mycite{mytext}]_
From here, he does not suggest how he wants the new tree to look.
Presumably, he wants the text "mycite" to link to the full citation, and
the string "mytext" to somehow be extra. But from here, his proposal is
too vague to be taken seriously. Does he want the "mytext" dumped as a
string in its own element? If so, then how about when there are multiple
references? For example:
As Bergonzi and Jensen note [Anatomy{p33-66Vol1,p45;Vol2p33-44}]_
Becomes:
<citation backrefs="id1" ids="Anatomy"
names="Anatomy"><other>p33-66Vol1,p45;Vol2p33-44</other></citation>
But what use is that? The other element now contains a string of text
that is almost useless to an external writer or parser. Perhaps he wants:
As Bergonzi and Jensen note [Anatomy{p33-66}{Vol1}{p45}{Vol2}{p33-44}]_
.. [Anatomy] *Anatomy of Rome*, etc
to become:
<citation backrefs="id1" ids="Anatomy" names="Anatomy">
<p>33-66</p>
<vol>1</vol>
<p>45</p>
<vol>2</vol>
<p>33-44</p>
</citation>
It is hard to say, because Alan's proposal does not contain any
specifics. He keeps insisting that it is not important how the rest of
the text that is not the ID gets handled, but that seems unworkable,
namely because his solution does not put fourth a solution to
bibliographic management. It basically requires a partial solution that
does not further the goals of reStructredText. Developers would have to
develop code only to have to go back later and develop more code, or
switch the code they have.
Alan seems unaware that a reStructuredText document gets rendered to a
tree before it gets rendered to a LaTeX document, and hence his proposal
remains too vague to be workable.
I suggest that Alan do 3 things in order for his proposal to go forward:
1. Use specific language when talking about this problem so that we are
not talking past each other
2. Provide the syntax for complex citation references, not just simple
references that have one page.
3. Provide specifics on how he wants these citations parsed, preferably
in a tree, or, if he does not feel comfortable with that, something
equivalent.
I don't think implementing poorly thought-out proposals further
reStructuredText
Paul
------------------------------------------------------------------------------
RSA(R) Conference 2012
Save $700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1
As I wrote already the 
RSS Feed