[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [O] bibtex bibliography exported to HTML

From: Christian Moe
Subject: Re: [O] bibtex bibliography exported to HTML
Date: Wed, 04 Jan 2012 23:50:34 +0100
User-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:6.0.2) Gecko/20110902 Thunderbird/6.0.2

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?


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.

Christian Moe



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

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)

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

Attachment: org-cite.el
Description: Text document

reply via email to

[Prev in Thread] Current Thread [Next in Thread]