From: Alan G I. <ai...@am...> - 2006-07-12 19:07:12
|
On Mon, 3 Jul 2006, Phil Schumm apparently wrote: > I believe we may have the same interest here; namely, > figuring out good ways to work with reST files containing > citations to many references, especially references that > we may already have stored in a BibTeX file. Yes. I consider the database format (e.g., .bib) inconsequential to the general discussion, but in fact I use it and it is simple, powerful, in widespread use, and already supported by Bibstuff. The core question is: what features will reStructuredText provide to allow non-LaTeX formats to have something approaching serious citation handling. I proposed a mechanism that will allow convenient interaction with preprocessors: enhancing the citation machinery to allow the citation to specify replacement text that reST writers will substitute for the citation label. (I have explained how this would work in previous posts. For example, Bibstuff can already be used to generate citations from a database from a list of citation references that it culls from an reST document, and it can be modified slightly to produce at the same time a formatted citation-reference-substitution, if David agrees to implement such substitution.) I understood David to say this is feasible. I also understood him to express reluctance to implement it, based on a rather abstract consideration that substituion already exists (although not in a fashion that is useful for this purpose!). So more people than just me will need to indicate that this enhancement will be useful to them. Cheers, Alan Isaac |
From: David G. <go...@py...> - 2006-07-13 00:07:26
Attachments:
signature.asc
|
[Alan G Isaac] > I proposed a mechanism that will allow convenient > interaction with preprocessors: A preprocessor could handle everything, with no change to reST. > (I have explained how this would work in previous posts. For future reference, an argument strung across multiple posts and evolving over several weeks is hard to follow. Judicious reiteration of the main points, and especially the examples, is helpful. > I understood David to say this is feasible. I actually said "theoretically possible, but unnecessarily complex & not worth the effort". On further reflection, I see that in addition to my earlier misgivings, the proposal is also backwards-incompatible. You proposed: .. [Goodger2006] inline:: (Goodger 2006) Above is the inline-substitution text, while here is the actual citation. This would break all current citations, which don't have a directive part. Allowing variant syntax (i.e. checking for an optional directive part) is out of the question. An alternative could be to implement a new directive for citations, something like this:: .. citation:: Goodger2006 :substitute: (Goodger 2006) This is the citation text. The ":substitute:" option above supplies the display citation label. Directive options allow for more flexible constructs than are otherwise possible, at the expense of some verbosity. But the biggest objection I have with the proposed mechanism (regardless of the syntax) is that there would be no explicit indication of the substitution *at the substitution site*. IOW there would be no way to tell from the citation reference -- without looking at the citation definition itself -- that the citation label would be changed. That's without precedent in reST and violates the "unsurprising" goal (http://docutils.sf.net/docs/ref/rst/introduction.html#goals). > I also understood him to express reluctance to implement it, > based on a rather abstract consideration that substituion > already exists (although not in a fashion that is useful for > this purpose!). I realize you're frustrated, but this type of invective is counterproductive. > So more people than just me will need to > indicate that this enhancement will be useful to them. No matter how many people indicate usefulness, some proposals are unacceptable and will be rejected. I believe this proposal to be one of these. Please consider this a pronouncement, and give it a rest. --=20 David Goodger <http://python.net/~goodger> |
From: Stuart R. <st...@za...> - 2006-07-13 00:41:18
|
Hi, David. > But the biggest objection I have with the proposed mechanism > (regardless of the syntax) is that there would be no explicit > indication of the substitution *at the substitution site*. IOW there > would be no way to tell from the citation reference -- without looking > at the citation definition itself -- that the citation label would be > changed. That's without precedent in reST and violates the > "unsurprising" goal > (http://docutils.sf.net/docs/ref/rst/introduction.html#goals). Perhaps I have misunderstood something, but isn't the "unsurprising goal" already violated by 'substition text' directives? http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions -Stuart |
From: David G. <go...@py...> - 2006-07-13 01:11:26
Attachments:
signature.asc
|
[Stuart Robinson] > Perhaps I have misunderstood something, but isn't the "unsurprising > goal" already violated by 'substition text' directives? >=20 > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#subs= titution-definitions No, because there's an explicit indication of the substitution: A substitution will happen |here|. The substitution reference syntax is a clear indication that something's = up. But: One [citation]_ and [another]_. Which citation will be substituted? Neither? Both? There's no way to tell. --=20 David Goodger <http://python.net/~goodger> |
From: G. M. <g....@we...> - 2006-07-13 07:07:50
|
On 12.07.06, David Goodger wrote: > [Alan G Isaac] > > I proposed a mechanism that will allow convenient > > interaction with preprocessors: > > A preprocessor could handle everything, with no change to reST. However, a small change to reST could facilitate a far simpler preprocessor and "nice", easy to understand preprocessed restructured text. > > So more people than just me will need to > > indicate that this enhancement will be useful to them. > > No matter how many people indicate usefulness, some proposals are > unacceptable and will be rejected. I believe this proposal to be one > of these. Please consider this a pronouncement, and give it a rest. Could we separate "enhanced citation support" from the implementation proposal? * I believe reST could gain a lot from supporting citations from a database. (Actually, this is one of the main points where LaTeX (and LyX) are still far superior to common office software.) * I agree that a backwards compatible, clean implementation that fits well in the existing syntax, should be found. > An alternative could be to implement a new directive for citations, > something like this:: > > .. citation:: Goodger2006 > :substitute: (Goodger 2006) > > This is the citation text. The ":substitute:" option above > supplies the display citation label. Directive options allow > for more flexible constructs than are otherwise possible, at > the expense of some verbosity. This looks nice to me. > But the biggest objection I have with the proposed mechanism > (regardless of the syntax) is that there would be no explicit > indication of the substitution *at the substitution site*. On 12.07.06, David Goodger wrote: > [Stuart Robinson] > > Perhaps I have misunderstood something, but isn't the "unsurprising > > goal" already violated by 'substition text' directives? > > > > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions > > No, because there's an explicit indication of the substitution: > > A substitution will happen |here|. > > The substitution reference syntax is a clear indication that something's up. > But: > > One [citation]_ and [another]_. > > Which citation will be substituted? Neither? Both? > There's no way to tell. Citations will always be substituted. (Sometimes the label and the substitution might conincide). This enables different common citation styles with a consistent syntax. (e.g. in my publications I almost entirely need the sorted numbered style: .. citation:: Goodger2006 :substitute: [1] ``On citations in reStructured text``, email correspondence at doc...@li..., June 2006 .. citation:: Isaac2006 :substitute: [2] ``A proposal for citations in reStructured text``, email correspondence at doc...@li..., June 2006 However, during the editing of the text I would like to keep the name-author labels so a new citation will not change all following labels in the text. Günter |
From: David G. <go...@py...> - 2006-07-13 13:49:54
Attachments:
signature.asc
|
[David Goodger] >> A preprocessor could handle everything, with no change to reST. [G. Milde] > However, a small change to reST could facilitate a far simpler > preprocessor and "nice", easy to understand preprocessed restructured > text. I have yet to be convinced why a change would be necessary and worthwhile= =2E I'd like to see a comprehensive proposal. Somebody should assemble all the arguments and evidence in one place; what we have now is scattered. It s= hould show the entire process from start to finish, what every part does, and s= hould address all output formats, not just LaTeX. > Could we separate "enhanced citation support" from the implementation > proposal?=20 Of course, please do. But any proposal for "enhanced citation support" w= ill require a good implementation proposal. > * I believe reST could gain a lot from supporting citations from a > database. (Actually, this is one of the main points where LaTeX (and > LyX) are still far superior to common office software.) I'm not averse to making changes to allow such support, but I believe Docutils/reST is the wrong place for the heavy lifting. There are dedica= ted citation database tools that do their job well. Far better to use one th= an to reimplement the functionality in Docutils. >> But the biggest objection I have with the proposed mechanism >> (regardless of the syntax) is that there would be no explicit >> indication of the substitution *at the substitution site*. =2E.. > Citations will always be substituted. > (Sometimes the label and the substitution might conincide).=20 So, display citation labels always substituted, with the default being th= e citation label actually used? That could work. It still makes me feel u= neasy though. It would be duplicating functionality, and that needs a very str= ong case. But I still don't see *why this is needed*. I've seen weak arguments, bu= t nothing persuasive. And I'm getting tired of this subject. > This enables different common citation styles with a consistent syntax.= > (e.g. in my publications I almost entirely need the sorted numbered > style: Why don't you use footnotes then? > However, during the editing of the text I would like to keep the > name-author labels so a new citation will not change all following > labels in the text. Use footnotes with autonumber labels: http://docutils.sf.net/docs/ref/rst/restructuredtext.html#autonumber-labe= ls --=20 David Goodger <http://python.net/~goodger> |
From: <ra...@gm...> - 2006-07-04 07:45:17
|
Hi, I wanted to summarise my views on what citations in rst could be like. I hope this helps to clarify issues related to this thread (maybe not for you but for me ;-). Sorry, the email is rather longish. And some parts are in total disregard of 'compatibility with docutils' and current implementation. To make sure I do not increase the confusion of terms (adapted from the rst documentation):: Here is a 'citation reference': [CIT2002]_. (CIT2002 is the 'citation label' or, equivalently, the 'citation key'.) When referring to the final output version, I add 'output' or talk about 'formatting'. .. [CIT2002] This line and the next is the 'citation text'. The citation text plus the initial `.. [CIT2002]` is the 'citation'. There are three routes from source to output: - TBLOR (the bibtex+latex output route), - TLORNUB (the latex output route not using bibtex), and - ANLOR (any non-latex output route) All three should have similar capabilities, while the first two can (and should) use latex facilities, the latter may need different support. When not using bibtex, some of this support is needed for latex too (in order to format \bibitem's which is also what bibtex uses). The features that could be addressed: 1. Finding citation keys in a (separately maintained) databases, and generating a matching list of citations. (latex can use bibtex for this purpose.) A sub-problem is automatically solved with this (and only this) approach: 1.1. Consistent formatting of the citation texts. TBLOR can delegate to bibtex, the other routes could use the mystical (== not yet existent) rst-preprocessor (the MRP :-), or an equivalent plugin/integration into docutils. Another sub-problem could be considered solved by this approach: 1.2. Sorting the bibliography section by some criteria like order in text, alphabetically by key, by author(s) and year, ... although it would make sense to support this for ordinary citation use in rst too: a directive could be used to collect all citations at a specific place in the output. I think this is the intended meaning of the citations directive, marked as not yet implemented in the docs? 2. Advanced citation references. It's useful to distinguish subtypes: 2.1. format *all* output citation references in a consistent form (brackets vs. parentheses, and numbered vs. keys vs. abbreviated author names). This should also format the beginning of the citation in the same way. TBLOR can use a \bibliographystyle{} and maybe \bibpunct to achieve this. With TLORNUB the \bibitem[labels] can be changed. I personally do not care for styles that use numbered citations, and the substitution of reference labels/keys based on citation text is surely not in the domain of rst (but both would still be possible for TBLOR, and when using the MRP =). This leaves changing output citation reference punctuation. This is output *style* only, would be hard to do using output stylesheets alone, and would probably be a 'simple' extension to the docutils writers. The MRP could address this both with the proposed reference substitution (see 2.2) or with phrase references (see 2.3) plus an option to omit brackets in the ouput. (for manual use this way would be error-prone and hard to change.) 2.2. format all citation references *with a specific key* consistently different. This is what the substitution proposed by Alan addresses:: On Jun 30, 2006, at 6:31 PM, Alan G Isaac wrote roughly: > Here is my reference to [Goodger2006]_, which I want > substituted. > .. [Goodger2006] replace:: (Goodger 2006) > Above is the inline-substitution text, while here > is the actual citation. latex supports this as a \bibitem[option]{}. The main use I see is that it can be a basis for 2.1, and that it allows the MRP to substitute database keys with nicer-to-read labels. 2.3. format *one specific citation reference*, differently than others (even those with the same key). This can be addressed with the phrase references and indirect references:: The Goodger triple [`Goodger (2006)`]_ [`(Goodger 2006)`]_ [`Goodger, 2006`]_ appears again. .. _Goodger (2006): `Goodger, 2006`_ .. _(Goodger 2006): `Goodger, 2006`_ .. [Goodger, 2006] citation text here This (plus an option to omit the standard brackets) can be a workaround for 2.1 and 2.2. 2.4. add extra text to a citation reference without affecting the citation key, e.g., a page reference. (in latex: \cite[p.42]{BlablaETAL1900} ) Sometimes it is ok to simply put this in the text adjacent to the reference. For the other cases: For ANLOR only, a workaround is possible with the phrase reference syntax. For TLORNUB and TBLOR, the option **needs to be kept with the reference**, so this would need a change to the docutils document model aka 'parameterised interpreted text' or a subset that works for citation references only. An awkward workaround is possible with the MRP, and for TBLOR with a matching post-processor, by using a convention for extending citation labels: e.g. [CIT2002_p42]_. 2.5. explicit different types of citation references: parenthesis around the whole reference or only the year. (in latex: \citep{} vs. \citet{} or \cite{}) I, personally, like citation references that look consistently the same, no matter where they are in the text. Unfortunately, some style guides do not agree with me. The same notes as for 2.4 apply here. 2.6. multiple citation keys in one citation reference. (in latex: \cite{X,Y,Z} ) This also needs an extension of the document model, but could be done without changing the rst input syntax, in a transform that collects adjacent references. I think phrase references and indirect references for citations and an option to omit the standard brackets in the output are a good start: they allow 2.2 and 2.3, as well as an approximation of 2.1, 2.4, and 2.5. But hope dies last (especially the hope that I will have the time to implement some of this =) Thanks for reading. cheers, stefan |
From: Alan G I. <ai...@am...> - 2006-07-13 09:46:38
|
On Wed, 12 Jul 2006, David Goodger apparently wrote:=20 > No matter how many people indicate usefulness, some=20 > proposals are unacceptable and will be rejected. =20 > I believe this proposal to be one of these. Please=20 > consider this a pronouncement, and give it a rest.=20 Do you mean my specific proposal? I am not attached to it. Or also the fully adequate alternative you discussed? I am hoping you have not also ruled that out. The rest of this post assumes that you have not. On Wed, 12 Jul 2006, David Goodger apparently wrote:=20 > A preprocessor could handle everything, with no change to=20 > reST.=20 But that kind of preprocessing would be much more complex. By relying on Bibstuff, we are already almost there, if we can provide citation-label-substitution text in some=20 form. Note that Bibstuff would provide only the citations and would not touch the rest of the document! On Wed, 12 Jul 2006, David Goodger apparently wrote:=20 > An alternative could be to implement a new directive for citations,=20 > something like this::=20 > .. citation:: Goodger2006=20 > :substitute: (Goodger 2006)=20 > This is the citation text. The ":substitute:" option above=20 > supplies the display citation label. Directive options allow=20 > for more flexible constructs than are otherwise possible, at=20 > the expense of some verbosity.=20 That would be excellent! Cheers, Alan Isaac PS Disregard my previous post, written before seeing your new message. |
From: David G. <go...@py...> - 2006-07-13 13:55:04
Attachments:
signature.asc
|
[Alan G Isaac] > On Wed, 12 Jul 2006, David Goodger apparently wrote:=20 >> No matter how many people indicate usefulness, some=20 >> proposals are unacceptable and will be rejected. =20 >> I believe this proposal to be one of these. Please=20 >> consider this a pronouncement, and give it a rest.=20 >=20 > Do you mean my specific proposal? I am not attached to it. > Or also the fully adequate alternative you discussed? Both. I haven't ruled out the alternative, but I don't see the need for = it, and I'm really tired of hearing the same lame arguments over and over. > I am hoping you have not also ruled that out. > The rest of this post assumes that you have not. >=20 > On Wed, 12 Jul 2006, David Goodger apparently wrote:=20 >> A preprocessor could handle everything, with no change to=20 >> reST.=20 >=20 > But that kind of preprocessing would be much more complex. Show us, don't tell us. IOW: prove it. Please put it in a comprehensive= proposal. --=20 David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-13 16:28:24
|
On Thu, 13 Jul 2006, David Goodger apparently wrote: > Please put it in a comprehensive proposal. I fear that what looks comprehensive to a user will not so appear to a developer. But here is a first pass. Cheers, Alan Isaac ============================== Proposal for Citation Handling ============================== Citation handling virtues: - not be LaTeX specific. - allow easy interaction with a bibliographic database - allow easy change of formatting both of the citation label and of the citation - allow continuous working on the original document without continually regenerating the citations (unless of course new citation references have been added) - allow hyperlinks from citation labels (as substituted) to citations, and otherwise retain reST's current and future handling of citations Given the ready existence of a preprocessor (Bibstuff_), this proposal assumes the database is in .bib format. (While Bibstuff_ remains crude, it is easily modifiable, often even by programming novices like myself.) This does *not* make the proposal LaTeX specific: this is just a common format for bibliographic databases. Many databases export to this useful format. The Proposal ============ The proposal: for reST to support substitution for the citation reference labels, so that reST writers can replace the citation label with citation-label-substitution text that is specified in the citation. The motivation: documents presented in different settings are required to format the citation references in different ways. It is desirable to maintain one version of the document where the citations and citation labels (as substituted) can readily be reformatted as needed. A comment: one important thing for preprocessing is that the document can be searched for citation references. The current citations reference syntax allows this to be done easily. For example, Bibstuff_ can already do this. The object: all of the content in a References section is to be generated by a preprocessor. This includes both the (proposed) citation-label-replacement text and the (already supported) citation text. Citation-label replacement is to be handled by reST, *not* by a preprocessor. (See the Comments below.) Example ======= For illustration, let us cite two books: [goossens_1994]_ and [lutz_2003]_. Here the citation labels are the keys in a bibliographic database. Such citation references are easily recognized as such by preprocessors: for example, Bibstuff_ already can compile a list of citation references from an reST document. [goossens_1994]_ is a handy guide to LaTeX. [lutz_2003]_ is an introduction to the programming language Python. Since the citation labels for these two books are keys in a citation database, a preprocessor can be used to generate both the citation and the citation-label-substitution text. Here is what the database looks like:: @BOOK{goossens_1994, author = {Gossens, Michel and Frank Mittelbach and Alexander Samarin}, year = 1994, title = {The LaTeX Companion}, edition = {2nd}, publisher = {Addison-Wesley}, address = {Boston, MA}, isbn = {0-201-54199-8} } @BOOK{lutz_2003, author = {Lutz, Mark and David Ascher}, year = 2003, title = {Learning Python}, publisher = {Oreilly}, address = {Sebastopol, CA}, isbn = {1-56592-464-9} } Here is what Bibstuff's addrefs.py currently produces when run on this document:: Gossens, Michel, Mittelbach, Frank and Samarin, Alexander. 1994. The LaTeX Companion. Lutz, Mark, and Ascher, David. 2003. Learning Python. Note that there is no obvious way to control where these citations should be physically placed. The current practice of addrefs.py is to simply append them to the file. A better (and easily implemented, even for me) approach is to write them to a new file for inclusion with reST's `include` directive. (See the Comments below.) Here is what I would like to modify Bibstuff to produce (based on David Goodger's comments). (I will sink energy into doing so if David decides to implement the citation directive.) .. citation:: goossens_1994 :replace: Goossens (1994) Gossens, Michel and Frank Mittelbach and Alexander Samarin, *The LaTeX Companion*, Addison-Wesley, 1994 .. citation:: lutz_2003 :replace: Lutz (2003) Lutz, Mark and David Ascher, 2003, *Learning Python*, Oreilly, 2003 Comments ======== 1. By outputting such citations to a separate file, the citations can simply be included at the desired location with the reST `include` directive. (Those familiar with LaTeX will note the parallels to the .bbl file, which holds the citations generated by a run of BibTeX.) 2. Is this approach better than relying on the preprocessor to produce an entire new document, with all inline substitutuions already in place. (Bibstuff_ can do this, somewhat crudely, already.) David has suggested no. I suggest that it is a much simpler and better arrangement: - the citations are readily included anywhere that is desirable (via the `include` directive), which is important. - reST will properly handle the links from the citations labels (i.e., the substitute handled by reST), whereas this capability disappears if we run a writer an a document where the substitutions have been preprocessed. It is valuable to retain reST's current and future handling of citations in this and other, possibly unforeseeable, way. I will add one different kind of argument: the LaTeX practice, which this proposal in some sense mimics, was developed by people who thought much longer and harder about citations than we have, and it has served very well over time. .. LINKS .. _Bibstuff: http://www.pricklysoft.org/software/bibstuff.html |
From: David G. <go...@py...> - 2006-07-13 18:07:16
|
On 7/13/06, Alan G Isaac <ai...@am...> wrote: > I fear that what looks comprehensive to a user will > not so appear to a developer. That's OK, we'll tackle the details as required. I will ask for clarification on several issues later. Let's put this into Subversion, for ease of collaborative editing and for posterity. We'll add it to docs/dev/rst/alternatives.txt, perhaps in a new section "Under Consideration". Alan, please tell me your berlios.de account name. If you don't have an account, you can get one here: https://developer.berlios.de/ -- David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-15 01:15:44
|
I seem to need clarification on two things. 1. Are arbitrary phrase reference names already permissible as citation reference labels? (I thought not, and indeed think this becomes unnecessary under the new proposal.) 2. Is it desirable that citation references in the text should *look* like citation references, as a matter of the readability of the reST document, and independent of the consideration of whether the citation-reference-label-substitution proposal is ultimately viewed as worth implementing? (I think this is right, so various replacement-substitution alternatives look a bit perverse to me.) Thank you, Alan Isaac |
From: David G. <go...@py...> - 2006-07-15 03:32:52
Attachments:
signature.asc
|
[Alan G Isaac] > I seem to need clarification on two things. >=20 > 1. Are arbitrary phrase reference names already permissible > as citation reference labels? Not yet, no. I do intend to implement it though, as it makes reST more consistent and orthogonal. This benefits the general use of citations, regardless of any specific limited case. > (I thought not, and indeed > think this becomes unnecessary under the new proposal.) I see it the other way around: phrase reference names as citation labels obviates the need for special-case citation label substitution. > 2. Is it desirable that citation references in the text > should *look* like citation references, as a matter of=20 > the readability of the reST document, and independent > of the consideration of whether the=20 > citation-reference-label-substitution proposal is=20 > ultimately viewed as worth implementing? (This seems like a rather leading question, but...) Yes. Substitutions should look like substitutions also. > (I think this=20 > is right, so various replacement-substitution=20 > alternatives look a bit perverse to me.) Which do you mean? The original citation label replacement-substitution = syntax proposal, or the directive approach I showed, or the substitution approa= ch without a new directive or new syntax? --=20 David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-17 01:57:36
|
>> 2. Is it desirable that citation references in the text >> should look like citation references, as a matter of the >> readability of the reST document, and independent of the >> consideration of whether the >> citation-reference-label-substitution proposal is >> ultimately viewed as worth implementing? On Fri, 14 Jul 2006, David Goodger apparently wrote: > (This seems like a rather leading question, but...) Yes. > Substitutions should look like substitutions also. I think a lot is going to turn on this. Right now we have: 1. citation references should in some way be able to support substitution (although perhaps by eschewing the citation reference mechanism provided by reST) 2. citation references should look like citation references 3. substitutiion references should look like substitution references Now if I understand David's "exploratory proposal" for a citation directive, docutils writer components dealing with the citation reference [goossens_1994]_ would make an inline substitution for the citation reference label based on the following citation directive. .. citation:: goossens_1994 :replace: Goossens (1994) Gossens, Michel and Frank Mittelbach and Alexander Samarin, *The LaTeX Companion*, Addison-Wesley, 1994 Do I have that right? If so, this would satsify 1. and 2. above but I understand David to object that it would not satisfy point 3. above. One suggested response to this was that citation references be considered to always imply substitution, even when the substitution is the same citation label. I find that response a bit "scholastic" in approach, but perhaps worth mentioning. But the question seems to me to be more fundamental: is a citation reference, for which a citation label substitution is desired, more like a citation reference or like an arbitrary substitution reference? I am not yet sure how to provide an argument for my perspective, but I consider it evident that it is not only more like a citation reference but *essentially is* a citation reference. Therefore, it should look in reST like any other citation reference. Anything else will be "surprising". Suppose instead that the reader enconters |goossens_1994|_ in the text. The reader knows only that a (hyperlinked) substitution reference has been encountered. Is it a citation reference? A figure reference? Or some other object? The reader has no way to tell except possibly from an author-specific context (i.e., some clues not mandated by reST). This seems badly wrong. Right? And not only is it hard for a human reader to tell what it intended, it is also hard for a preprocessor to tell whether it should treat this substituion reference as a citation reference or not. And since I think we have agreed that allowing preprocessors interact with reST documents and bibliographic databases to produce citations for the document is a good idea, keeping things easy for preprocessors seems also like a good idea. Cheers, Alan Isaac PS After I get David's response to the above perspective I will try to incorporate both into the citation-enhancement document. |
From: David G. <go...@py...> - 2006-07-17 16:15:49
|
[Alan G Isaac] >>> 2. Is it desirable that citation references in the text >>> should look like citation references, as a matter of the >>> readability of the reST document, and independent of the >>> consideration of whether the >>> citation-reference-label-substitution proposal is >>> ultimately viewed as worth implementing? [David Goodger] >> (This seems like a rather leading question, but...) Yes. >> Substitutions should look like substitutions also. [Alan G Isaac] > I think a lot is going to turn on this. > Right now we have: > > 1. citation references should in some way be able to > support substitution (although perhaps by eschewing > the citation reference mechanism provided by reST) What exactly do you mean by the parenthesized part? What are you referring to? If I read it correctly, I disagree. There is no avoidance of the reST-supplied citation reference mechanism at all, just an indirect use of it via substitutions. A necessary aside: This discussion is getting even more complex, and these imprecise references make it worse (imprecise from my perspective; I can't be sure what's being referred to). Please provide more background info, more precise references, even if that takes more words. Verbose is good in technical discussions. Please do me the courtesy of answering my questions. When I ask a question, it's because I want/need the answer. The questions are not rhetorical. I am getting increasingly frustrated by this discussion. I tried to put an end to it once, and I don't see the point in continuing. I will follow through here in good faith, but my patience is running out. I would put the unparenthesized part above differently. You want citation references (& definitions?) to support substitutions. I say they already do [*]_ -- via the existing substitution mechansism -- and no addition is necessary. I have yet to be convinced otherwise. IOW, I consider (1) to be an invalid assumption/goal. .. [*] Or should; there may be a bug currently. > 2. citation references should look like citation > references > 3. substitutiion references should look like > substitution references > > Now if I understand David's "exploratory proposal" for > a citation directive, docutils writer components dealing > with the citation reference [goossens_1994]_ would make an > inline substitution for the citation reference label based > on the following citation directive. It has nothing to do with writer components. This is all in the parser. Substitutions are entirely a reST parser mechanism. > .. citation:: goossens_1994 > :replace: Goossens (1994) > > Gossens, Michel and Frank Mittelbach and Alexander Samarin, > *The LaTeX Companion*, > Addison-Wesley, 1994 > > Do I have that right? There's a lot more than simply adding a new directive. We'd have to add *support* for the new *functionality*. At the very least, the directive above would be an interface to the existing substitution mechansim. But... there *is* an existing, working mechanism, so why implement something new? > If so, this would satsify 1. and 2. above > but I understand David to object that it would not satisfy > point 3. above. > > One suggested response to this was that citation references > be considered to always imply substitution, even when the > substitution is the same citation label. I find that > response a bit "scholastic" in approach, but perhaps worth > mentioning. I agree -- so that idea is out. But that leaves the proposal worse off, not better. > But the question seems to me to be more fundamental: is > a citation reference, for which a citation label > substitution is desired, more like a citation reference or > like an arbitrary substitution reference? The question doesn't make sense. Citations and substitutions are completely orthogonal. If you want both simultaneously, apply both. End of story. > I am not yet sure > how to provide an argument for my perspective, but > I consider it evident that it is not only more like > a citation reference but *essentially is* a citation > reference. Therefore, it should look in reST like any other > citation reference. Anything else will be "surprising". You may consider it evident, but I am entirely unconvinced. You want citation references to use simple labels in the input text (the citation key), but different labels in the output (the display label, generated by the preprocessor). You want to be able to define the output/display label text in one place, for all applicable citation references. I have shown that this is possible without any new directive and without adding substitution functionality to citations. You seem to be entirely focused on this one feature and refuse to recognize the solution presented. But there's a greater whole that needs to be considered. > Suppose instead that the reader enconters |goossens_1994|_ > in the text. The reader knows only that a (hyperlinked) > substitution reference has been encountered. This form has never been suggested in this discussion. It's not on the table. (Please correct me if I'm wrong.) > Is it a citation > reference? A figure reference? Or some other object? The reader > has no way to tell except possibly from an author-specific > context (i.e., some clues not mandated by reST). This seems > badly wrong. Right? Incorrect. The substitution syntax says "something else is going to go here". To know what, the reader must refer to the definition. But that's infinitely better than some text being replaced without any notice at all. The author can and should use a convention that makes sense to all readers (author, preprocessor, end-readers). There's nothing wrong with that. > And not only is it hard for a human reader to tell what it > intended, it is also hard for a preprocessor to tell whether > it should treat this substituion reference as a citation > reference or not. And since I think we have agreed that > allowing preprocessors interact with reST documents and > bibliographic databases to produce citations for the > document is a good idea, Perhaps you think so, but *I* never agreed. My position is that if you want to preprocess reST for citations, go right ahead. But I see no need for reST to make changes to accommodate preprocessors. That would be the tail wagging the dog. > keeping things easy for > preprocessors seems also like a good idea. I have asked questions about how Bibstuff interacts with the input, but no answers yet. In any case, I don't really care how hard or easy it is for preprocessors. If a preprocessor can recognize [citation]_, it can certainly recognize |[citation]_| or whatever other convention is used. > PS After I get David's response to the above perspective > I will try to incorporate both into the citation-enhancement > document. Please answer the questions I've raised here and in my previous message (where I quoted your entire proposal) first. -- David Goodger <http://python.net/~goodger> |
From: Stuart R. <st...@za...> - 2006-07-17 19:16:36
|
Hi, guys. > You want citation references to use simple labels in the input text > (the citation key), but different labels in the output (the display > label, generated by the preprocessor). You want to be able to define > the output/display label text in one place, for all applicable > citation references. At the risk of muddying the water, I don't see how being able to define the output/display label text in one place for all applicable citation references really gives you what you'd want for a complete citation solution. For example, consider the following reST text: Here is a parenthetical citation [goossens:1994]_. But [goossens:1994]_ says so and so. When it comes out as LaTeX, you would want something like this: Here is a parenthetical citation \citep{goossens:1994}. But \cite{goossens:1994} says so and so. Note that there are two commands: \citep vs. \cite. How would you get from the reST to the LaTeX above with global substitution? I don't think you can. And I also don't see how you could with a pre- or post-processor either. +----------------------------------------+ | Stuart Robinson | | Email: st...@za... | | Homepage: http://www.zapata.org/stuart | +----------------------------------------+ |
From: Alan G I. <ai...@am...> - 2006-07-17 19:40:19
|
On Mon, 17 Jul 2006, Stuart Robinson apparently wrote:=20 > Here is a parenthetical citation [goossens:1994]_. But=20 > [goossens:1994]_ says so and so.=20 > When it comes out as LaTeX, you would want something like this:=20 > Here is a parenthetical citation \citep{goossens:1994}. But=20 > \cite{goossens:1994} says so and so.=20 > Note that there are two commands: \citep vs. \cite. How would you get fro= m=20 > the reST to the LaTeX above with global substitution? I don't think you= =20 > can. And I also don't see how you could with a pre- or post-processor=20 > either.=20 1. David has ruled out (for now at least) parameterized citation references 2. If we rely on substitution, as David has been suggesting, then paramaterization (for the preprocessor) will be=20 nevertheless be easily possible, and long as we agree on a convention for the substitution reference names. 3. Right now I am trying to get 80% functionality, now full LaTeX style handling. Cheers, Alan Isaac |
From: Alan G I. <ai...@am...> - 2006-07-17 19:42:33
|
On Mon, 17 Jul 2006, Alan G Isaac apparently wrote:=20 > now full LaTeX style handling.=20 now -> NOT Cheers, Alan Isaac |
From: David G. <go...@py...> - 2006-07-17 19:50:35
|
On 7/17/06, Stuart Robinson <st...@za...> wrote: > Note that there are two commands: \citep vs. \cite. How would you get from > the reST to the LaTeX above with global substitution? You can't. In reST, just do this: Here is a parenthetical citation ([goossens:1994]_). But [goossens:1994]_ says so and so. IOW, just include the parentheses. Of course, the follow-up is to say that parenthetical citations (the text inside the parentheses) should be formatted differently from inline citations. My answer: not in reST, sorry. If you need that level of detail, use LaTeX. -- David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-17 19:34:17
|
On Mon, 17 Jul 2006, David Goodger apparently wrote: > If a preprocessor can recognize [citation]_, it can > certainly recognize |[citation]_| or whatever other > convention is used. I COMPLETELY agree with this. AND I even like this proposed syntax. It is completely clear: a citation reference that is substituted and linked. (One drawback: it is just a convention, not a syntax enforced by reST. But as I understand you, you do not see that as a big drawback.) So say I have the substitution reference |[doe2006b]_|. I define the substitution: .. |[doe2006b]_| replace:: `Doe (2006b)`_ That substitution works fine, of course. And next if I understand you, I can provide the target for that link: .. _Doe (2006b): Doe2006b which you indicate should allow me to link to the following citation .. [Doe2006b] Doe, John, 2006, An Interesting Article Do I have that right? If so, this seems fine, *especially* when coupled with your intent to allow phrase reference names as citation reference labels, KEY QUESTION: Should this really work right now? (I cannot get the link to the citation label to "pass through" this way: do I need to update from 0.3.10?) Thank you, Alan Isaac PS About answering the other questions: I will. I am just trying to get some clarifications before I give you my answers, many of which have already become irrelevant due to your recent clarifications. But quickly to one that appears central at the moment: Bibstuff recognizes citation references (roughly) by looking for the currently allowed syntax for citation references: a reference name in brackets followed by an underscore. This is probably not hard to modify to any regular expression, but of course for preprocessing to work there must be *some* regular expression that can identify citation references. |
From: Alan G I. <ai...@am...> - 2006-07-18 13:23:34
|
On Mon, 17 Jul 2006, Alan G Isaac apparently wrote: > Bibstuff recognizes citation > references (roughly) by looking for the > currently allowed syntax for citation > references: a reference name in brackets > followed by an underscore. > This is probably not hard to modify > to any regular expression, > but of course for preprocessing to work > there must be some regular expression > that can identify citation references. This is not quite right: the reference to regular expressions is misleading, since Bibstuff is relying on an EBNF grammar (via SimpleParse, a dependency). The current definition of a cite is very simple and allows much that would not be permitted by reST:: cite := '[', -[]]+, ']_' fwiw, Alan Isaac |
From: David G. <go...@py...> - 2006-07-14 19:25:58
Attachments:
signature.asc
|
[Quoting the entire document for continuity.] > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D > Proposal for Citation Handling > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D > > Citation handling virtues: Do you mean "goals"? > - not be LaTeX specific. > - allow easy interaction with a bibliographic database > - allow easy change of formatting both of the > citation label and of the citation Both the citation reference and the citation definition have labels. Please, let's be precise here. Let's add a terminology preamble: "Citation reference": such as [Doe2006]_, occurs in text. "Citation" or "citation definition": .. [Doe2006] This is the citation: it's the construct that contains the details of the work being cited. Both of these have a "citation label", a reference name, which links them ("Doe2006" above). A "citation key" is the bibliographic database lookup key. Proposed is a "citation label substitution" which will replace the citation label in the final formatted output, resulting in a "display citation label". Please ensure that the text conforms to this terminology. Otherwise, we're just wasting each other's time. Replace the last line with "citation reference's display label and of the citation's display label"? Does this mean that you want to reformat the citation's label too? Together with reformatting the citation reference's label, or separately? > - allow continuous working on the original document > without continually regenerating the citations > (unless of course new citation references have been added) I don't know what this means. When do you regenerate the citations? This doc needs a workflow description. > - allow hyperlinks from citation labels (as substituted) > to citations, and otherwise retain reST's current > and future handling of citations > > Given the ready existence of a preprocessor (Bibstuff_), > this proposal assumes the database is in .bib format. > (While Bibstuff_ remains crude, it is easily modifiable, > often even by programming novices like myself.) > > This does *not* make the proposal LaTeX specific: > this is just a common format for bibliographic databases. > Many databases export to this useful format. > > > The Proposal > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > The proposal: > for reST to support substitution for the citation reference > labels, so that reST writers can replace the citation label > with citation-label-substitution text that is specified in > the citation. By "reST writers" do you mean authors (humans), or Docutils Writer components (software)? > The motivation: > documents presented in different settings are Replace "settings": perhaps "contexts (journals, web sites, etc.)". > required to format the citation references in different > ways. It is desirable to maintain one version of the > document where the citations and citation labels (as > substituted) can readily be reformatted as needed. > > A comment: > one important thing for preprocessing is that the document can be > searched for citation references. The current citations > reference syntax allows this to be done easily. For > example, Bibstuff_ can already do this. If phrase reference names are allowed as citation labels, will Bibstuff still be able to find citation references? For example (intentionally complex), [`this::could-be, "a" [citation?\`]_ reference!`]_ > The object: > all of the content in a References section is to be > generated by a preprocessor. This includes both the > (proposed) citation-label-replacement text and the (already > supported) citation text. Citation-label replacement is to > be handled by reST, *not* by a preprocessor. (See the > Comments below.) > > > Example > =3D=3D=3D=3D=3D=3D=3D > > For illustration, > let us cite two books: [goossens_1994]_ and [lutz_2003]_. > Here the citation labels are the keys in a bibliographic database. > Such citation references are easily recognized as such by > preprocessors: for example, Bibstuff_ already can compile a list of > citation references from an reST document. > > [goossens_1994]_ is a handy guide to LaTeX. > [lutz_2003]_ is an introduction to the programming language Python. > Since the citation labels for these two books are keys in a citation > database, a preprocessor can be used to generate both the citation > and the citation-label-substitution text. > > Here is what the database looks like:: > > @BOOK{goossens_1994, > author =3D {Gossens, Michel and Frank Mittelbach > and Alexander Samarin}, > year =3D 1994, > title =3D {The LaTeX Companion}, > edition =3D {2nd}, > publisher =3D {Addison-Wesley}, > address =3D {Boston, MA}, > isbn =3D {0-201-54199-8} > } > @BOOK{lutz_2003, > author =3D {Lutz, Mark and David Ascher}, > year =3D 2003, > title =3D {Learning Python}, > publisher =3D {Oreilly}, > address =3D {Sebastopol, CA}, > isbn =3D {1-56592-464-9} > } > > Here is what Bibstuff's addrefs.py currently produces when > run on this document:: > > Gossens, Michel, Mittelbach, Frank and Samarin, > Alexander. 1994. The LaTeX Companion. Does Bibstuff automatically turn "Frank Mittelbach" into "Mittelbach, Frank"? If so, that's dangerous -- not all names work that way. How does Bibstuff recognize citation references? Can its recognition mechanism be customized? How? > Lutz, Mark, and Ascher, David. 2003. Learning Python. > > Note that there is no obvious way to control where these > citations should be physically placed. The current practice > of addrefs.py is to simply append them to the file. > A better (and easily implemented, even for me) approach is > to write them to a new file for inclusion with reST's > `include` directive. (See the Comments below.) This seems very reasonable. > Here is what I would like to modify Bibstuff to produce > (based on David Goodger's comments). (I will sink energy > into doing so if David decides to implement the citation > directive.) > > .. citation:: goossens_1994 > :replace: Goossens (1994) > > Gossens, Michel and Frank Mittelbach and Alexander Samarin, > *The LaTeX Companion*, > Addison-Wesley, 1994 > > .. citation:: lutz_2003 > :replace: Lutz (2003) > > Lutz, Mark and David Ascher, 2003, > *Learning Python*, > Oreilly, 2003 If the above could be produced, it should be just as easy to produce this: .. |[lutz_2003]| replace:: [`Lutz (2003)`]_ .. _Lutz (2003): lutz_2003 .. [lutz_2003] Lutz, Mark and David Ascher, 2003, *Learning Python*, Oreilly, 2003 Since a preprocessor is required either way, the added complexity of this approach shouldn't be a problem. In your text, all you have to do is insert "|[lutz_2003]|" instead of "[lutz_2003]_". The first line above is a substitution definition, replacing the inline text with the final display citation label. I included square brackets in the substitution reference ("|[...]|") to simulate a regular citation reference, but arbitrary text could be used (e.g. "|lutz_2003|" or "|(lutz_2003)|"), whatever works well with Bibstuff and the author's conventions. The second line links "Lutz (2003)" to "lutz_2003", the citation key. The last 4 lines are the citation itself. But from the above, it seems that you want both citation reference and citation definition to have the same display label. In that case, the above can be simplified to: .. |[lutz_2003]| replace:: [`Lutz (2003)`]_ .. [Lutz (2003)] Lutz, Mark and David Ascher, 2003, *Learning Python*, Oreilly, 2003 > Comments > =3D=3D=3D=3D=3D=3D=3D=3D > > 1. By outputting such citations to a separate file, > the citations can simply be included at the desired > location with the reST `include` directive. > (Those familiar with LaTeX will note > the parallels to the .bbl file, which holds the citations > generated by a run of BibTeX.) > 2. Is this approach better than relying on the preprocessor > to produce an entire new document, with all inline > substitutuions already in place. Is that a question? > (Bibstuff_ can do this, > somewhat crudely, already.) David has suggested no. You misunderstood me; I never suggested that. The "insert a references section via the include directive" approach is perfectly reasonable. > I suggest that it is a much simpler and better arrangement: > > - the citations are readily included anywhere that is > desirable (via the `include` directive), > which is important. No argument here. > - reST will properly handle the links from the citations labels > (i.e., the substitute handled by reST), whereas this > capability disappears if we run a writer an a document where > the substitutions have been preprocessed. Not true. The mechanism I showed above should work just fine. > It is valuable to retain > reST's current and future handling of citations in > this and other, possibly unforeseeable, way. I agree. > I will add one different kind of argument: the LaTeX practice, > which this proposal in some sense mimics, was developed by people > who thought much longer and harder about citations than > we have, and it has served very well over time. That argument is irrelevant. The LaTeX people thought about citations *in the context of LaTeX*, not in the context of reST. I have no problem whatsoever with the Bibtex/Bibstuff/preprocessor approach you're advocating. I do have a problem with the duplication of functionality when existing functionality should do the job just fine. "There should be one -- and preferably only one -- obvious way to do it" applies here also (it's originally from the Zen of Python (http://www.python.org/doc/humor/#zen). In any case, you've shown no evidence of "the LaTeX practice". You've described a bit about the Bibtex/Bibstuff practice. How does that relate to LaTeX? We don't *want* to mimic LaTeX. LaTeX is great, but reST is not LaTeX; reST should not be LaTeX, and never will be LaTeX. It's part of my job to be a gatekeeper, to resist efforts to make reST into LaTeX. > .. LINKS > > .. _Bibstuff: http://www.pricklysoft.org/software/bibstuff.html --=20 David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-14 20:00:00
|
On Fri, 14 Jul 2006, David Goodger apparently wrote: > [Quoting the entire document for continuity.] I think I understand all your comments. I will try to produce a response/revision by Monday. Thank you, Alan Isaac |
From: Stuart R. <st...@za...> - 2006-07-14 21:11:19
|
Hey, this is great. It looks like some real progress is being made. Let me know if there is any way the rest of us can help. -Stuart On Fri, 14 Jul 2006, Alan G Isaac wrote: > On Fri, 14 Jul 2006, David Goodger apparently wrote: > > [Quoting the entire document for continuity.] > > I think I understand all your comments. > I will try to produce a response/revision by Monday. > > Thank you, > Alan Isaac > > > > > > ------------------------------------------------------------------------- > Using Tomcat but need to do more? Need to support web services, security? > Get stuff done quickly with pre-integrated technology to make your job easier > Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo > http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. > -- +----------------------------------------+ | Stuart Robinson | | Email: st...@za... | | Homepage: http://www.zapata.org/stuart | +----------------------------------------+ |