formats for dissertation writing

CSL Development
1

I’m working on my proposal at the moment and I’d like to decide how
I’m going to handle the text and the references.

Historically I’ve written in LateX using TeXshop.app and managed
references in bibtex using BibDesk.

I did once try writing with docbook NG and formatting references
using citeproc but I found it a little difficult. Is docbook still
the preferred format for citeproc development or has the focus
shifted to OpenOffice? Is there currently a way to run citeproc on
ODT formatted files?

In any case, I’d prefer to work with a readable plain-text
representation, something like textile or markdown, so that I can
share parts of my work for comment. That way I can copy parts into a
word doc and send it to my committee, most of whom prefer to use the
track changes and commenting features in word, I can then take their
edits and comments and work the contents back into well formed
representation ready for processing with whatever the chosen system
is. I’m happy for the citations to be coded someway (I’ve had \citet
{author00title} before without people freaking out.).

2

Hello James,

You might be interested in MultiMarkDown. There is also a
MultiMarkDown to PDF droplet on that site. References are limited
though in that implementation.

http://fletcher.freeshell.org/wiki/MultiMarkdown

I am currently writing in MarkDown myself. I hope that CiteProc will
one day support it and/or if I can contribute to that. (Need to learn
more XSLT/perl for that.)

Right now CiteProc is still in the design/implementation phase and
not very usable yet. (You’ll need to check with Bruce to ask where
exactly it is.)

If you need formatted references now, I think you need to look at
LaTeX en BibTex.

Johan—
http://www.geo.vu.nl/~jkool/

3

I did once try writing with docbook NG and formatting references using
citeproc but I found it a little difficult. Is docbook still the
preferred format for citeproc development or has the focus shifted to
OpenOffice? Is there currently a way to run citeproc on ODT formatted
files?

Supporting an XML input format is pretty easy, but I haven’t yet looked
at doing ODT. I still write with DocBook.

In any case, I’d prefer to work with a readable plain-text
representation, something like textile or markdown, so that I can
share parts of my work for comment. That way I can copy parts into a
word doc and send it to my committee, most of whom prefer to use the
track changes and commenting features in word, I can then take their
edits and comments and work the contents back into well formed
representation ready for processing with whatever the chosen system
is.

Ouch. It’s hard to live in a Word-dominated world, eh?

text: markdown/textile/reST → DocBook → PDF with
references: BibDesk → MODS → citeproc

(is MODS still the preferred format for citeproc?)

No, I ripped out MODS support for now (and maybe forever). I need to
formalize it more, but the current representation is RDF, and looks
like this (from the svn repo):

<http://svn.sourceforge.net/viewcvs.cgi/xbiblio/citeproc-xsl/trunk/
data/data.rdf?view=markup&rev=19>

or

markdown/textile/reST → LaTeX → PDF with
BibDesk → bibtex → LaTeX.

The Python docutils looks interesting
(http://www-128.ibm.com/developerworks/library/x-matters24/), has
anyone successfully used those with CiteProc?

Any other suggestions?

I rather like writing in Textile and markdown myself, and it’s one of
the reasons I wanted to port citeproc. Ruby has a nice library that can
handle both, and which it’s easy to dynamically extend (with citation
support, for example). IIRC, it will also be getting DocBook and TeX
output modes soon.

But obviously that’ll take some work.

Am in a bit of hurry and will be off-line for a few days.

Bruce

4

I am currently writing in MarkDown myself. I hope that CiteProc will
one day support it and/or if I can contribute to that. (Need to learn
more XSLT/perl for that.)

Yeah, a Perl port would make sense, though I’m rather more disposed to
Python and Ruby. I’d say the Ruby port is maybe a couple of days from
being finished, depending on one’s skills.

Right now CiteProc is still in the design/implementation phase and not
very usable yet. (You’ll need to check with Bruce to ask where exactly
it is.)

Well, that’s a little strong. The current release version managed to do
an excellent job formatting a full book manuscript. And my publisher
was quite happy with it.

The new version in SVN is in need of testing and more tweaking I think,
but it’s close to the same level. I expect to use it format the next
article I submit (fairly soon).

If you need formatted references now, I think you need to look at
LaTeX en BibTex.

But only if you only want PDF.

Bruce

5

I am currently writing in MarkDown myself. I hope that CiteProc
will one day support it and/or if I can contribute to that. (Need
to learn more XSLT/perl for that.)

Yeah, a Perl port would make sense, though I’m rather more disposed
to Python and Ruby. I’d say the Ruby port is maybe a couple of days
from being finished, depending on one’s skills.

I wasn’t suggesting a port to perl here actually. MarkDown is in
perl, and in order to gain good CiteProc support would need some
modifications, hence my reference to perl.

Right now CiteProc is still in the design/implementation phase and
not very usable yet. (You’ll need to check with Bruce to ask where
exactly it is.)

Well, that’s a little strong. The current release version managed
to do an excellent job formatting a full book manuscript. And my
publisher was quite happy with it.

That is good news! Didn’t know you had completed to whole transition
to RDF yet.

The new version in SVN is in need of testing and more tweaking I
think, but it’s close to the same level. I expect to use it format
the next article I submit (fairly soon).

That is text in DocBook format?

If you need formatted references now, I think you need to look at
LaTeX en BibTex.

But only if you only want PDF.

There is LaTeX2RTF, but that’s not always optimal. (Long time ago
that I looked at it, but it had much problems with accented
characters amongst others.)

Johan—
http://www.geo.vu.nl/~jkool/

6

I am currently writing in MarkDown myself. I hope that CiteProc will
one day support it and/or if I can contribute to that. (Need to
learn more XSLT/perl for that.)

Yeah, a Perl port would make sense, though I’m rather more disposed
to Python and Ruby. I’d say the Ruby port is maybe a couple of days
from being finished, depending on one’s skills.

I wasn’t suggesting a port to perl here actually. MarkDown is in perl,
and in order to gain good CiteProc support would need some
modifications, hence my reference to perl.

Right; it just might be easier (or at least more elegant) to be able to
include a citeproc module into MultiMarkDown. The author of it
actually contacted me awhile back about citation stuff.

Right now CiteProc is still in the design/implementation phase and
not very usable yet. (You’ll need to check with Bruce to ask where
exactly it is.)

Well, that’s a little strong. The current release version managed to
do an excellent job formatting a full book manuscript. And my
publisher was quite happy with it.

That is good news! Didn’t know you had completed to whole transition
to RDF yet.

No, that was with the MODS version. But the RDF version is working
fairly well now.

The new version in SVN is in need of testing and more tweaking I
think, but it’s close to the same level. I expect to use it format
the next article I submit (fairly soon).

That is text in DocBook format?

Yes.

If you need formatted references now, I think you need to look at
LaTeX en BibTex.

But only if you only want PDF.

There is LaTeX2RTF, but that’s not always optimal. (Long time ago that
I looked at it, but it had much problems with accented characters
amongst others.)

Right, I had problems as well.

Bruce

7

Hi Bruce,

(is MODS still the preferred format for citeproc?)

No, I ripped out MODS support for now (and maybe forever). I need to
formalize it more, but the current representation is RDF

If you want to attract many developers, I think you should be very
clear about the goals as well as the languages involved. No one wants
to invest lots of development effort just to find out it was all in
vain.

There should be a long-term strategy which you are committed to. I
really think that this would be beneficial for speeding up development
as well as for the project as a whole. People should get the feeling
that it’s worth contributing to this project.

Matthias

8

If you want to attract many developers, I think you should be very
clear about the goals as well as the languages involved. No one wants
to invest lots of development effort just to find out it was all in
vain.

True; I’ll figure out a way to support MODS somehow once things
stabilize again.

There should be a long-term strategy which you are committed to. I
really think that this would be beneficial for speeding up development
as well as for the project as a whole. People should get the feeling
that it’s worth contributing to this project.

We need a language neutral-styling language (CSL) and basically an API
to format citations.

Citeproc was originally written in XSLT 2.0, and there will always be
an XSLT 2.0 version, but there’s no reason it should not be ported to
other languages, including PHP. I actually think porting it will
attract more developers.

So my roadmap is:

  • get CSL to 1.0 ASAP and don’t change it for a long time
  • get citeproc-xsl to 1.0 (which means it supports all the features of
    CSL 1.0 + RDF and, somehow, MODS input)
  • encourage others to work with me on porting citeproc to other
    languages

I will probably be releasing something like 0.9 version of the first
two fairly soon for testing and such and feedback. I’d like to then try
to build up a wider range of styles to confirm CSL is solid. Once I’m
confident in that I’ll release the final version.

I don’t care what those “other languages” are: PHP, Ruby, Perl, Python,
Java, C++, Lua. It doesn’t matter. What matters is the logic (as
embodied in CSL, and the API).

I can’t do all this without help though.

Bruce

9

There should be a long-term strategy which you are committed to. I
really think that this would be beneficial for speeding up development
as well as for the project as a whole. People should get the feeling
that it’s worth contributing to this project.

We need a language neutral-styling language (CSL) and basically an API
to format citations.

Agreed, the more language-neutral the better.

So my roadmap is:

  • get CSL to 1.0 ASAP and don’t change it for a long time

Yes, I consider this the most important part. Give developers something
to chew on and promise them this is going to stay.

With this respect, John Gruber did an awesome job with markdown (IMHO)
– at some point he declared the syntax as fixed for the next time
being and did NOT attempt to do any greater changes.

And if changes get implemented, make sure that they are as backwards
compatible as possible.

Matthias

10

The sample command for the usage of CiteProc (in xdoc-config.xml) is
outdated.

Usage of CiteProc:

java net.sf.saxon.Transform -o samples/test.html samples/docbook-
test.xml lib/document/dbng-xhtml.xsl citation-style=“apa-en"
bibdb=“flatfile” bibinfile=”…/data/data.rdf"

Johan

11

The sample command for the usage of CiteProc (in xdoc-config.xml) is
outdated.

Yup.

Usage of CiteProc:

Thanks.

Bruce