Q: This gem vs citeproc gem?

[jrochkind]

Hi, thanks for writing all this stuff! I am looking at it to see how to use it to do what I need, and I notice there is this gem, citeproc-ruby, which depends on another gem, citeproc. Can you explain the motivation or division of responsibilities between these two gems? It would help me understand the code. The gem just called citeproc is, of course, in ruby, just like this gem citeproc-ruby is!

[inukshuk]

The implementation is split up into the two gems for historical reasons (actually, three gems, because the csl gem is relevant here too). The distinction between citeproc and citeproc-ruby is a bit unfortunate from today's perspective: it was introduced because we had an interface for citeproc-js that could be called from Ruby. So the citeproc gem basically handles the processor's input and output while an rendering 'engine' does the actual rendering (in this case citeproc-ruby is the 'engine').

[jrochkind]

ah, okay, that sort of clears things up. It sounds like that interface for citeproc-js that could be called from ruby isn't a thing anymore?

I'd like to use CiteProc::Name directly from citeproc in my own code, to have a data model for names that matches the needs of citations. Does this see reasonable? If I wanted to parse a name and have it turn out as a single CiteProc::Name (not Names) (already knowing/guessing it's a personal not corporate name), this is the best I've figured out: CiteProc::Name.new(Namae.parse(str_name)). Does that seem like a forwardsly compatible reliable way to do that?

[inukshuk]

Yes that sounds reasonable to me; CiteProc::Name contains a lot of helpers in a vain attempt to make the actual name rendering simpler -- I think they can be useful if you want to render names or parts of names elsewhere.

And, yes, the citeproc-js Ruby engine is not a thing anymore.

[jrochkind]

Cool, thanks! Doing similar with CiteProc::Date.

What methods do you mean as helpers? I'm not sure how to interpret the thing you linked to, are the helpers in there? I might find helpers pretty useful.

[inukshuk]

That was poorly phrased, sorry. I just meant all the instance methods of Name help to keep some name formatting and sorting/comparing details our of the name node renderer (which is too complicated as it is).

[retorquere]

I'm still a little confused by these two gems. Would I expect to use citeproc, which would in turn (automatically?) use citeproc-ruby? The other way around? The readme's of the two projects look to be precisely the same.

[inukshuk]

For most intents and purposes you need all three gems citeproc-ruby, citeproc and csl; since citeproc-ruby sets dependencies on the other two you. The naming is a bit unfortunate for historical reasons, but just think of citeproc-ruby as the main gem you need to install (and it should pull in the others).