How to define in-text CSL format for HTML citations?

CSL Development
1

Hi List,

I posted this questionhttps://github.com/citation-style-language/documentation/issues/33
(text
below) as a Github issue on the CSL pages and Rintze suggested I post it to
this list as well.

I would like to define a CSL file in which the in-text format includes a
link to the resource. Can this be done in CSL by say, modifying the layout
element appropriately? I cannot figure out how to use a variable in the
prefix/suffix.

I imagine a <citation> element looking something like this:

<layout prefix="(<a href='URL'>" suffix="</a>)" delimiter="; ">
      <text macro="author-short"/>
      <text macro="issued" prefix=" "/>
</layout>

but cannot see how to get URL value from something like <text macro="url"> into the prefix.

Given the importance of web-based formats and the ease of using CSL to
generate citations in markdown and html documents with tools such as
pandoc, it seems natural that individuals would want to style in-text
citations not only to reflect journal norms of author surnames etc, but
include such features as actual links, perhaps add title attributes for
mouse-over effects, and so forth. If this is not possible in the current
implementation, is this something CSL might address in the future?

I imagine that a flexible implementation of this could further be used to
add semantic data to inline citations, e.g.

<a rel="cito:UsesMethodIn" href="http://doi.org/

10.1186/2041-1480-1-S1-S6">Shotton (2010)

Can any of this be done using the current schema? If not, is this a
reasonable thing to work towards or should it be left to some other tool?

Thanks,

Carl–
Carl Boettiger
UC Santa Cruz
http://carlboettiger.info/

2

My tendency would be for CSL to stay out of the "styling/linking"
issue and leave that to individual implementations (in other words,
citeproc-hs or citerproc-js etc could accept flags for hyperlinking
citations etc.) The main reason would be that otherwise we’d have to
start duplicating styles with various styling implementations and that
sounds like a nightmare.

That said, for your particular issue:
I’m not sure what you’re suggesting makes sense - the layout is for an
entire citation, which can contain multiple item, each of which can
have a URL, so you wouldn’t want the URL in the layout field or rather

  • which one would you want?). But you could, of course, easily do
    something like






with proper escaping, obviously.

3

What Sebastian said. CSL is agnostic about output format, and it’s up to
implementations to sort out these details.

4

I only subscribed to the mailinglist after having read this message,
so please forgive me the bad citation.

Carl Boettiger wrote:

Given the importance of web-based formats and the ease of using CSL to
generate citations in markdown and html documents with tools such as
pandoc, it seems natural that individuals would want to style in-text
citations not only to reflect journal norms of author surnames etc, but
include such features as actual links, perhaps add title attributes for
mouse-over effects, and so forth. If this is not possible in the current
implementation, is this something CSL might address in the future?

I’m also having problems with this. I’m currently implementing a
CSL-based solution for displaying publication lists on a homepage. For
this I also want to include some links.

I think it is correct, that CSL shouldn’t depend on the selected
output format, so my proposal would be to have a syntax like

This would allow the processor to wrap a certain text part with a
link, or ignore it. This wouldn’t depend on the output format.

Also the argument, that one would get even more styles, which also
differ in the linking behavior doesn’t hold in my opinion. My current
solution is much worse :frowning:

The solution provided by Sebastian doesn’t work, because it is invalid
XML (using prefix=“<a href='”). I don’t know how this could be escaped
properly to be read in correctly, and still have the correct tags in
the output.

At the moment I use intermediate markers of the kind prefix=“{{a
href='” which are then replaced in a post-processing step by ‘<’. This
results in ugly one-time-styles. I would really like to see some kind
of linking features like proposed above.

Best regards,
Christoph

5

The solution provided by Sebastian doesn’t work, because it is invalid
XML (using prefix=“<a href='”).
This is mainly a technical discussion list for an XML based format, so
I assume people know how to escape XML. See e.g.
Free Online XML Escape / Unescape Tool - FreeFormatter.com

6

Zitat von Sebastian Karcher <@Sebastian_Karcher>:

The solution provided by Sebastian doesn’t work, because it is invalid
XML (using prefix=“<a href='”).
This is mainly a technical discussion list for an XML based format, so
I assume people know how to escape XML. See e.g.
Free Online XML Escape / Unescape Tool - FreeFormatter.com

I know how to escape XML, but not how escaping in this specific case
would solve the problem, i.e. get a valid
tag after processing.
Using e.g. citeproc-node with something like suffix=“<br/>” for
testing, gives me <br/>, which is a verbatim
and not a
line break, what one would need.

Christoph

7

Maybe one of those days, but I’m not following this discussion at all.

Can you just describe what you’re trying to do, and we can talk about
possible solutions and workarounds?

8

Christoph,

That’s right. Any text that reaches the processor through CSL code will be
escaped according to the output format. The only way to do this through CSL
markup is what you have been doing (i.e. setting a slug in the CSL, and
then replacing it in each citation after it is rendered).

Adding wrapper markup is currently out of scope for CSL proper, but
processors may offer their own hooks to accomplish this. If you’re running
citeproc-node, you’ll be running citeproc-js, which could be extended to
support field-level wrappers with a small amount of work, thanks to
groundwork done to support Steve Ridout’s work on the CSL Visual Editor.

The business end of the hook is in formats.js, in the "@showid/true"
function:

https://bitbucket.org/fbennett/citeproc-js/src/0948536cb1b541aea81b2b94ba98682c8692bcf6/src/formats.js?at=default#cl-112

As you can tell from the source, this is currently just hard-wired code
that sets a span on the output. The span is used in the Visual Editor to
navigate from an element in a rendered citation back to its source in CSL
code. It is enabled by a processor option (csl_reverse_lookup_support),
which (unlike other options) must be set in the source code itself,
before building the engine:

https://bitbucket.org/fbennett/citeproc-js/src/0948536cb1b541aea81b2b94ba98682c8692bcf6/src/formats.js?at=default#cl-112

We can exploit this code to support your use case (which I’m guessing will
be very popular once supported). I think the way to do it would be to
provide a hook on the processor that registers a callback to add a wrapper
according to your preferences, based on the item data and the context of
the item.

Does that sound like it would be useful?

Frank

9

right, what Frank says is the broader answer to your question. As both
me and Bruce said in the original thread, the issue is not that this
isn’t an understandable and relevant request, but that the CSL
specifications aren’t the right place for it. This needs to happen in
the various processors, some of which, as Frank points out, are well
set-up for this.

My guess would be that with three flags, something like
"hyperlink_title," “hyperlink_DOI,” and “hyperlink_URL” you’d have
most bases covered.

As for the escaped/unescaped html in affixes: The original poster had
html in affixes, so I assumed he was happy with the output. My
suggestion was just a tweak on something he posted and I was quite
clear that I didn’t consider it a general solution.

10

Though, I think, you would want to be flexible enough to be able to
hyperlink other identifiers, like PMID/PMCID. Maybe an attribute like
"hyperlink" (on group or text/number/etc. nodes) could reference a macro
that would generate the actual url.

11

Though, I think, you would want to be flexible enough to be able to
hyperlink other identifiers, like PMID/PMCID. Maybe an attribute like
“hyperlink” (on group or text/number/etc. nodes) could reference a macro
that would generate the actual url.

With a callback against the item in context, you could even provide RDFa
wrappers on the individual elements. It would be a little tricky to get it
right, but the effects against some of the new statutory archives in the
UK, the US and Europe could be really nice. It would open a path to linking
into author profiles on ORCID eventually as well.

12

Frank, thanks for your reply.

Zitat von Frank Bennett <@Frank_Bennett>:

Adding wrapper markup is currently out of scope for CSL proper, but
processors may offer their own hooks to accomplish this.

In my opinion, there isn’t much difference between a font-weight,
display and a potential href argument.

My use case is, that I want to generate different publication lists
for our institute’s homepage, and this should allow to wrap quite
arbitrary parts of a bibentry with a link. So your proposal to add a
hook to certain items propably wouldn’t work straight away.

So, with an href argument, a possible part would look like

As a workaround, I created two macros doi-or-url-start and
doi-or-url-stop which allow to insert pseudo links, which are then
post-processed with PHP. For reference, here are the snippets I
currently use:

For the replacements of the ‘{{…’ stuff I use the following regular
expressions:

function replaceLinks($text) {
$pattern = array(‘/{{(a href=.?)}}(.?){{/a}}/’,
‘/{{(/?(?:[hH][1-6]|[a-zA-Z]+))/?}}/’);
$replacement = array(‘<\1>\2’,
‘<\1>’);
return preg_replace($pattern, $replacement, $text);
}

Best regards,
Christoph

13

Frank, thanks for your reply.

Zitat von Frank Bennett <@Frank_Bennett>:

Adding wrapper markup is currently out of scope for CSL proper, but
processors may offer their own hooks to accomplish this.

In my opinion, there isn’t much difference between a font-weight,
display and a potential href argument.

They look similar in HTML markup, but the first two are purely about
display, and the last requires information from the item data. Also, you
might place the first two anywhere in a citation, but the last needs to go
exclusively on a node that renders a variable (if we are going to render
fine-grained linking, which we should provide for – to cover RDFa).

My use case is, that I want to generate different publication lists
for our institute’s homepage, and this should allow to wrap quite
arbitrary parts of a bibentry with a link. So your proposal to add a
hook to certain items propably wouldn’t work straight away.

Yes, you would need to write a small snippet of JavaScript code. When the
adjustments to the processor are done, I’ll post instructions.

So, with an href argument, a possible part would look like

If you want to wrap the entire bib entry in a single like like that, it’s
already supported – that is what the code added for Philip Lord’s project
does.

Coding the wrapper and variable into the CSL would make things quite stiff.
People might want to link with an anchor around the cite, or place a button
next to the cite, or link to a resolver with a selection of cite details,
or just apply a highlight to some portion the cite, conditioned on its
content. Or link to the ORCID ids or profiles of all authors on an item in
a rollover menu (including authors dropped by et al. truncation).

A hook can be made to cover any of those use cases fairly easily.

As a workaround, I created two macros doi-or-url-start and
doi-or-url-stop which allow to insert pseudo links, which are then
post-processed with PHP. For reference, here are the snippets I
currently use:

For the replacements of the ‘{{…’ stuff I use the following regular
expressions:

function replaceLinks($text) {
$pattern = array(‘/{{(a href=.?)}}(.?){{/a}}/’,
‘/{{(/?(?:[hH][1-6]|[a-zA-Z]+))/?}}/’);
$replacement = array(‘<\1>\2’,
‘<\1>’);
return preg_replace($pattern, $replacement, $text);
}

That was what I understood. A hook function will be easier for you to work
with, once it’s running in the processor.

More news in a few days!

Frank

14

Zitat von Frank Bennett <@Frank_Bennett>:

My use case is, that I want to generate different publication lists
for our institute’s homepage, and this should allow to wrap quite
arbitrary parts of a bibentry with a link. So your proposal to add a
hook to certain items propably wouldn’t work straight away.

Yes, you would need to write a small snippet of JavaScript code. When the
adjustments to the processor are done, I’ll post instructions.

great.

Coding the wrapper and variable into the CSL would make things quite stiff.
People might want to link with an anchor around the cite, or place a button
next to the cite, or link to a resolver with a selection of cite details,
or just apply a highlight to some portion the cite, conditioned on its
content. Or link to the ORCID ids or profiles of all authors on an item in
a rollover menu (including authors dropped by et al. truncation).

I see

More news in a few days!

Thank you!

Christoph

15

The latest processor release tag (1.0.531) should give you a hook for
adding link anchors in HTML output. Here is a sample hook function, which
should be defined as an element on the “sys” object, before the processor
is instantiated:

sys.variableWrapper = function (itemData, variableNames, str, punct) {
if (variableNames[0] === ‘title’ && itemData.URL) {
return ‘’ + str + ‘’ + punct;
} else {
return (str + punct);
}
}

itemData is the input item, in CSL JSON format. Simple fields are easy, for
names you may need to do some study and sleuthing to figure out how they
work.

variableNames is an array of variable names. Normally this will be just a
single name, but cs:names nodes can specify multiple creator types (such as
editor and translator).

str is the field content, less any trailing punctuation applied by CSL.

punct is an empty string or a single punctuation character.

If you set that function and run the new processor in your current
environment, it should just work. That’s what it says here, anyway. :slight_smile:

Frank

16

(You may want access to the state object inside that function, to inspect
options.and processor globals; but let me know how it works in the current
configuration before we extend it).