From: Yannick C. <yan...@la...> - 2006-01-23 22:14:08
|
Hi, as I'm trying to extend my use of reStructuredText (how convenient!), I face some difficulties related to the limited definition of reference names (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names). 1. The ADS bibliographic code (e.g. 1970ApJ...159..165H in http://cdsads.u-strasbg.fr/cgi-bin/nph-bib_query?bibcode=1970ApJ...159..165H) is very useful as a cite-key. Still, it cannot be used directly in a citation [1970ApJ...159..165H]_ because of the presence of multiple '.' I assume (it does not issue any WARNING or INFO though, but just does nothing). Of course, I could use the hyperlink target `1970ApJ...159..165H`_, but this is no more a citation. 2. I'm using reST to automatically generate tables of stars, some of them having a '+' in their (otherwise reST-compliant) name (e.g. BD+75325). This prevent me from making a simple link with BD+75325_, and I have to use the slightly less (machine) readable `BD+75325`_ format. So, my question: is there any strong reason for not allowing non-isolated periods and '+'-sign in reference names? I'm using rst2html.py (Docutils 0.5 [snapshot 2006-01-10, r4283]). Cheers. |
From: David G. <go...@py...> - 2006-06-30 13:23:41
Attachments:
signature.asc
|
I'm trying to get through my backlog of email; sorry for the long delay! [Yannick Copin] > as I'm trying to extend my use of reStructuredText (how > convenient!), I face some difficulties related to the limited > definition of reference names > (http://docutils.sf.net/docs/ref/rst/restructuredtext.html#reference-na= mes). > > 1. The ADS bibliographic code (e.g. 1970ApJ...159..165H in > http://cdsads.u-strasbg.fr/cgi-bin/nph-bib_query?bibcode=3D1970ApJ...15= 9..165H) > is very useful as a cite-key. Still, it cannot be used directly in a > citation [1970ApJ...159..165H]_ because of the presence of multiple > '.' I assume (it does not issue any WARNING or INFO though, but just > does nothing). Of course, I could use the hyperlink target > `1970ApJ...159..165H`_, but this is no more a citation. I just proposed an extension to the citation syntax to allow for phrase references (see the "citation enhancement?" thread). Once implemented, your example would be possible as: [`1970ApJ...159..165H`]_ > 2. I'm using reST to automatically generate tables of stars, some of > them having a '+' in their (otherwise reST-compliant) name > (e.g. BD+75325). This prevent me from making a simple link with > BD+75325_, and I have to use the slightly less (machine) readable > `BD+75325`_ format. > > So, my question: is there any strong reason for not allowing > non-isolated periods and '+'-sign in reference names? In general, reference name syntax is kept simple to prevent accidental markup recognition. Plus sign: I suppose "+" could be added to simple reference name syntax. The only objection I can think of is in uses like "pi+e_" where "e" is a reference but "pi+e" isn't. But since hyphens, which double as minus signs, *are* allowed, that isn't much of an objection. Question for all: Any objections to adding "+" to simple reference name syntax? Note that I don't want to add any other punctuation characters to the simple reference name syntax (commas, colons, equals signs, quotes, parentheses, etc.), because the danger of misinterpreting input would grow too high. Backquotes suffice to allow arbitrary reference text. Multiple periods (multiple punctuation in general): I think this would go too far. Two periods in a row might be acceptable, but three make up an ellipsis, which separates words. I would expect this to work as three separate references: reference_...not a reference...another_...`yet another`_... If we allowed multiple periods in simple reference names, the example above would be misinterpreted ("reference...another" mistaken for one name). And I would be loathe to require backslash escapes in this case. We could allow this form in citation reference context only: [1970ApJ...159..165H]_ But that would complicate the syntax model, both algorithmically and mentally. So I don't think so. The phrase reference syntax should suffice: [`1970ApJ...159..165H`]_ --=20 David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2006-08-17 10:07:04
|
David Goodger wrote on 30 Jun 2006: > Question for all: Any objections to adding "+" to simple reference > name syntax? I don't think the benefit is large enough to justify the document breakage. I recall doing something like foo+bar_ before and finding the default behavior (making "bar", but not "foo" a link) convenient. > We could allow this form in citation reference context only: > > [1970ApJ...159..165H]_ > > But that would complicate the syntax model, both algorithmically and > mentally. Well, allowing more characters (everything except whitespac?) in citation references wouldn't cause as much breakage, I assume, because [foo+bar]_ (which is currently interpreted as normal text) probably occurs quite seldom in real documents. > So I don't think so. The phrase reference syntax should suffice: > > [`1970ApJ...159..165H`]_ That's not easy to implement either, is it? Best, Felix -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: Alan G I. <ai...@am...> - 2006-08-17 13:27:07
|
> David Goodger wrote on 30 Jun 2006: >> Question for all: Any objections to adding "+" to simple reference >> name syntax? On Thu, 17 Aug 2006, Felix Wiemann apparently wrote: > I don't think the benefit is large enough to justify the > document breakage. I recall doing something like foo+bar_ > before and finding the default behavior (making "bar", but > not "foo" a link) convenient. The context of David's question makes it clear he has citation references in mind, and I hope that Felix does too, because '+' is a common character in citation keys. See e.g.: http://en.wikipedia.org/wiki/BibTeX In this sense, the potential benefit is *very* large for all those who would like to use their existing BibTeX databases in combination with their reST documents. On Thu, 17 Aug 2006, David Goodger apparently wrote: > We already have "foo-bar" as a valid reference name, so > "foo+bar" and perhaps even "foo:bar" seem reasonable. Yes please! Both are extremely common in bibliographic database cite keys! (Example of the latter: http://www.ddm.org/Bibtex/showdatabase.cgi ) Alan Isaac PS I have rewritten and enhanced Dylan Schwilk's addrefs.py script to produce nicely formatted (based on user chosen styles!) reST citation definitions, with labels. Citation references are culled from the reST document, and citation definition information is drawn from any BibTeX database. (The new script, bib4txt.py, will be posted with the other BibStuff materials on Dylan's site very soon, but I can email a copy to anyone in a real hurry to try it.) |
From: David G. <go...@py...> - 2006-08-17 13:15:09
Attachments:
signature.asc
|
> David Goodger wrote on 30 Jun 2006: >> Question for all: Any objections to adding "+" to simple reference >> name syntax? [Felix Wiemann] > I don't think the benefit is large enough to justify the document > breakage. I recall doing something like foo+bar_ before and finding th= e > default behavior (making "bar", but not "foo" a link) convenient. This might cause some minor breakage, but the argument seems weak to me. = Can you point to any real-world examples (i.e., not invented for this case)? = I can't think of any case where the answer isn't "there should be spaces ar= ound the '+' then". We already have "foo-bar" as a valid reference name, so "foo+bar" and perhaps even "foo:bar" seem reasonable. >> We could allow this form in citation reference context only: >> >> [1970ApJ...159..165H]_ >> >> But that would complicate the syntax model, both algorithmically and >> mentally. >=20 > Well, allowing more characters (everything except whitespac?) in > citation references wouldn't cause as much breakage, I assume, because > [foo+bar]_ (which is currently interpreted as normal text) probably > occurs quite seldom in real documents. We'd have to be very careful; we couldn't allow "]" either, and probably = others as well. But I don't want to make exceptions. Same argument as for ".." and "..."= above: the syntax model (and docs) would become more complicated. So either "foo+bar" becomes a legal reference name (usable in all context= s), or we require phrase reference syntax in citation refs. >> The phrase reference syntax should suffice: >> >> [`1970ApJ...159..165H`]_ >=20 > That's not easy to implement either, is it? I don't know yet. It shouldn't be too difficult; it'd just be a matter o= f adapting code that already exists. But the implementation difficulty doe= sn't matter, since it's the right thing to do. --=20 David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2006-08-17 13:37:14
|
David Goodger wrote: > Felix Wiemann wrote: > >> David Goodger wrote: >> >>> Question for all: Any objections to adding "+" to simple reference >>> name syntax? >> >> I don't think the benefit is large enough to justify the document >> breakage. I recall doing something like foo+bar_ before and finding the >> default behavior (making "bar", but not "foo" a link) convenient. > > This might cause some minor breakage, but the argument seems weak to > me. Can you point to any real-world examples (i.e., not invented for > this case)? I don't have any real-world example at hand, but IIRC the foo+bar_ example above actually occured in a document I wrote. > So either "foo+bar" becomes a legal reference name (usable in all contexts), or > we require phrase reference syntax in citation refs. Well, I don't like foo+bar to be a simple reference, and it doesn't solve other cases like "..". So supporting phrase reference syntax in citation refs might be the best thing indeed. Felix -- Felix Wiemann -- http://www.ososo.de/ |