Re: [O] bibtex bibliography exported to HTML

[Christian Moe]

On 1/4/12 10:31 PM, Stephen J. Barr wrote:
> I want to include bibliography entries the
> way I would with LaTeX, but then have a decent looking bibliography
> when I export to HTML. Is this behaviour supported, and if so, how do
> I do it?

Hi,

It's not currently supported, but I have some pretty raw code lying 
around from last summer to do just that. I'd be obliged if you'd test 
drive the attached Org-cite.el.

Be warned, though, that even if it works for you, you'll probably want 
support and bugfixes that I have very little time for at the moment, 
being very busy with other work.

This version depends on bibtex for the formatting, so you need a 
working LaTeX installation. When your document's changed, before you 
export to HTML (or ODT), you need to first do a latex export and run 
bibtex on it.  Instructions follow below.

Yours,
Christian Moe


----

ORG-CITE

Org-cite formats bibliographic citations and reference lists in
Org-mode documents for export with non-LaTeX backends (HTML, ODT, 
plain text, Docbook...). Citations are hyperlinked to references.

Org-cite is /not/ mature for use in a "production environment." It
is intended to come in handy when you can deliver your final product
as LaTeX/PDF, but need to share drafts with full references in other
formats (HTML, ODT) with others.

Org-cite currently requires BibTeX for the formatting, so you still 
need a working LaTeX installation. Org-cite via BibTeX aims to produce 
a /reasonably close approximation/ to the formatting you get from a 
LaTeX export with a few of the most widely used BibTeX packages and 
styles (plain, natbib, and apacite for now). It does not /and will 
not/ aim at identical results to any package/style, nor to support all 
packages/styles out there.

Future versions will aim to include other formatters beside
BibTeX.

Org-cite can read raw latex cite macros including the most
usual subsets supported by the natbib and apacite packages: with
long and short authorlists, pre-notes, post-notes (locators), and
multiple citations, e.g. the natbib cite

: The cow jumped over the moon, \citet[see 
e.g.][p.11,p.6]{goose2010,thumb1999,thumb2003}.

should come out as something like

: The cow jumped over the moon, see e.g. Goose et al. (2010); Thumb 
(1999; 2003).

Future versions will also support some version of the custom Org cite
links preferred by some users.

Setting the command org-cite-format as a pre-processing hook for
export is always safe, since changes are done to a temporary copy of
your document. Doing org-cite-format directly in your working buffer
is possible (and helpful for debugging), but risks permanently
overwriting your cites if you then save without reverting. Please
always back up before you try this.


* Installation:

Make sure you have a working LaTeX/BibTeX installation. Place
org-cite.el somewhere on your load-path. Evaluate the following, or
add permanently to your .emacs:

#+begin_src emacs-lisp
  (require 'org-cite)
  (add-hook 'org-export-preprocess-hook 'org-cite-format)
#+end_src

Instead of adding the hook on startup, you can also toggle export
behavior with `M-x org-cite-toggle'.


* Use:

Org-cite does not automatically detect what package you are using, so
you need to tell it. The current options are natbib, apacite, or nil
for plain.

: (setq org-cite-bibtex-package 'apacite)

You also need to tell org-cite how to format your citations. Org-cite
gives you more options than some latex packages, but some of these may
give nonsensical results. The current options are =author-date=,
=numeric=, =notes= (similar to numeric, but inserted as Org 
footnotes), and =text= (full citation in text). I recommend sticking 
to the first three for now.

: (setq org-cite-method 'author-date)

If you only use one method, you may want to keep these in your .emacs.

To export foo.org to foo.odt with references:

- First export foo.org to LaTeX and process it until you get the
  output you want, e.g.
  : latex foo
  : bibtex foo
  : latex foo
  : pdflatex foo
  This produces =foo.aux= and =foo.bbl= files needed by org-cite.
- Make sure org-export-preprocess-hook includes org-cite-format (see
  above), and that your org-cite-bibtex-package and org-cite-method
  settings agree with your LaTeX settings.
- Export foo.org to ODT or other target format.

If things go wrong, org-cite may have choked while trying to cull
curly braces from your bibitems. You can troubleshoot this by looking
at the bibitem at point in the =org-cite-temp-bbl= buffer, which is
left open if org-cite ends prematurely (you need to kill this buffer
before trying again).


* Known problems

Org-cite handles many special (non-ascii) characters as represented in 
LaTeX, but not all; and it is picky when it comes to how these special 
characters are written. Some editing of your .bib file or at least the 
.bbl produced by bibtexing may be necessary. For example, it will 
recognize \"{a} as ä, but will not recognize \"a or {\"a}. There are 
two ways you can solve this: either conform your .bib file to 
org-cite's requirements, or conform org-cite to your .bib file by 
customizing org-cite-latex-chars-utf8 to include \"a as well.

For some reason I have not pinned down, a doubling of the bibliography 
section has been known to occur with some documents.


* Reporting bugs:

A bug report should ideally include all of the following:
- What you expected to see, and what you got
- The files foo.org, foo.aux and foo.bbl
- If export failed, traceback from the debugger and the contents of
  the org-cite-temp-bbl buffer

org-cite.el
Description: Text document