From: Matt D. <mat...@ya...> - 2007-02-19 17:14:09
|
Back in July, Alan Isaac posted an extensive `Proposal for Citation Handling`_ .. _Proposal for Citation Handling: http://permalink.gmane.org/gmane.text.docutils.user/3120 As far as I can tell from browsing the archives, there was some substantive discussion preceding that proposal, but very little afterward. Can anyone comment about the status? I'm one of those users who hopes to be able to compose a (social sciences) thesis using reST, and am willing to contribute some programming time (using my intermediate-level Python chops) to move this along if there's consensus on how it should be implemented. In the meantime, can any reST/LaTeX/BibTeX users comment on how they're working around reST's limited citation support? Thanks, Matt |
From: Alan G I. <ai...@am...> - 2007-02-19 21:57:48
|
On Mon, 19 Feb 2007, Matt Dorn apparently wrote: > http://permalink.gmane.org/gmane.text.docutils.user/3120 > Can anyone comment about the status? That status as I understand: the developers have other priorities and limited time. However they also have a stated intent to soon allow more characters in citation references, which is one important change. Currently you cannot use ``+`` or ``:``, which are in many databases. > In the meantime, can any reST/LaTeX/BibTeX users comment > on how they're working around reST's limited citation > support? For HTML output, I use Bibstuff with pretty good results. http://code.google.com/p/bibstuff/ (Just use an include directive to include the citations output.) Since I go to PDF via LaTeX, I just use the LaTeX citations option along with a sed script to cut out the bibliography so that I can rely on my favored bibliography style and database. Clumsy, but it works well enough to use until reST evolves more support. Which reminds me, we should request this last bit from the developers, since it should be trivial. E.g., --use-bib-database=mydatabase1,mydatabase2 --use-bst-style=myfavoritestyle would produce \bibliographystyle{myfavoritestyle} \bibliography{mydatabase1,mydatabase2} instead of the usual bibliography. This would be very helpful! Cheers, Alan Isaac |
From: <gr...@us...> - 2007-02-20 08:07:13
|
On Mon, 19 Feb 2007, Alan G Isaac wrote: >> In the meantime, can any reST/LaTeX/BibTeX users comment >> on how they're working around reST's limited citation >> support? > > For HTML output, I use Bibstuff with pretty good results. > http://code.google.com/p/bibstuff/ > (Just use an include directive to include the citations output.) > Since I go to PDF via LaTeX, I just use the LaTeX citations > option along with a sed script to cut out the bibliography > so that I can rely on my favored bibliography style and > database. what does the sed script do exactly ? > Clumsy, but it works well enough to use until reST evolves > more support. > > Which reminds me, we should request this last bit from the > developers, since it should be trivial. E.g., > --use-bib-database=mydatabase1,mydatabase2 > --use-bst-style=myfavoritestyle > would produce > \bibliographystyle{myfavoritestyle} > \bibliography{mydatabase1,mydatabase2} > instead of the usual bibliography. This would be very helpful! wouldnt this be easy to put in your style file, i want to limit the number of options (we are roughly at 80 so one might argue everything is already lost) currently some people are testing \ref for the latex-writer, if possible i want to finish this first (and i only work on the writer) cheers -- |
From: Alan G I. <ai...@am...> - 2007-02-20 16:46:21
|
> On Mon, 19 Feb 2007, Alan G Isaac wrote: >> Which reminds me, we should request this last bit from >> the developers, since it should be trivial. E.g., >> --use-bib-database=mydatabase1,mydatabase2 >> --use-bst-style=myfavoritestyle >> would produce >> \bibliographystyle{myfavoritestyle} >> \bibliography{mydatabase1,mydatabase2} >> instead of the usual bibliography. This would be very >> helpful! On Tue, 20 Feb 2007, (CET) gr...@us... apparently wrote: > wouldnt this be easy to put in your style file The first would, but not the second, since it creates the bibliography. But I just realized that a single option suffices: since you always need one style and one or more databases to create you bibliography, the option could be:: --use-bibtex=myfavoritestyle,mydatabase1,mydatabase2 which would again output :: \bibliographystyle{myfavoritestyle} \bibliography{mydatabase1,mydatabase2} (And of course would *suppress* the current bibliography creation.) This would be very useful! Cheers, Alan Isaac |
From: Alan G I. <ai...@am...> - 2007-02-20 16:46:22
|
> On Mon, 19 Feb 2007, Alan G Isaac wrote: >> Since I go to PDF via LaTeX, I just use the LaTeX >> citations option along with a sed script to cut out the >> bibliography so that I can rely on my favored >> bibliography style and database. On Tue, 20 Feb 2007, (CET) gr...@us... apparently wrote: > what does the sed script do exactly ? I run the sed script on the .tex file written by rst2latex.py. It replaces the entire bibliography section with these two lines:: \bibliographystyle{myfavoritestyle} \bibliography{mydatabase1,mydatabase2} My general view is that when it is possible to rely on existing LaTeX tools, that is a good idea, and LaTeX bibliography and citation tools are really quite good. Cheers, Alan Isaac |
From: Matt D. <mat...@ya...> - 2007-02-20 14:10:18
|
Alan G Isaac <aisaac <at> american.edu> writes: > That status as I understand: > the developers have other priorities and limited time. OK, but was there consensus on which part(s) of the proposal would be implemented? If we could at least arrive to that point, other developers (like myself) who may have some spare time could step up and help out. > Since I go to PDF via LaTeX, I just use the LaTeX citations > option along with a sed script to cut out the bibliography > so that I can rely on my favored bibliography style and > database. Do you have a method for including page numbers in your citations as well? Or does your work not require it? I'm working on my own workaround, but am curious about how others might handle this. Thanks, Matt |
From: Alan G I. <ai...@am...> - 2007-02-20 16:46:21
|
On Tue, 20 Feb 2007, (UTC) Matt Dorn apparently wrote: > Do you have a method for including page numbers in your > citations as well? Or does your work not require it? I'm > working on my own workaround, but am curious about how > others might handle this. Yes I need it and currently cannot have it. I would like to look at what you are doing. I would also welcome additions to the citation proposal. Here is the problem for use, as I see it. David does not need academic citation handling, so reST provides only the most basic support, and he is unlikely to sink much energy into it. He may also doubt that academic paper writing is an intended application for reST, which could reinforce the problem. In this context, I am very grateful that he has acknowledged the need to extend the character set in citation references and plans to implement this. You take away one part of the problem if you are willing to do development work on citation support. At this point the question becomes "what will the main developers bless" rather than "what will the main developers implement". This suggests that we might try to turn the citation proposal into a proposal for real citation support and discover what parts are seen as truly incompatible with the reST vision. My personal view is that the capabilities in the LaTeX world of natbib provide an excellent if rather ambitious point of reference. The key question, I suggest, is whether citation references will be enhanced to support paramters and substitution, or whether we will somehow rely on the existing substitution mechanism. My user's view is that citation references should really be citation references. Therefore I would like to see a mechanism for including and extracting formatting information. For example, allow tags in citation references that determine the substituted text:: [you+me:2007:pubhere[tag1]]_ [you+me:2007:pubhere[tag2]]_ [you+me:2007:pubhere[p.17]]_ .. citation:: you+me:2007:pubhere :tag1: You and Me, 2007 :tag2: (You and Me, 2007) :p.17: You and Me (2007,p.17) You, M. and Y. Me, *Our Great Book*, Pub Here, Inc., 2007 This is just quick new thought by a user, and may be crazy/unacceptable. Cheers, Alan Isaac |
From: <gr...@us...> - 2007-02-21 15:02:42
|
On Tue, 20 Feb 2007, Alan G Isaac wrote: > On Tue, 20 Feb 2007, (UTC) Matt Dorn apparently wrote: >> Do you have a method for including page numbers in your >> citations as well? Or does your work not require it? I'm >> working on my own workaround, but am curious about how >> others might handle this. > > Yes I need it and currently cannot have it. > I would like to look at what you are doing. > I would also welcome additions to the citation proposal. > > Here is the problem for use, as I see it. > David does not need academic citation handling, > so reST provides only the most basic support, > and he is unlikely to sink much energy into it. > He may also doubt that academic paper writing > is an intended application for reST, > which could reinforce the problem. for me reST is a plain textfile document, and there are options to convert it into other representations. but it is complete in itself. this is also an argument against autonumbering, and it is one side of not a coin but a cube i guess. > In this context, I am very grateful that he has > acknowledged the need to extend the character set > in citation references and plans to implement this. > > You take away one part of the problem if you are willing > to do development work on citation support. At this > point the question becomes "what will the main developers > bless" rather than "what will the main developers > implement". This suggests that we might try to turn > the citation proposal into a proposal for real citation > support and discover what parts are seen as truly > incompatible with the reST vision. > > My personal view is that the capabilities in the LaTeX world > of natbib provide an excellent if rather ambitious point of > reference. > > The key question, I suggest, is whether citation references > will be enhanced to support paramters and substitution, or > whether we will somehow rely on the existing substitution > mechanism. My user's view is that citation references > should really be citation references. and what distinguishes a citation reference from other references ? > Therefore I would like to see a mechanism for including and extracting > formatting information. formatting options, whatfore ? this is not really plaintextdocument, isnt it ? from reST-document point. i would want a section "bibliography" that contains all citations and all their information, otherwise the reST-document is incomplete (this is contrary to bobtex i guess). and the writer does with it whats needed to get it in shape, for latex this might need to write a bibtex-database and applying the correct bibtex-formator please excuse my ignorance, i never used bibtex or citations, but i mangle the latex-writer and need to get some grip to it. cheers > For example, allow tags in citation > references that determine the substituted text:: > > [you+me:2007:pubhere[tag1]]_ > [you+me:2007:pubhere[tag2]]_ > [you+me:2007:pubhere[p.17]]_ > > .. citation:: you+me:2007:pubhere > :tag1: You and Me, 2007 > :tag2: (You and Me, 2007) > :p.17: You and Me (2007,p.17) > > You, M. and Y. Me, > *Our Great Book*, > Pub Here, Inc., 2007 > > This is just quick new thought by a user, and may be > crazy/unacceptable. |
From: Alan G I. <ai...@am...> - 2007-02-21 15:38:23
|
On Wed, 21 Feb 2007, (CET) gr...@us... apparently wrote: > formatting options, whatfore ? this is not really > plaintextdocument, isnt it ? Of **course** not. ;-) reST is *lightly* marked up, but that is still markup. The markup is used by the writers for formatting purposes. Formatting is already directly accommodated all over the place, even to the point of options to remove spaces. > from reST-document point. i would want a section "bibliography" that > contains all citations and all their information, > otherwise the reST-document is incomplete If you specify the database, the document is just as "complete" as when you use an ``include`` directive. But I think your comment is tangential to the core question: people are starting to write documents in reST that have substantial citation needs, so what support will the reST writers offer? Take my example of allowing tags in citation so that references that determine the substituted text:: [you+me:2007:pubhere[p.17]]_ .. citation:: you+me:2007:pubhere :p.17: You and Me (2007,p.17) You, M. and Y. Me, *Our Great Book*, Pub Here, Inc., 2007 This is a very natural way to specify a substitution to be used by the writers. It may well be the wrong solution, but I cannot see it as undermining an important reST philosophy. Good citation support is obviously hard. Otherwise reST would already have it. There is a demand for it. Cheers, Alan Isaac |
From: <gr...@us...> - 2007-02-21 17:10:22
|
On Wed, 21 Feb 2007, Alan G Isaac wrote: > But I think your comment is tangential to the core question: > people are starting to write documents in reST that > have substantial citation needs, so what support will the > reST writers offer? that is what i want to find out, what can i do and i have to understand why to have a chance to do it right. > Take my example of allowing tags in citation so that > references that determine the substituted text:: > > [you+me:2007:pubhere[p.17]]_ > > .. citation:: you+me:2007:pubhere > :p.17: You and Me (2007,p.17) > > You, M. and Y. Me, > *Our Great Book*, > Pub Here, Inc., 2007 > > This is a very natural way to specify a substitution to be > used by the writers. It may well be the wrong solution, but > I cannot see it as undermining an important reST philosophy. no me neither, but it might be the wrong solution. for example i am unsure if this is possible to transform this into something latex bibliography can live with. what i am not really fond of is all those puncutations:: [you+me:2007:pubhere[p.17]]_ has nearly as much punctuations than letters. and what should this become then in html and in latex (i dont think anyone cares about man-pages) > Good citation support is obviously hard. Otherwise reST > would already have it. There is a demand for it. cheers -- |
From: G. M. <mi...@us...> - 2007-02-22 10:03:40
|
On 21.02.07, gr...@us... wrote: > On Tue, 20 Feb 2007, Alan G Isaac wrote: > for me reST is a plain textfile document, and there are options to > convert it into other representations. but it is complete in itself. I suppose 'reST' in this context should refer to a text file in reStructured Text syntax. (For me, reStructured Text is a markup language.) While you can use reStructured Text (the language) and docutils this way, this pure formatting is just a subset of docutils capabilities (as you already stated). > This is also an argument against autonumbering, and it is one side of > not a coin but a cube i guess. This is the side when you want i.e. provide documentation for a project in plain text format (for use cases where no html or pdf viewer is available) but allow for a "better" representation in a rich environment. For the reading of rst documents on a linux console (or DOS box), explicit markup is fine (and real numbers instead of autonumbers are better). However, if you look at the textfile document as a "source" to work on, you will see the benefits for easier editing: The docutils writers can do things computers are good at to save you time and effort and reduce errors. Take autonumbering: The number is not guessed nor depends it on any information not present in the text source. In this way, the text source is "complete in itself". OTOH, inserting a new point to your list (or deleting one) is easier and less error prone with autonumbering. The same holds for scientific citations, where automatic insertion of the `citation reference target` from a database saves a lot of work. Maybe we could benefit from a rst2rst writer that transforms a valid rst source file to an equally valid rst text document for end-users (with "magic" parts made explicit). > and what distinguishes a citation reference from other references ? A scientific citation reference has to follow conventions that are quite strict and vary from publisher to publisher (or university to university, in the case of a thesis). The rules are targeted to hard-copy printout (i.e. less suited for html). There are rules for both, the `citation reference` ("outgoing link" in the text) and the `citation reference target` (entry in the "References" list). LaTeX/BibTeX has elaborated support for scientific citation that a 'convert' from LaTeX to docutils is hardly missing. (Both, missing math and citation support prevent me from using rst for my phd thesis.) > from reST-document point. i would want a section "bibliography" that > contains all citations and all their information, otherwise the > reST-document is incomplete As Alan pointed out: all the needed information is there (as pointer to the database). In this sense it is not "incomplete" but "not explicite". > and the writer does with it whats needed to get it in shape, > for latex this might need to write a bibtex-database and applying > the correct bibtex-formator When processing a LaTeX document with ``latex bibtex latex latex``, bibtex: 1. scans the LaTeX document for citation references (actually, a latex-produced auxiliary file) 2. Looks up the references in a BibTeX database (".bib file") 3. Formats the data according to a BibTeX style (".bst file") 4. Writes it to an auxiliary file While latex formats the citation key and includes the bibtex-produced references list as "References" section. The nice thing is that many publishers and universities have provided BibTeX style files, so that I * do not need to care about the details of their formating rules * can use a common literature citation database for publications in different journals or books. The questions are: * What of this process should be done by latex|bibtex and what by the docutils writer if transforming a rst document to LaTeX or PDF? * How proceed if the output format is not LaTeX (or derived from it)? Günter |
From: Alan G I. <ai...@am...> - 2007-02-22 15:39:20
|
On Thu, 22 Feb 2007, "G. Milde" apparently wrote:=20 > The questions are:=20 > * What of this process should be done by latex|bibtex and what by the=20 > docutils writer if transforming a rst document to LaTeX or PDF?=20 > * How proceed if the output format is not LaTeX (or derived from it)?=20 G=FCnter summarized many things nicely. I just want to add=20 three comments: - relying on BibTeX should always be optional (and is now in=20 SVN as an option!), so I think the first question above must change somewhat - for other output formats there is the possibility of=20 relying on functionality similar to that provided by=20 BibTeX. E.g., Bibstuff provides some of this=20 functionality for reST documents and produces an=20 includable list of reST citations from a .bib file. (For this=20 to be a real solution, more characters that are common in=20 .bib files must be allowed in citation references, but=20 David said this is coming.) - As G=FCnter points out, BibTeX also provides a formatted=20 substitution for the citation reference. This is a really=20 necessary citation functionality, and a core question=20 remains whether reST will provide a mechanism for=20 *citations* to achieve this (e.g., via a citation=20 directive with tags) or will force the use of workarounds. Cheers, Alan Isaac |