Re: pandoc/citeproc issues: multiple bibliographies, nocite, citeonly

[John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

+++ John MacFarlane [Nov 23 10 19:33 ]:
> +++ Nathan Gass [Nov 24 10 02:29 ]:
> > On 22.11.10 00:26, Tillmann Rendel wrote:
> > >John MacFarlane wrote:
> > >>There's a proposal at
> > >>
> > >>http://gitit.net/PandocCitationGrammar
> > >>
> > >>that would address (2-4) by requiring the user to put an explicit
> > >>
> > >><references />
> > >>
> > >>tag where the bibliography goes;[...]
> > >
> > >I like the idea of explicitly specifying where the bibliography goes. I
> > >don't like that syntax too much, however, because
> > >
> > >(a) it is HTML-focused, so it might look awkward in LaTeX-target
> > >markdown files with lots of literal LaTeX code
> > >
> > >(b) it looks like literal HTML, but is actually (pandoc extended)
> > >markdown, which might be confusing
> > 
> > I just wanted to add that I completely agree here. I find syntax
> > which looks like html, but actually is not pass-through html but
> > special markdown syntax confusing.
> > 
> > >
> > >
> > >I had a similar problem in my use of pandoc. I want to insert
> > >system-generated content, such as a table of contents, at a specific
> > >point in the document. So I decided to write a script which replaces a
> > >whole section (or subsection etc.) with system-generated content, based
> > >on the name of the section. So for example, the snippet:
> > >
> > >Table of Contents
> > >=================
> > >
> > >It doesn't matter what you write here
> > >
> > >Introduction
> > >============
> > >
> > >would get translated to something like:
> > >
> > >\tableofcontents
> > >\section{Introduction}
> > >
> > >I think this would work well for references, too.
> > >
> > >
> > >The main benefit is that one can use the input format's syntax for
> > >headings to specify "special sections" like table of contents or
> > >references. The input document therefore looks natural. (One could even
> > >have one's editor and pandoc automatically fill in the section content
> > >with a textual version of the system-generated data, for some kind of
> > >semi-WYSIWYG effect).
> > >
> > >The main drawback is that the name of the section is relevant, so this
> > >introduces a language dependency. For my scripts, I just have a
> > >command-line flag for the various special sections:
> > >
> > >"--toc=Table of Contents"
> > >
> > 
> > Other possibilities would be to add some label syntax, similar to
> > the \label{} of latex, to just recognize most or even all possible
> > headers for such a section, or use a special code block, which is at
> > least clearly markdown syntax. Actually, when I think about it, the
> > last one strikes me as a very good alternative. So instead of
> > 
> >     <reference>
> >     some config
> >     </reference>
> > 
> > we simply use
> > 
> >    ~~~~~~~~~~ {.reference}
> >    some config
> >    ~~~~~~~~~~
> 
> 
> I'm open to suggestions other than the HTMLish syntax.  But I don't
> think this is obviously better.  For one thing, it looks like a code
> block.  And we'd have to implement some mini-language inside the
> block to specify the includes, excludes, source, etc.  If we use
> XML, we're using something that's already familiar.
> 
> One possibility would be a special attribute on a header:
> 
> # Works cited {.bibliography src="mybib.json"}
> 
> # References {.bibliography src="foo.bib" include="item2,item3"
>                omit="item4" if-year="1999" only-if-type="primary"}

PS.  I'm sorely tempted to put off implementing these complexities
til later, and release a simple version of pandoc/citeproc that just
constructs a bibliography of works cited in the document and puts
them at the end, more or less the way it does now.  The one twist
I'd add would be this:  the bibliography is inserted only if the
document ends with a Header.  That way you could suppress the
bibliography by not ending with a Header.

We could keep this convention later even if we implemented a
<references /> element. So existing documents would not break.

What we'd be missing:

- ability to have multiple bibliographies
- ability to include works not cited in bibliographies
- ability to suppress works cited in bibbliographies
- ability to filter bibliographies by fields (e.g. source=primary)

These things would be nice for some users, but they add a lot of
complexity and could be implemented later.

Note:  users who want to style the bibliography could still do so.
Just specify --section-divs and the section containing the bibliography
(the section at the end of the document) will be put in a div with
its own id.

John