pandoc/citeproc issues: to flag or not to flag?

pandoc/citeproc issues: to flag or not to flag?

[John MacFarlane]

[We've made huge progress on pandoc/citeproc.  I'm going to
send a few emails discussing some outstanding issues that
I'd like to resolve.  To make the conversations more coherent,
I'm splitting them up by topic.]

Currently pandoc's citeproc capabilities are activated using a cabal
flag, 'citeproc'.  Unfortunately, the way we do this violates Cabal
policy, which says that the flags shouldn't change the API.
If you specify 'citeproc', the module Text.Pandoc.Biblio gets
exposed; otherwise, it does not.

Some possible solutions:

1. Remove the citeproc flag, so that pandoc now depends on citeproc and cannot
be installed without it. I think this is probably the way to go, but it
significantly increases pandoc's dependencies and might cut down portability.
It would also slow e.g. debian packaging. Perhaps we should make sure citeproc
installs on a variety of OS's before proceeding.

2.  Don't expose Text.Pandoc.Biblio; just use it internally in pandoc.
This would allow pandoc to be installed without citeproc (we could still
make the citeproc flag default to True).  The problem is that this would
make it impossible for people using pandoc as a library to get access
to the citeproc bits.

I don't see any other solution.  We can't even provide a stub
processBiblio function, because its type is constructed out of
types defined in citeproc.  But I wanted to see whether people had
other ideas, or preferences between the above options.

John

Re: pandoc/citeproc issues: to flag or not to flag?

[Andrea Rossato]

On Sun, Nov 21, 2010 at 10:49:54AM -0800, John MacFarlane wrote:
> [We've made huge progress on pandoc/citeproc.  I'm going to
> send a few emails discussing some outstanding issues that
> I'd like to resolve.  To make the conversations more coherent,
> I'm splitting them up by topic.]
> 
> Currently pandoc's citeproc capabilities are activated using a cabal
> flag, 'citeproc'.  Unfortunately, the way we do this violates Cabal
> policy, which says that the flags shouldn't change the API.
> If you specify 'citeproc', the module Text.Pandoc.Biblio gets
> exposed; otherwise, it does not.

Cabal is not the Bible. They expose an API which changes at every
release. Did you ever try to link against the cabal library? I
wouldn't take their policy too seriously.

> Some possible solutions:
> 
> 1. Remove the citeproc flag, so that pandoc now depends on citeproc and cannot
> be installed without it. I think this is probably the way to go, but it
> significantly increases pandoc's dependencies and might cut down portability.
> It would also slow e.g. debian packaging. Perhaps we should make sure citeproc
> installs on a variety of OS's before proceeding.

citeproc-hs should be portable, even when linked to hs-bibutils (which
should be indeed portable too). I did not try, though.

The only dependencies citeproc-hs adds to pandoc are json and
hs-bibutils.

> 2.  Don't expose Text.Pandoc.Biblio; just use it internally in pandoc.
> This would allow pandoc to be installed without citeproc (we could still
> make the citeproc flag default to True).  The problem is that this would
> make it impossible for people using pandoc as a library to get access
> to the citeproc bits.
> 
> I don't see any other solution.  We can't even provide a stub
> processBiblio function, because its type is constructed out of
> types defined in citeproc.  But I wanted to see whether people had
> other ideas, or preferences between the above options.

My suggestion would be to use the flag and make it True when we decide
the time has come. That would leave the possibility to compile and
package pandoc without citeproc. If you are really concerned about the
cabal policy we just change processBiblio to:

processBiblio :: FilePath -> [FilePath] -> Pandoc -> IO Pandoc

and we move there the style and the bibliographic data reading.

Andrea

Re: pandoc/citeproc issues: to flag or not to flag?

[John MacFarlane]

+++ Andrea Rossato [Nov 22 10 23:14 ]:
> On Sun, Nov 21, 2010 at 10:49:54AM -0800, John MacFarlane wrote:
> > [We've made huge progress on pandoc/citeproc.  I'm going to
> > send a few emails discussing some outstanding issues that
> > I'd like to resolve.  To make the conversations more coherent,
> > I'm splitting them up by topic.]
> > 
> > Currently pandoc's citeproc capabilities are activated using a cabal
> > flag, 'citeproc'.  Unfortunately, the way we do this violates Cabal
> > policy, which says that the flags shouldn't change the API.
> > If you specify 'citeproc', the module Text.Pandoc.Biblio gets
> > exposed; otherwise, it does not.
> 
> Cabal is not the Bible. They expose an API which changes at every
> release. Did you ever try to link against the cabal library? I
> wouldn't take their policy too seriously.

Changing your API with a new release is fine, since users of
the library can specify a release or range of releases.  It's
much more problematic if the API depends on flags, because there's
no way, in a cabal file, to say "this library depends on
pandoc compiled with the citeproc flag."

So, I think the policy here is well motivated and would like to conform to it.

> > Some possible solutions:
> > 
> > 1. Remove the citeproc flag, so that pandoc now depends on citeproc and cannot
> > be installed without it. I think this is probably the way to go, but it
> > significantly increases pandoc's dependencies and might cut down portability.
> > It would also slow e.g. debian packaging. Perhaps we should make sure citeproc
> > installs on a variety of OS's before proceeding.
> 
> citeproc-hs should be portable, even when linked to hs-bibutils (which
> should be indeed portable too). I did not try, though.
> 
> The only dependencies citeproc-hs adds to pandoc are json and
> hs-bibutils.

This suggests to me that we should just make citeproc a standard
dependency of pandoc, and remove the flag.

Would anyone object to this?

John