display="block" does not appear to be honoured in csl styles

[dfaligertwood]

See citation-style-language/styles#1140

I'll put up a minimal example in a bit.

Relevant CSL spec section: http://citationstyles.org/downloads/specification.html#display

[jgm]

Correct, this is not implemented yet. It's a little hard to see how to implement this in a way that would work with all pandoc output formats.

+++ dfaligertwood [Sep 23 14 07:31 ]:

See citation-style-language/styles#1140

I'll put up a minimal example in a bit.

Relevant CSL spec section: http://citationstyles.org/downloads/specification.html#display

---

Reply to this email directly or view it on GitHub: https://github.com/jgm/pandoc-citeproc/issues/85

[njbart]

"It's a little hard to see how to implement this …"

To me, it seems a "block" is essentially to be formatted like a (new) paragraph.

"indent" is essentially a blockquote.

And "left-margin" and "right-inline" could be formatted like a numbered list, with "left-margin" in place of the number.

(Note that the default assumption seems to be that "left-margin" and "right-inline" appear together; if one is missing, the other is to be formatted as a "block".)

[jgm]

+++ nickbart1980 [Sep 23 14 08:45 ]:

"It's a little hard to see how to implement this …" To me, it seems a "block" is essentially to be formatted like a (new) paragraph. "indent" is essentially a blockquote. And "left-margin" and "right-inline" could be formatted like a numbered list, with "left-margin" in place of the number.

The only difficulty is that there's nothing really corresponding to the "left-margin / right-inline" combination. An ordered list (as you suggest) could almost work, but we need the ability to completely customize the list number, which pandoc does not currently give you.

Perhaps a definition list could be used? The default display wouldn't be quite right in HTML, but it could be customized with CSS so that the definition part formed an indented block after the term part.

[njbart]

I guess using a definition list would be a good start.

For latex, https://tex.stackexchange.com/questions/130097/automatically-set-description-list-labelwidth-based-on-widest-label might be helpful, too.

[scaramouche1]

Any news on this issue? I think that a perfectly good solution is just to use a space to separate the left-margin and right-inline.

All the reference styles that use display="block", generate references like the following:

Author1
year-publication1 title-publication1
year-publication2 title-publication2

Author2
year-publication3 title-publication3
year-publication4 title-publication4

Thus, left-margin and right-inline are not an issue (in 99.9% of the cases all the years, which have 4 characters, are already aligned).

[rmzelle]

I just checked the frequency of the various options in the CSL repository:

• display="block": 45x in 33 styles
• display="left-margin": 12x in 12 styles
• display="right-inline": 47x in 11 styles
• display="indent": 2x in 2 styles

Even partial support (for just display="block" and display="indent"), which would cover the majority of cases, would already be very helpful.

[njbart]

@rmzelle (and perhaps @fbennett, too): Maybe you could clarify what you expect the output from the various elements to look like in html (and possibly other formats …).

• Is block any different from an ordinary paragraph?
• Is indent any different from an ordinary blockquote?
• Are left-margin and right-inline best formatted like numbered list items, with the contents of left-margin in place of the number? Or as a row in a two-column table, as seen in http://docs.citationstyles.org/en/stable/specification.html#display?

And let’s not forget the related hanging-indent and second-field-align (http://docs.citationstyles.org/en/stable/specification.html#whitespace):

• hanging-indent seems straightforward, I’m using css:

  div.hanging {
    padding-left: 2em;
    text-indent: -2em;
  }

  This is similarly straightforward in LaTeX as well as MS Word and LibreOffice.

• For second-field-align we need, again, a format like a numbered list item, with the first field of all items as wide as the longest label (I’m not sure how to achieve this in html). Nothing else seems to be needed for the flush option, but for margin, the first field needs to appear in the margin (again I’m not sure how to achieve this).

I should hope that clarification on the expected html formats will help to find out how to implement this in pandoc.

[rmzelle]

I haven't studied citeproc-js's output, which might already address all these options, but:

Is block any different from an ordinary paragraph?

I think treating blocks as regular paragraphs could mess up the line-spacing (see http://docs.citationstyles.org/en/stable/specification.html#whitespace). You probably wouldn't want extra space before and after each block. The most important thing is that each block needs to start on a new line. (I think "block" was based on the CSS display: block; key/value, https://developer.mozilla.org/en-US/docs/Web/CSS/display)

Is indent any different from an ordinary blockquote?

Semantically, that seems wrong, but if it triggers indentation it could work visually.

Are left-margin and right-inline best formatted like numbered list items, with the contents of left-margin in place of the number? Or as a one row in a two-column table, as seen in http://docs.citationstyles.org/en/stable/specification.html#display?

A table seems more elegant (repurposing a list seems like a hack). A table would work for second-field-align as well, right?

[rmzelle]

Here is the HTML output as produced by Zotero/citeproc-js for the "block", "left-margin", "right-inline", and "indent" options: https://gist.github.com/rmzelle/03da0873c9af2d096c31e9976bd96c6f

[njbart]

That’s helpful. However, if I add more text to the “left-margin”/“right-inline” example in your test.html, I get something that looks like

left-margin  right-inline right-inline right-inline right-inline right-inline
right-inline right-inline right-inline right-inline right-inline right-inline 
right-inline right-inline right-inline

rather than the expected

left-margin  right-inline right-inline right-inline right-inline right-inline 
             right-inline right-inline right-inline right-inline right-inline 
             right-inline right-inline right-inline right-inline right-inline 
             right-inline

[njbart]

Ok, from what I’ve seen so far it seems there are a number of issues.

First, observations:

1. citeproc-js output: This is what I get in Zotero/LO with @rmzelle’s test.csl (with some more “right-inline” text added):

   

   … so there are various issues (extra newline at the beginning, extra paragraph at the end, no newline before “indent”, …), also note that no tables are used

2. Seemingly correct output can be achieved in html using divs and css; see https://gist.github.com/nickbart1980/1e7d5ec15035b304886e58c87cbd4b48

   

   left-margin alone and right-inline alone cannot be formatted correctly in this way; either csl processors should format either, if occurring alone, as block, or (better) CSL style files containing left-margin alone or right-inline alone should not pass validation.

3. In LO (and MS Word), left-margin+right-inline can be formatted as a paragraph with hanging indent and a tab.

   Note that three different paragraph styles are needed here; possibly more if top and bottom margins matter, but formatting this as one paragraph with newlines, what citeproc-js seems to have been trying so far, seems impossible.

4. In LaTeX, a list will easily do the trick for left-margin+right-inline (not shown).
5. One problem in all these formats is how to automatically set the correct width of left-margin.

Second, conceptual questions:

1. The CSL specs are not entirely clear on whether hanging-indent or second-field-align can be used together with the display attributes. Can they?

   If yes, where should a block after a hanging-indent or second-field-align start, flush left or indented? (If used for an abstract or notes, I’d say indented, but the specs are silent.)

2. “If used, all rendering elements should be under the control of a display attribute.” (http://docs.citationstyles.org/en/stable/specification.html#display). In chicago-annotated-bibliography.csl (see OP) this is not the case. Is this style even valid then?
3. Even if it’s valid, shouldn’t there be a simpler way for having a newline inserted into the output? Many blocks and the indent in society-for-american-archaeology.csl seem to be used for nothing else than that.
4. Are there any guidelines on the relative dimensions of left-margin vs. indent? (In the style repo, these co-occur once only, in university-of-helsinki-faculty-of-theology.csl, indent first, and since there’s no documentation link, I’m not even sure whether that was intended …)

[rmzelle]

left-margin alone and right-inline alone cannot be formatted correctly in this way; either csl processors should format either, if occurring alone, as block, or (better) CSL style files containing left-margin alone or right-inline alone should not pass validation.

The CSL 1.0.1 already says that lone "left-margin" and "right-inline" elements should be treated as blocks. Schema validation to disallow lone elements is not trivial and would require something like additonal embedded Schematron rules.

The CSL specs are not entirely clear on whether hanging-indent or second-field-align can be used together with the display attributes. Can they?

I'm pretty sure that these are mutually exclusive.

“If used, all rendering elements should be under the control of a display attribute.” (http://docs.citationstyles.org/en/stable/specification.html#display). In chicago-annotated-bibliography.csl (see OP) this is not the case. Is this style even valid then?

The spec says "should" instead of "must", so it's not technically wrong, but it would probably be better to change

    <layout suffix=".">
      <group delimiter=". ">
        ...
      </group>
      <text variable="note" display="block"/>
    </layout>

in chicago-annotated-bibliography.csl to

    <layout suffix=".">
      <group display="block" delimiter=". ">
        ...
      </group>
      <text variable="note" display="block"/>
    </layout>

Even if it’s valid, shouldn’t there be a simpler way for having a newline inserted into the output?

Maybe. You can't just print a newline though, since you'd want it to be conditional on the presence of content before and after the line break.

Are there any guidelines on the relative dimensions of left-margin vs. indent?

I don't think this has ever been discussed within CSL, no.

[njbart]

But chicago-annotated-bibliography.csl also has hanging-indent="true" (as all Chicago styles do). If hanging-indent and display are mutually exclusive, the style still wouldn’t be valid.

<text variable="note" prefix="&#10;"/> OTOH seems to work for chicago-annotated-bibliography.csl (in pandoc at least).

So I guess my first suggestion for CSL would be to get rid of all display="block" attributes in styles that have hanging-indent or second-field-align set (and replace them with newlines), and then see to what extent display attributes are still needed in general. One of the seemingly more popular display/block/left-margin/right-inline styles, American Anthropological Association, has become obsolete; AAA have fully switched to Chicago Manual of Style (Author-Date) now (http://www.americananthro.org/StayInformed/Content.aspx?ItemNumber=2044&navItemNumber=693).

For pandoc I’d suggest: Do implement hanging-indent and second-field-align, but leave the display attributes on the backburner until these are sorted out more fully on the CSL side.

[rmzelle]

The CSL specs are not entirely clear on whether hanging-indent or second-field-align can be used together with the display attributes. Can they?

I'm pretty sure that these are mutually exclusive.

Oh, sorry, I totally misread this the first time around. I meant to say that hanging-indent and second-field-align should probably be mutually exclusive. (which seems like an easier question to answer)

I don't see why hanging-indent and second-field-align should be incompatible with display="block", although I agree it's a bit nebulous how they should interact with the other display options. I can do some digging in the xbiblio-dev mailing list archive to figure why the different options were added to begin with.

<text variable="note" prefix="&#10;"/> OTOH seems to work for chicago-annotated-bibliography.csl (in pandoc at least).

The benefit of display="block" is that the line break is conditional (like delimiters), though (and give a target for CSS, if you'd want to style the block).

[phretor]

@jgm bump! :-)

[cormacrelf]

There's also CSS grid in HTML output mode, that can create pretty good results with consistent alignment throughout the references div, even with block elements in between. There are few couple of ways to emulate this in other formats, like https://github.com/bitzl/latex-grid-system, but maybe not OOXML.

https://gist.github.com/cormacrelf/9ca29bd720d7043d64d5cd5fab5d3e03