Support Citation Style Language (CSL) Styles in LibreOffice/OpenOffice - University Project

[ThiloteE]

This issue here is supposed to be for students and tries to explain the issue more clearly and broader as is done in the original issue (#2146). It also aims at preventing external CSL maintainers from being spammed with too many unnecessary JabRef related messages and requests.

Background info:

For the OpenOffice (OO) and LibreOffice (LO) integration, JabRef offers to format citations in various Styles. These styles are also referred to as JStyles. They are used by importing OO/LO Style files into JabRef. Please check out JabRef's LO/OO documentation for further information.

Problems:

1. The amount of JStyles offered by JabRef is very low.
2. Important and popular ones like APA, IEEE and others are missing.
3. Users having to create or adjust JStyle files is undesirable for various reasons:
   • Users may not have the expertise
   • Users may not have the time

Solution:

Support Citation Style Language (CSL) Styles in the LO/OO integration as originally proposed in #2146. That means, users should be able to select CSL styles somewhere in the "select styles" dialogue of the OO/LO integration.

There could potentially be two tabs: One for CSL styles, a separate tab for Jstyles.

[ThiloteE]

Additional Info: Documentation of the current OpenOffice integration code:

• https://github.com/JabRef/jabref/tree/main/docs/code-howtos/openoffice

Additional Info: How JabRef currently uses CSL:

• JabRef currently uses CSL for the Entry Preview in the entry-editor. The style can be chosen in the preferences.

  Entry-Preview (as separate tab):
  

  Preferences:
  

• JabRef uses Citeproc java by Michel-Kraemer. Citeproc-java is a Citation Style Language (CSL) processor for Java. It interprets CSL styles and generates citations and bibliographies.

[Siedlerchr]

Some hints on the code:
JabRef calls the UNO API of LibreOffice to insert formatted text into the Writer Document.
Roughly the approach is as follows for this here as well:

1. get the CSL->HTML for the bibliography (See Preview classes)
2. convert the HTML to OO-Text (these methods already exist, see for example formatFullReferenceOfBibEntry )

A difference: JabRef's jstyle format also controls the formatting of the in text citation and if it should be author year or numeric
This needs to be considered as well. Therefore, I would suggest starting with the formatting of the list of references.

[iandol]

The documentation «Documentation of the current OpenOffice integration code» link is a 404, is this the current location?

https://devdocs.jabref.org/code-howtos/openoffice/

[ThiloteE]

The documentation «Documentation of the current OpenOffice integration code» link is a 404 [...]

@iandol thx, I fixed it.

[ThiloteE]

This seems to be the main function that needs to be called to insert html formated text:

jabref/src/main/java/org/jabref/model/openoffice/ootext/OOTextIntoOO.java

Lines 100 to 131 in cbf99ec

	/**
	* Insert a text with formatting indicated by HTML-like tags, into a text at the position given by a cursor.
	* <p>
	* Limitation: understands no entities. It does not receive any either, unless the user provides it.
	* <p>
	* To limit the damage {@code TAG_NAME_REGEXP} and {@code ATTRIBUTE_NAME_REGEXP} explicitly lists the names we care about.
	* <p>
	* Notable changes w.r.t insertOOFormattedTextAtCurrentLocation:
	* <p>
	* - new tags:
	* <p>
	* - {@code <span lang="zxx">} - earlier was applied from code
	* <p>
	* - {@code <span oo:CharStyleName="CharStylename">} - earlier was applied from code, for "CitationCharacterFormat"
	* <p>
	* - {@code <p>} start new paragraph - earlier was applied from code
	* <p>
	* - {@code <p oo:ParaStyleName="ParStyleName">} : start new paragraph and apply ParStyleName - earlier was applied from code
	* <p>
	* - {@code <tt>} - earlier: known, but ignored - now: equivalent to {@code <span oo:CharStyleName="Example">} - {@code <oo:referenceToPageNumberOfReferenceMark>} (self-closing)
	* <p>
	* - closing tags try to properly restore state (in particular, the "not directly set" state) instead of dictating an "off" state. This makes a difference when the value inherited from another level (for example the paragraph) is not the "off" state.
	* <p>
	* An example: a style with {@code ReferenceParagraphFormat="JR_bibentry"} Assume JR_bibentry in LibreOffice is a paragraph style that prescribes "bold" font. LAYOUT only prescribes bold around year. Which parts of the bibliography entries should come out as bold?
	* <p>
	* - The user can format citation marks (it is enough to format their start) and the properties not (everywhere) dictated by the style are preserved (where they are not).
	*
	* @param position The cursor giving the insert location. Not modified.
	* @param ootext The marked-up text to insert.
	*/
	public static void write(XTextDocument doc, XTextCursor position, OOText ootext)

This is the class the currently generates our custom JStyle format export layout:

jabref/src/main/java/org/jabref/logic/openoffice/style/OOBibStyle.java

Line 58 in 27a22af

public class OOBibStyle implements Comparable<OOBibStyle> {

[Siedlerchr]

Some additional stuff. Citeproc-java can render both the citation and the bibliography (list of references)

Current state: JabRef only renders the bibliography
JabRef's CSLAdapter class needs to be extended to support making the citation as well, but that is simple:
cslInstance.makeCitation( id ) where id would be the citation key