From: Alan G I. <ai...@am...> - 2005-10-03 19:16:26
|
About the only time I really feel frustrated with reST is=20 when I hit citations. I'm trying to find a way to be happy. Here is one idea. 1. Do not restrict the character set quite so much for=20 reference names. In particular, allow isolated hyphens, parentheses, colons, and nonbreaking space. I do not use=20 plusses (+) in my keys but a lot of people do: allowing=20 this is therefore also a good idea. 2. Allow suppressing the brackets on the inline reference=20 names. 3. The first two enhancements would mean that I could write=20 [Isaac=C2=A0(2005)]_ or [(Isaac=C2=A02005)] to get Isaac=C2=A0(2005) or= =20 (Isaac=C2=A02005) in the text. (That's a nonbreaking space.) =20 These are standard citation styles in my field for inline=20 and end-of-line citation references. 4. Allow citation aliasing. [LikeThis]_ .. [LikeThis] [Isaac2005] When combined with the previous suggestions, this would=20 allow a single target for inline and end-of-line citation=20 references. OK, that would be perfectly livable. But the following=20 would be even better (although I don't expect it to be well=20 received). I would like to be able to write:: reference HTML format [t:Isaac2005,p.121] -> Isaac (2005,p.121) [p:Isaac2005,p.121] -> (Isaac 2005,p.121) and have the two citation references both point to .. [Isaac2005] The citation text. This of course requires some conventions: - the single alphabetic modifier before a colon - concluding digits specify a date - a comma separates off supplementary citation information The LaTeX writer would be able to use natbib (it's the=20 standard) to handle these naturally: reference LaTeX [t:Isaac2005,p.121] -> \citet[p.121]{Isaac2005} [p:Isaac2005,p.121] -> \citep[p.121]{Isaac2005} Cheers, Alan Isaac |
From: David G. <go...@py...> - 2005-10-04 03:13:15
Attachments:
signature.asc
|
[Alan G Isaac] > About the only time I really feel frustrated with reST is > when I hit citations. I'm trying to find a way to be happy. > Here is one idea. > > 1. Do not restrict the character set quite so much for > reference names. In particular, allow isolated hyphens, Isolated internal hyphens, underscores, and periods are already allowed. This works just fine: [cit-ref_no.1]_ .. [cit-ref_no.1] citation (http://docutils.sf.net/docs/ref/rst/restructuredtext.html#citations) > parentheses, colons, and nonbreaking space. > I do not use plusses (+) in my keys but a lot of people > do: allowing this is therefore also a good idea. > > 2. Allow suppressing the brackets on the inline reference > names. You mean for the output? > 3. The first two enhancements would mean that I could write > [Isaac (2005)]_ or [(Isaac 2005)] to get Isaac (2005) or > (Isaac 2005) in the text. (That's a nonbreaking space.) > These are standard citation styles in my field for inline > and end-of-line citation references. What do you mean by "end-of-line citation references"? What is the standard you're using? Do you have a reference URL? > 4. Allow citation aliasing. [LikeThis]_ > > .. [LikeThis] [Isaac2005] > > When combined with the previous suggestions, this would > allow a single target for inline and end-of-line citation > references. Perhaps you should be using hyperlink references, which already allow all of these things. For example: Here we have the document text, with an ordinary citation reference: [Isaac2005]_. But we can implement any form we like: * `Isaac (2005,p.121)`_ * `(Isaac 2005,p.121)`_ .. _Isaac (2005,p.121): .. _(Isaac 2005,p.121): .. [Isaac2005] Citation text We don't even need to duplicate references, but can use anonymous & indirect references instead: `Isaac (2005,p.121)`__ __ Isaac2005_ etc. ... `(Isaac 2005,p.121)`__ __ Isaac2005_ etc. ... .. [Isaac2005] Citation text An alternative would be to revise citation syntax to allow phrase-references as well as simple reference names (http://docutils.sf.net/docs/ref/rst/restructuredtext.html#reference-names). But this would require a non-trivial effort, and I'm not sure it would be worthwhile. > OK, that would be perfectly livable. But the following > would be even better (although I don't expect it to be well > received). > > I would like to be able to write:: > > reference HTML format > [t:Isaac2005,p.121] -> Isaac (2005,p.121) > [p:Isaac2005,p.121] -> (Isaac 2005,p.121) > > and have the two citation references both point to > > .. [Isaac2005] The citation text. Now we're getting into the realm of parameterized interpreted text: http://docutils.sf.net/docs/dev/rst/alternatives.html#parameterized-interpreted-text This is an unresolved area. Don't hold your breath ;-) > This of course requires some conventions: > > - the single alphabetic modifier before a colon What do the "p" & "t" signify? > - concluding digits specify a date > - a comma separates off supplementary citation information IOW, text after the comma isn't significant? It isn't functional, but just for show? -- David Goodger <http://python.net/~goodger> |
From: Mikolaj M. <mi...@wp...> - 2005-10-04 08:07:34
|
David Goodger scripsit: > This is an OpenPGP/MIME signed message (RFC 2440 and 3156) > --------------enig5B165A33B422B32E4C1CBA43 > Content-Type: text/plain; charset=UTF-8 > Content-Transfer-Encoding: 7bit > > [Alan G Isaac] >> About the only time I really feel frustrated with reST is >> when I hit citations. I'm trying to find a way to be happy. >> Here is one idea. >> >> 1. Do not restrict the character set quite so much for >> reference names. In particular, allow isolated hyphens, >> parentheses, colons, and nonbreaking space. >> I do not use plusses (+) in my keys but a lot of people >> do: allowing this is therefore also a good idea. This would make citations hardly recognizable from other content. > >> - concluding digits specify a date >> - a comma separates off supplementary citation information > > IOW, text after the comma isn't significant? It isn't functional, but > just for show? > Rather: after comma is additional bibliographic information which is important only in context of current place of document (number of page), but has no influence on citation citation description. That would be handy but I usually see such info in compact way [Isaac2005:121]. m. -- LaTeX + Vim = http://vim-latex.sourceforge.net/ Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078 vim.pl - http://skawina.eu.org/mikolaj CLEWN - http://clewn.sf.net |
From: Alan G I. <ai...@am...> - 2005-10-04 13:12:50
|
>Alan wrote: >> 1. Do not restrict the character set quite so much for=20 >> reference names. In particular, allow isolated hyphens,=20 On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > Isolated internal hyphens, underscores, and periods are=20 > already allowed. Right. Sorry that crept into the list. The additions=20 requested are isolated parentheses, colons, and nonbreaking=20 space. And perhaps plusses. >Alan wrote: >> 2. Allow suppressing the brackets on the inline reference=20 >> names.=20 On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > You mean for the output?=20 Yes. Like with footnotes. On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > What do you mean by "end-of-line citation references"? =20 I mean what the Chicago Manual of Style calls an In-Text style. In my field (economics), we might say: Goodger=C2=A0(2005) asserts ... (^ within-sentence style) Or we might say: Experts assert it (Goodger 2005). (end-of-sentence style ^) On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > What is the standard you're using? Do you have a reference URL?=20 The end-of-sentence style is a standard Chicago style: http://library.osu.edu/sites/guides/chicagogd.html The within-sentence style is also quite standard, and=20 I think it too is a Chicago style, but I cannot find a URL. >Alan wrote: >> I would like to be able to write::=20 >> reference HTML format=20 >> [t:Isaac2005,p.121] -> Isaac (2005,p.121)=20 >> [p:Isaac2005,p.121] -> (Isaac 2005,p.121)=20 >> and have the two citation references both point to=20 >> .. [Isaac2005] The citation text.=20 On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > Now we're getting into the realm of parameterized interpreted text:=20 > http://docutils.sf.net/docs/dev/rst/alternatives.html#parameterized-inter= preted-text=20 > This is an unresolved area. Don't hold your breath ;-)=20 OK. =20 On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > What do the "p" & "t" signify?=20 Cite as *t*ext; cite in *p*arentheses. Taken from the natbib standard: \citep and \citet. >Alan wrote: >> - concluding digits specify a date=20 >> - a comma separates off supplementary citation information=20 On Mon, 03 Oct 2005, David Goodger apparently wrote:=20 > IOW, text after the comma isn't significant? It isn't functional, but=20 > just for show?=20 Well the is is not linkable, but it is informative. Usually it is a specific page reference, as opposed to the page range given in the citation text. This is in very wide use: see the Chicago Manual of Style http://library.osu.edu/sites/guides/chicagogd.html Thnaks for your other suggestions. I'll try them out. Cheers, Alan=20=0D |
From: Mikolaj M. <mi...@wp...> - 2005-10-04 20:18:39
|
Alan G Isaac scripsit: > > The end-of-sentence style is a standard Chicago style: > http://library.osu.edu/sites/guides/chicagogd.html I checked this site and I think what you and/or reST really need is something like bibtex. Allow for compact inserting of citations in text and by some extension expand it to full, chosen form. m. -- LaTeX + Vim = http://vim-latex.sourceforge.net/ Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078 vim.pl - http://skawina.eu.org/mikolaj CLEWN - http://clewn.sf.net |
From: Alan G I. <ai...@am...> - 2005-10-05 20:35:52
|
> Alan G Isaac scripsit: >> The end-of-sentence style is a standard Chicago style: >> http://library.osu.edu/sites/guides/chicagogd.html On Tue, 4 Oct 2005, Mikolaj Machowski apparently wrote: > I checked this site and I think what you and/or reST really need is > something like bibtex. Allow for compact inserting of citations in text > and by some extension expand it to full, chosen form. Yes indeed, but I cannot write it and it is not a docutils priority. So in the meantime I use reST citations along with bibstuff, which processes the reST citation references using my .bib file. Crude, but much better than nothing. Cheers, Alan Isaac |
From: Alan G I. <ai...@am...> - 2005-10-04 13:12:52
|
OK, I could get pretty far with the proposed workarounds if I could have one thing: indirect link via a citation reference. E.g., `Goodger (2005)` is helpful. .. _Goodger (2005): [goodger2005]_ .. [goodger2005] citation text Why this is needed: well, bibstuff looks for a citation *reference*. OK, so that's not the perfect motivation perhaps, but on a more general plane, is there any reason why docutils should dislike this? (It seems pretty natural; more natural than treating goodger2005 as a filename, which is the current action.) Cheers, Alan Isaac |
From: Alan G I. <ai...@am...> - 2005-10-05 20:35:57
|
OK, I've tried out all the suggestions, and learned a fair amount about the citation possibilities in reST. I think. In the end I am persuaded that reST is going to need a change in order to handle citations nicely. I am just a user, so I am going to propose a change at the user's level. I believe reST needs to distinguish between the cite-text and the cite-key, a distinction that is not currently drawn. Citation references should use the cite-key, but the transformed document should use the cite-text (with cite-key as fallback). I believe backward compatibility is possible with this change. Here is how it might look in the text document: [mycitekey] .. [mycitekey] :label: MyCiteLabel The complete citation as usual. The specifics are not that important at the user level, but this would look very natural I think. The important things are 1. allow people to use the cite-keys defined in their bibliography files, so that the bibliography can be automatically generated (with external tools for now) 2. do not presume that the citation reference in the reST text should appear in the transformed document. Rather, allow substitution by specified text. fwiw, Alan Isaac |
From: David G. <go...@py...> - 2006-06-30 03:25:21
Attachments:
signature.asc
|
[Here's the earlier discussion, from October 2005. Following up on it has been in my personal to-do list for some time. Sorry for the delay.] [Alan G Isaac] >>> 1. Do not restrict the character set quite so much for >>> reference names. In particular, allow isolated hyphens, [David Goodger] >> Isolated internal hyphens, underscores, and periods are >> already allowed. [Alan G Isaac] > Right. Sorry that crept into the list. The additions > requested are isolated parentheses, colons, and nonbreaking > space. And perhaps plusses. This would complicate things too much. We already have a mechanism for arbitrary references though, which could be applied to citations also. Read on. >>> 2. Allow suppressing the brackets on the inline reference >>> names. > >> You mean for the output? > > Yes. Like with footnotes. That could be done. How should this alternative rendering be formatted, to distinguish citations from surrounding text? > OK, I've tried out all the suggestions, and learned a fair > amount about the citation possibilities in reST. I think. > > In the end I am persuaded that reST is going to need > a change in order to handle citations nicely. I am just > a user, so I am going to propose a change at the user's > level. > > I believe reST needs to distinguish between the cite-text > and the cite-key, a distinction that is not currently drawn. > Citation references should use the cite-key, but the > transformed document should use the cite-text (with cite-key > as fallback). I believe backward compatibility is possible > with this change. It looks like the downtime has paid dividends: I think I have an answer. My first idea was to treat arbitrary-text citation references as ordinary hyperlink references: `[arbitrary citation text]`__ __ citation_ Or, if you don't want brackets, `arbitrary citation text`__ __ citation_ The citation itself must still conform to the current rules: .. [citation] text here This works with Docutils now, as-is. There are some problems though: 1. The citations will not contain the arbitrary text, but only the simple reference names. 2. Citation references would actually be simple hyperlink references, and wouldn't be treated specially. For example, they wouldn't be part of a collected list of citation references, nor could you apply special formatting to them. These deficiencies led me to apply the notion of phrase references to citations. IOW, citations could be generalized like hyperlink references: [`arbitrary citation name`]_ .. [arbitrary citation name] text here But that's as far as I'm willing to go at this point. We're not going to support the advanced/complex constructs that have been described: no optional parts of citations (like page references) or parameterizations (like t/p text/parentheses or within-sentence/end-of-sentence codes) or multiplex citations. reST is a minimal implicit markup, and such complex constructs are too explicit for comfort. They could be simulated with indirect phrase citation references though, something like this: [`complex variant, p. 123`]_ .. _complex variant, p. 123: `base citation`_ .. [base citation] citation text here However, there's no reason that advanced constructs couldn't be supported via explicit markup -- a directive. I won't be implementing it any time soon though. --=20 David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-03 13:07:22
|
> On Sun, 2 Jul 2006, Alan G Isaac wrote:=20 >> Goal: allow documents to change inline citation=20 >> formatting at a single location.=20 On Mon, 3 Jul 2006, (CEST) gr...@us...=20 apparently wrote:=20 > whatfore is this needed ? =20 > in my understanding the different formats are required, because submitted= =20 > papers had to follow certian style guides. but you dont submit reST=20 > documents, dont you ?=20 > in latex one does not change the format when writing a document, this is= =20 > done at publishing time.=20 > having citations formatted in several styles in reST does not sound like= =20 > easing things ?=20 Issues of style arise whenever you start to share your work=20 in different forums. Submission for publication is a clear=20 example, as you said, but it is only one example. The=20 general goal is a clear need for writers who use citations. However I think you misunderstood: I am not proposing that reST use style sheets or something complicated like that. I am asking only that=20 citations support substitution. David has said this is=20 feasible (although he has not yet smiled on the idea). Cheers, Alan Isaac |
From: Mikolaj M. <mi...@wp...> - 2006-07-03 18:58:44
|
Alan G Isaac scripsit: > The citation needs of rst2latex users are much simpler to > meet: they just need [mycitekey]_ to be turned into > \cite{mycitekey} in the LaTeX document along with the > ability to specificify .bib files and a .bst file in their > config file. So while some rst2latex users may find the > citation-substitution feature I have requested to be useful > (especially those new to LaTeX), most would probably prefer > to rely on support for existing LaTeX tools. Yes, this is the simplest solution but leave HTML users with empty hands. m. -- LaTeX + Vim = http://vim-latex.sourceforge.net/ Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078 vim.pl - http://skawina.eu.org/mikolaj CLEWN - http://clewn.sf.net |
From: Alan G I. <ai...@am...> - 2006-06-30 23:24:05
|
OK, I am pretty sure I misconstrued something, so I am going to propose something like what I thought was being offered. Here is my reference to [Goodger2006], which I want substituted. .. [Goodger2006] inline:: (Goodger 2006) Above is the inline-substitution text, while here is the actual citation. Disregarding the possibly noxious syntax, is the basic idea possible to consider? This would be quite huge: it would mean that formatting of inline citations could be=20 changed at a single location for each key. Cheers, Alan Isaac |
From: David G. <go...@py...> - 2006-07-02 15:29:01
Attachments:
signature.asc
|
[Alan G Isaac] > OK, I am pretty sure I misconstrued something, > so I am going to propose something like > what I thought was being offered. Thanks for the clarification! > Here is my reference to [Goodger2006], > which I want substituted. > > .. [Goodger2006] inline:: (Goodger 2006) > Above is the inline-substitution text, while here > is the actual citation. > > Disregarding the possibly noxious syntax, > is the basic idea possible to consider? Theoretically possible, but unnecessarily complex & not worth the effort IMO. You will be able to do the same thing with this: Here is my reference to [`(Goodger 2006)`]_, which I want substituted. .. _(Goodger 2006): Goodger2006_ .. [Goodger2006] Above is the inline-substitution text, while here is the actual citation. I prefer this because: * it is more WYSIWYG: the citation appears in the input the same as it will in the output; * it uses an existing mechanism (indirect references); * it avoids mixing orthogonal features (substitutions & citations); * your proposal doesn't address the real issue (parameterized, dynamic, database-backed bibliographies), and reST won't either. > This would be quite huge: > it would mean that formatting of inline citations could be > changed at a single location for each key. I don't see this as a plus. reST already has a mechanism for that, substitutions: Here is my reference to |Goodger 2006|, which I want substituted. .. |Goodger 2006| replace:: [`(Goodger 2006)`]_ .. _(Goodger 2006): Goodger2006_ .. [Goodger2006] Above is the inline-substitution text, while here is the actual citation. (This may not work right now due to a known bug.) --=20 David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2006-07-02 16:15:20
|
Goal: allow documents to change inline citation formatting at a single location. Option 1: currently not possible:: Here is my reference to [Goodger2006]_, which I want substituted.=20 .. [Goodger2006] replace:: (Goodger 2006) Above is the inline-substitution text, while here is the actual citation. Option 2: currently possibly possible (excepting a bug):: Here is my reference to |Goodger 2006|, which I want substituted. .. |Goodger 2006| replace:: [`(Goodger 2006)`]_ .. _(Goodger 2006): Goodger2006_ .. [Goodger2006] Above is the inline-substitution text, while here is the actual citation. Why option 1 is better: - Just look at it. It is much clearer and much easier to understand. - A citation looks like a citation. This is a good thing. > your proposal doesn't address the real issue=20 > (parameterized, dynamic, database-backed bibliographies),=20 > and reST won't either.=20 There is more than one "real issue". Preprocessing (e.g., with Bibstuff) can handle the database issues, and this will be much easier with option 1. Specifically, with option 1 a simple preprocessor can easily provide the formatting for the inline-citation-substitution-text, while with option 2 this will be very hard to achieve. I hope you will seriously consider implementing option 1, which seems a very natural and achievable improvement of citation handling in reST. Cheers, Alan Isaac |
From: <gr...@us...> - 2006-07-03 07:56:14
|
On Sun, 2 Jul 2006, Alan G Isaac wrote: > Goal: allow documents to change inline citation > formatting at a single location. whatfore is this needed ? in my understanding the different formats are required, because submitted papers had to follow certian style guides. but you dont submit reST documents, dont you ? in latex one does not change the format when writing a document, this is done at publishing time. having citations formatted in several styles in reST does not sound like easing things ? or am i totally wrong ? -- |
From: G. M. <g....@we...> - 2006-07-03 09:52:10
|
On 3.07.06, gr...@us... wrote: > On Sun, 2 Jul 2006, Alan G Isaac wrote: > > > Goal: allow documents to change inline citation > > formatting at a single location. > > whatfore is this needed ? > > in my understanding the different formats are required, because submitted > papers had to follow certian style guides. but you dont submit reST > documents, dont you ? I would export the reST document and submit a pdf or latex file (whatever is expected). > in latex one does not change the format when writing a document, this is > done at publishing time. More and more publishers expect "camera ready" documents (especially for conference proceedings and the like). They normally accept pdf or ps files and provide instructions on how to produce them. The "good ones" provide a LaTeX stylesheet and a BibTeX style so it is easy to typeset the document according to the specifications from a latex source. Together with the rst2latex writer this would allow to write publications in reST. (Actually, for me, to make use of this way the math support of reST would need more work as well.) > having citations formatted in several styles in reST does not sound like > easing things ? I suppose the formatting of citations could be left to the same add-on tool that creates the citation list from the bibliography database based on the "cite-keys". This could be either a wrapper around BibTeX, something like the citation database in OpenOffice or some new implementation. BTW: For the work with bibliographic databases under Python, there exists already a tool "pybliogapher" that could be uses as the base for a reST citation add-on. The home page http://pybliographer.org/ says: Pybliographer is a tool for managing bibliographic databases. It can be used for searching, editing, reformatting, etc. In fact, it's a simple framework that provides easy to use python classes and functions, and therefore can be extended to many uses (generating HTML pages according to bibliographic searches, etc). Günter |
From: Alan G I. <ai...@am...> - 2006-07-03 13:23:34
|
On Mon, 3 Jul 2006, "G. Milde" apparently wrote:=20 > More and more publishers expect "camera ready" documents=20 > (especially for conference proceedings and the like). They=20 > normally accept pdf or ps files and provide instructions=20 > on how to produce them. The "good ones" provide a LaTeX=20 > stylesheet and a BibTeX style so it is easy to typeset the=20 > document according to the specifications from a latex=20 > source.=20 The citation needs of rst2latex users are much simpler to=20 meet: they just need [mycitekey]_ to be turned into=20 \cite{mycitekey} in the LaTeX document along with the=20 ability to specificify .bib files and a .bst file in their=20 config file. So while some rst2latex users may find the=20 citation-substitution feature I have requested to be useful (especially those new to LaTeX), most would probably prefer=20 to rely on support for existing LaTeX tools. > I suppose the formatting of citations could be left to the=20 > same add-on tool that creates the citation list from the=20 > bibliography database based on the "cite-keys". This could=20 > be either a wrapper around BibTeX, something like the=20 > citation database in OpenOffice or some new=20 > implementation.=20 I think the important thing for reST, given that it will not=20 implement its own access to bibliographic databases, is to=20 make it easy to preprocess documents. Right now the only=20 way I see to make this easy is to enhance citations to=20 support substitution. (See my posted example.) Cheers, Alan Isaac |
From: Alan G I. <ai...@am...> - 2006-07-03 13:29:25
|
On Mon, 3 Jul 2006, Alan G Isaac apparently wrote:=20 > The citation needs of rst2latex users are much simpler to=20 > meet: they just need [mycitekey]_ to be turned into=20 > \cite{mycitekey} in the LaTeX document=20 I should add that this statement is wrong in the following=20 way: parameterized citations are what is really wanted. But these have (reasonably) been ruled out for reST. Cheers, Alan Isaac |
From: Phil S. <ps...@uc...> - 2006-07-03 16:38:07
|
On Jun 30, 2006, at 6:31 PM, Alan G Isaac wrote: > Here is my reference to [Goodger2006], which I want substituted. > > .. [Goodger2006] inline:: (Goodger 2006) > Above is the inline-substitution text, while here > is the actual citation. I'm afraid I don't understand the objective here, and I certainly can't see why you would want to mix formatting with content when reST/ docutils does such a nice job of separating the two. Suppose you've decided to submit to a journal that requires citations in the form (Goodger, 2006) instead of (Goodger 2006). You're not suggesting that one would go back and insert commas in the original reST document, are you? IMHO, there are three main issues WRT citations/references when writing an academic paper in reST. The first is how to get the references out of your bibliographic database (e.g., a BibTeX file) and into a location (and format) where docutils can use them. IOW, it's just as easy to write [Goodger2006]_ as it is to write \cite {Goodger2006}, where Goodger2006 is a key corresponding to a reference in your BibTeX file. However, you don't want to retype the target (i.e., the complete reference) each time you want to use it in a reST document. There are several ways one might attack this problem (each with its advantages and disadvantages), but the important point is that by itself, it is a distinct (albeit important) issue. A second issue concerns how much control over bibliographic formatting you need/want across all output formats -- IOW, what should be built in to docutils itself. In other words, suppose I'm writing a paper, and I intend to submit it to a journal which uses the citation format (Goodger 2006). Now, if I also want to generate a copy of the paper in HTML (say, to put it on my web site), do I really need to have (Goodger 2006) in the output instead of [Goodger2006]? In my case, I don't; I personally don't care if the citation format in the HTML version is not exactly like that in the published version. However, this is what you seem to be trying to accomplish above. The problem with your approach, of course, comes when you decide that you want to have (Goodger, 2006) (or something else) instead; you have to change every reference in your reST document. Finally, assuming you want to submit a LaTeX file to a journal (or its corresponding pdflatex output), you need to translate the citations and references into LaTeX format. rst2latex.py (with the -- use-latex-citations option) already gets you most of the way there; if, that is, the corresponding target (i.e., full reference) in your reST document is in the same format you would use for a \bibitem{} entry in your LaTeX file. Of course there are a few outstanding issues here. For example, I'm not sure it's possible currently to handle multiple citations at a single point in the text (e.g., as in \cite{Goodger2005, Goodger2006}), or some of the other things you sometimes need to do with citations (e.g., as in (see Goodger 2006, chap. 1)). Moreover, it's quite likely that the exact content of the reference you want to use in LaTeX will not be the same content you'd want to have placed in an HTML file (e.g., you might want "Vol.\ A-- E" in the LaTeX version but not elsewhere). Again, there are various ways you might imagine getting around this, however each has both advantages and disadvantages. reST/docutils is not a complete typsetting system, and if I understand David correctly, he has no interest in trying to make it into one. However, I for one believe that reST/docutils has tremendous potential in the academic research context. It is easier to learn than LaTeX, thus making it possible to collaborate with non- LaTeX users. Moreover, it enforces one of the primary arguments for using LaTeX (as opposed to a word processor) in the extreme; when writing, one should concentrate on content and not waste time diddling around with formatting. Clearly, there are some issues RE citations/references that have to be worked out to make it easy for someone to write an academic paper in reST. However, let's begin with a discussion of exactly what the objectives are and/or should be before getting in to the details of implementation. -- Phil |
From: Alan G I. <ai...@am...> - 2006-07-03 17:30:23
|
> On Jun 30, 2006, at 6:31 PM, Alan G Isaac wrote roughly: >> Here is my reference to [Goodger2006]_, which I want=20 >> substituted. >> .. [Goodger2006] replace:: (Goodger 2006) >> Above is the inline-substitution text, while here=20 >> is the actual citation.=20 On Mon, 3 Jul 2006, Phil Schumm apparently wrote:=20 > I'm afraid I don't understand the objective here Really?? Perhaps you have a LaTeX bias, which leads you to=20 think the objective can be met by using LaTeX. > I certainly can't see why you would want to mix formatting=20 > with content when reST/ docutils does such a nice job of=20 > separating the two. So you would oppose for example the tables (especially grid=20 tables) or manual footnote numbers or the substitution=20 defintions already allowed by reST??? (The last of course=20 is the relevant one here.) In fact, relative to the workarounds that David has=20 proposed, you should see my request as helping to maintain=20 the formatting/content separation. (See the previous posts=20 on this thread.) > Suppose you've decided to submit to a journal that=20 > requires citations in the form (Goodger, 2006) instead of=20 > (Goodger 2006). You're not suggesting that one would go=20 > back and insert commas in the original reST document, are=20 > you? Yes: with a preprocessor. But to understand how, you have to follow the thread. Nothing is changed in the reST document body text. See the example at the top of this post. The rest of your note seems to assume that only LaTeX is=20 relevant to publication or other formatted document sharing. This is simply not true. > Now, if I also want to generate a copy of the paper in=20 > HTML (say, to put it on my web site), do I really need to=20 > have (Goodger 2006) in the output instead of=20 > [Goodger2006]? In my case, I don't Others face different cases. Why be dismissive? Also note that David already recognized this by allowing that some formatting could be useful (e.g., omitting the brackets). > The problem with your approach, of course, comes when you=20 > decide that you want to have (Goodger, 2006) (or something=20 > else) instead; you have to change every reference in your=20 > reST document.=20 No. You do not change every citation reference. That is the whole point: no matter how many times a given key occurs as a citation reference, under my proposal you will only have to make the change in a single place (for that key). So in the example at the top of this post, no matter how many times [Goodger2006]_ occurs in the text, there is only a single place that requires a change. And again, handled by a preprocessor. (Specifically, Bibstuff plus some extensions.) This is all irrelevant to reST **except** that I am asking reST to make it easy. To make it easy, we need to be able to replace the citation reference with replacement-citation-text. The replacement text can be generated by a preprocessor (or by hand for small documents). I am just asking for substitution to be allowed. > reST/docutils is not a complete typsetting system Nobody is asking it to be. > Clearly, there are some issues RE citations/references=20 > that have to be worked out to make it easy for someone to=20 > write an academic paper in reST. Yes, and there should be no presumption that rst2latex will=20 be used to do this. > However, let's begin with a discussion of exactly what the=20 > objectives are and/or should be before getting in to the=20 > details of implementation.=20 I feel I stated one objective pretty clearly. I need citations references, I need to preprocess them to get a bibliography, and I need to substitute formatted text for the citation references. The first two are in place. I am asking reST to make it easy to do the last of these by =20 allowing substitution of replacement-citation-text for=20 citation references. David has already suggested such=20 substitution is feasible, and I am saying it can meet this=20 need. My previous posts discuss this in more detail. Cheers, Alan Isaac |
From: Phil S. <ps...@uc...> - 2006-07-03 19:21:34
|
On Jul 3, 2006, at 12:38 PM, Alan G Isaac wrote: > Really?? Perhaps you have a LaTeX bias, which leads you to think > the objective can be met by using LaTeX. I wouldn't call it a bias, but I think most would agree that it is possible to write a paper for publication in LaTeX, and that there are very few things you can't accomplish in that context. The question is whether, for a subset of use cases, it is possible to use reST instead as a way of (1) simplifying things and thus fostering collaboration with non-LaTeX users, and (2) creating a source document that is more versatile than a file containing LaTeX markup. >> I certainly can't see why you would want to mix formatting with >> content when reST/ docutils does such a nice job of separating the >> two. > > So you would oppose for example the tables (especially grid tables) > or manual footnote numbers or the substitution defintions already > allowed by reST??? (The last of course is the relevant one here.) Not at all. The "formatting" involved in creating a table in reST (even a grid table) is all content: which row(s) comprise the header, which cells should be spanned, etc. are all content. Manual footnote numbers may be near the border, depending on why they are being used (i.e., to try and accomplish a content objective or a formatting objective). And substitution definitions frequently involve content (e.g., substituting an em dash for |---|). >> Suppose you've decided to submit to a journal that requires >> citations in the form (Goodger, 2006) instead of (Goodger 2006). >> You're not suggesting that one would go back and insert commas in >> the original reST document, are you? > > Yes: with a preprocessor. But to understand how, you have to > follow the thread. Nothing is changed in the reST document body text. Well, either you do modify the reST document before it is processed by docutils, or you add something to docutils itself. In either case, this issue -- creating citation styles according to a specific format -- is already handled nicely by LaTeX. The only reason I can see for not making use of that is if you want to do that same thing with HTML output, say. That's fine if you do; I was simply asking for clarification as to why you want to do this within docutils. >> Now, if I also want to generate a copy of the paper in HTML (say, >> to put it on my web site), do I really need to have (Goodger 2006) >> in the output instead of [Goodger2006]? In my case, I don't > > Others face different cases. Why be dismissive? Also note that > David already recognized this by allowing that some formatting > could be useful (e.g., omitting the brackets). That was exactly my point. I was hoping to nudge others to describe specific use cases involving citations that may well be different from my own. No value judgement there. >> The problem with your approach, of course, comes when you decide >> that you want to have (Goodger, 2006) (or something else) instead; >> you have to change every reference in your reST document. > > No. You do not change every citation reference. That is the whole > point: no matter how many times a given key occurs as a citation > reference, under my proposal you will only have to make the change > in a single place (for that key). So in the example at the top of > this post, no matter how many times [Goodger2006]_ occurs in the > text, there is only a single place that requires a change. Part of the problem with this thread has been a confusion with terminology, I think. For better or for worse, I was using the term citation to refer to what is placed in the text (e.g., (Goodger 2006)) and the term reference to refer to what appears in the list of references. So, if you have citations to 10 different references in your text, then you need to change each of the 10 references. Obviously, if you intend to do this programmatically, then the total number of changes you need to make is not a problem. >> Clearly, there are some issues RE citations/references that have >> to be worked out to make it easy for someone to write an academic >> paper in reST. > > Yes, and there should be no presumption that rst2latex will be used > to do this. Agreed. >> However, let's begin with a discussion of exactly what the >> objectives are and/or should be before getting in to the details >> of implementation. > > I feel I stated one objective pretty clearly. I need citations > references, I need to preprocess them to get a bibliography, and I > need to substitute formatted text for the citation references. The > first two are in place. I am asking reST to make it easy to do the > last of these by allowing substitution of replacement-citation-text > for citation references. David has already suggested such > substitution is feasible, and I am saying it can meet this need. > My previous posts discuss this in more detail. What I was asking for was clarification on *why* you want to do this. If you go the LaTeX route (e.g., rst2latex.py with --use-latex- citations), then all you need to do is to specify an appropriate style file when you typeset the document, and you get what you describe for free. Thus, it must be that you are interested in other output formats, correct? 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. What I was trying to say before was that I don't yet have a clear enough idea of what you are trying to do (or why you are trying to do it). I'm interested, because if it's similar to some of the issues I (or others) are facing, we may be able to work together to develop a solution. -- Phil |
From: Stuart R. <st...@za...> - 2006-07-03 22:20:41
|
I agree that we have some issues of terminology to sort out. One of the main problems is that the term 'citation' is used to refer to different things. I would suggest that we use the following terms to prevent confusion: CITATION KEY : the key used to refer to a reference IN-TEXT CITATION : the reference to a citation key in a document FORMATTED CITATION : the citation as it appears in the final version of the document For example, let's say I have a .bib file with only a single reference in it. Here's an actual reference form one of my own .bib files: @BOOK{mcmahon:2006, author = {April McMahon AND Robert McMahon}, year = {2006}, title = {Language Classification by Numbers}, publisher = {Oxford University Press}, address = {Oxford} } Now, let's say I have a reST file that cites this reference: This reST document contains a citation [mcmahon:2006]_. [mcmahon:2006]_ is about computational techniques for language classification. We could say that this document has two in-text citations of a book whose citation key is 'mcmahon:2006'. Once it is processed, the in-text citation will be converted into formatted citations. > Part of the problem with this thread has been a confusion with > terminology, I think. For better or for worse, I was using the term > citation to refer to what is placed in the text (e.g., (Goodger > 2006)) and the term reference to refer to what appears in the list of > references. So, if you have citations to 10 different references in > your text, then you need to change each of the 10 references. > Obviously, if you intend to do this programmatically, then the total > number of changes you need to make is not a problem. +----------------------------------------+ | Stuart Robinson | | Email: st...@za... | | Homepage: http://www.zapata.org/stuart | +----------------------------------------+ |
From: Stuart R. <st...@za...> - 2006-07-03 23:25:40
|
I created a web page with links to various version of a sample reST document I created for citation testing purposes: http://www.zapata.org/stuart/docutils/ Perhaps if we use the same terminology and refer to the same document, there will be fewer misunderstanding and we can make progress more rapidly. If you haven't used LaTeX or BibTeX before, you might find a comparison of sample-lc.tex and sample-lc-bib.tex useful. The second is basically the same as the first, except that I added some hand-coding to get automatic bibliography creation to work. You can see the difference with a quick diff: $ diff sample-lc.tex sample-lc-bib.tex 16a17,18 > \usepackage{natbib} > \bibpunct{(}{)}{;}{a}{,}{,} 71c73,76 < This is a test file. It cites two books {[}goossens:1994,lutz:2003{]}{\_}. {[}goossens:1994{]}{\_} is a handy guide to LaTeX. {[}lutz:2003{]}{\_} is an introduction to the programming language Python. --- > This is a test file. It cites two books \citep{goossens:1994,lutz:2003}. \cite{goossens:1994} is a handy guide to LaTeX. \cite{lutz:2003} is an introduction to the programming language Python. > > \bibliography{references} > \bibliographystyle{apalike} Hope this helps. +----------------------------------------+ | Stuart Robinson | | Email: st...@za... | | Homepage: http://www.zapata.org/stuart | +----------------------------------------+ |
From: David G. <go...@py...> - 2006-07-04 01:13:42
Attachments:
signature.asc
|
[Stuart Robinson] > I agree that we have some issues of terminology to sort out. One of the= > main problems is that the term 'citation' is used to refer to different= > things. I would suggest that we use the following terms to prevent > confusion: >=20 > CITATION KEY : the key used to refer to a reference > IN-TEXT CITATION : the reference to a citation key in a document > FORMATTED CITATION : the citation as it appears in the final version of= =20 > the document I agree that the terminology used so far is confusing, but I wouldn't use= these particular terms; IMO they exacerbate the confusion. We already have per= fectly good terminology for most of what we need, as used in the reST markup spe= c (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html). Pl= ease use them: "Citation reference": such as [Doe2006]_, occurs in text. "Citation": .. [Doe2006] This is the citation: it's the construct that contains the details of the work being cited. Both of these have a "citation name", which links them ("Doe2006" above).= This is the equivalent of the "citation key", although that term should be use= d when referring to a bibliographic database key. In addition to these, we have: "output citation reference" or "display ci= tation reference" or "formatted citation reference" for the citation reference a= s seen in the final output; and "citation reference substitution" or "citation n= ame substitution" for the proposed text to replace the standard citation name= =2E --=20 David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2006-07-04 01:28:22
Attachments:
signature.asc
|
[David Goodger] > Both of these have a "citation name", which links them ("Doe2006" above= ). This > is the equivalent of the "citation key", although that term should be u= sed when > referring to a bibliographic database key. Actually, the term used in the markup spec is "citation label", which is = better than the above. So we have "citation label"; "output citation label" or "display citation label" or "formatted citation label"; and "citation lab= el substitution". --=20 David Goodger <http://python.net/~goodger> |