Persist citation nature in the CSL reference mark (#15437)

pluto-han · calixtus · web-flow · commit faf043681ee7 · 2026-03-30T18:08:24.000Z
* Persist in-text/empty nature in the CSL reference mark

* Backward compatibility with legacy citations

* Remove superfluous comments

* Add comments in `getUpdatedReferenceMarkNameWithNewNumbers`

* Extract citation style and citation type into one method

* Reformat code

* Update CHANGELOG.md

* Transform if-else to switch

* Refactor updateMarkAndTextWithNewStyle

* use else-if for backward compatibility

* update CHANGELOG.md

---------

Co-authored-by: Carl Christian Snethlage &lt;50491877+calixtus@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv
 
 ### Changed
 
+- We changed CSL reference format by adding citation type at the end.  [#15370](https://github.com/JabRef/jabref/issues/15370) [#15434](https://github.com/JabRef/jabref/issues/15434)
 - We changed the groups filter field to use a filter icon. [#15402](https://github.com/JabRef/jabref/issues/15402)
 - We improved the MultiMergeEntries dialog to automatically select the most plausible field value when merging entries (e.g. a more specific date). [#15027](https://github.com/JabRef/jabref/issues/15027)
 - We removed the restart prompt when accepting Mr. DLib privacy settings or hiding the Related articles tab in the entry editor. [#15195](https://github.com/JabRef/jabref/issues/15195)
diff --git a/jablib/src/main/java/org/jabref/logic/openoffice/ReferenceMark.java b/jablib/src/main/java/org/jabref/logic/openoffice/ReferenceMark.java
@@ -6,18 +6,22 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import org.jabref.logic.openoffice.oocsltext.CSLCitationType;
+
 import io.github.thibaultmeyer.cuid.CUID;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 public class ReferenceMark {
     public static final String[] PREFIXES = {"JABREF_", "CID_"};
     public static final String IN_TEXT_MARKER = "IN_TEXT";
+    public static final String EMPTY_MARKER = "EMPTY";
+    public static final String NORMAL_MARKER = "NORMAL";
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ReferenceMark.class);
 
     private static final Pattern REFERENCE_MARK_FORMAT = Pattern.compile(
-            "^(JABREF_[\\w-:—./–]+ CID_\\d+(?:, JABREF_[\\w-:—./–]+ CID_\\d+)*) (\\w+)(?: (" + IN_TEXT_MARKER + "))?$",
+            "^(JABREF_[\\w-:—./–]+ CID_\\d+(?:, JABREF_[\\w-:—./–]+ CID_\\d+)*) (\\w+)(?: (" + IN_TEXT_MARKER + "|" + EMPTY_MARKER + "|" + NORMAL_MARKER + "))?$",
             Pattern.UNICODE_CHARACTER_CLASS);
 
     private static final Pattern ENTRY_PATTERN = Pattern.compile(
@@ -28,7 +32,7 @@ public class ReferenceMark {
     private List<String> citationKeys;
     private List<Integer> citationNumbers;
     private String uniqueId;
-    private boolean inText;
+    private CSLCitationType citationType;
 
     /// - Single entry: `JABREF_{citationKey} CID_{citationNumber} {uniqueId}`
     /// - Group of entries: `JABREF_{citationKey1} CID_{citationNumber1}, JABREF_{citationKey2} CID_{citationNumber2}, ..., JABREF_{citationKeyN} CID_{citationNumberN} {uniqueId}`
@@ -41,12 +45,12 @@ public ReferenceMark(String name) {
         parse(name);
     }
 
-    public ReferenceMark(String name, List<String> citationKeys, List<Integer> citationNumbers, String uniqueId, boolean inText) {
+    public ReferenceMark(String name, List<String> citationKeys, List<Integer> citationNumbers, String uniqueId, CSLCitationType citationType) {
         this.name = name;
         this.citationKeys = citationKeys;
         this.citationNumbers = citationNumbers;
         this.uniqueId = uniqueId;
-        this.inText = inText;
+        this.citationType = citationType;
     }
 
     private void parse(String name) {
@@ -56,13 +60,25 @@ private void parse(String name) {
             this.citationKeys = List.of(CUID.randomCUID2(8).toString());
             this.citationNumbers = List.of(0);
             this.uniqueId = this.citationKeys.getFirst();
-            this.inText = false;
+            this.citationType = CSLCitationType.NORMAL;
             return;
         }
 
         String entriesString = matcher.group(1).trim();
         this.uniqueId = matcher.group(2) != null ? matcher.group(2).trim() : CUID.randomCUID2(8).toString();
-        this.inText = matcher.group(3) != null;
+
+        String citationTypeMarker = matcher.group(3);
+        if (citationTypeMarker == null) {
+            citationTypeMarker = NORMAL_MARKER;
+        }
+        this.citationType = switch (citationTypeMarker) {
+            case IN_TEXT_MARKER ->
+                    CSLCitationType.IN_TEXT;
+            case EMPTY_MARKER ->
+                    CSLCitationType.EMPTY;
+            default ->
+                    CSLCitationType.NORMAL;
+        };
 
         this.citationKeys = new ArrayList<>();
         this.citationNumbers = new ArrayList<>();
@@ -77,10 +93,10 @@ private void parse(String name) {
             LOGGER.warn("CSLReferenceMark: Failed to parse any entries from name={}. Assuming random values", name);
             this.citationKeys = List.of(CUID.randomCUID2(8).toString());
             this.citationNumbers = List.of(0);
-            this.inText = false;
+            this.citationType = CSLCitationType.NORMAL;
         }
 
-        LOGGER.debug("CSLReferenceMark: citationKeys={} citationNumbers={} uniqueId={} inText={}", getCitationKeys(), getCitationNumbers(), getUniqueId(), isInText());
+        LOGGER.debug("CSLReferenceMark: citationKeys={} citationNumbers={} uniqueId={} citationType={}", getCitationKeys(), getCitationNumbers(), getUniqueId(), getCitationType());
     }
 
     public String getName() {
@@ -100,8 +116,8 @@ public String getUniqueId() {
         return uniqueId;
     }
 
-    public boolean isInText() {
-        return inText;
+    public CSLCitationType getCitationType() {
+        return citationType;
     }
 
     public static Optional<ReferenceMark> of(String name) {
diff --git a/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLCitationOOAdapter.java b/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLCitationOOAdapter.java
@@ -27,6 +27,7 @@
 import com.sun.star.lang.WrappedTargetException;
 import com.sun.star.text.XTextCursor;
 import com.sun.star.text.XTextDocument;
+import com.sun.star.uno.Exception;
 
 /// This class processes CSL citations in JabRef and interacts directly with LibreOffice using an XTextDocument instance.
 /// It is tightly coupled with {@link CSLReferenceMarkManager} for management of reference marks tied to the CSL citations.
@@ -48,9 +49,7 @@ public class CSLCitationOOAdapter {
     private final OpenOfficePreferences openOfficePreferences;
 
     private CitationStyle currentStyle;
-    private boolean styleChanged;
-    private boolean inTextUsed;
-    private boolean inTextNatureChanged;
+    private CSLCitationType citationType;
 
     public CSLCitationOOAdapter(XTextDocument doc, Supplier<List<BibDatabaseContext>> databasesSupplier, OpenOfficePreferences openOfficePreferences, BibEntryTypesManager bibEntryTypesManager) throws WrappedTargetException, NoSuchElementException {
         this.document = doc;
@@ -65,36 +64,42 @@ public CSLCitationOOAdapter(XTextDocument doc, Supplier<List<BibDatabaseContext>
         }
 
         markManager.readAndUpdateExistingMarks();
-        this.inTextUsed = markManager.hasInTextMarks();
+        this.citationType = markManager.getCitationType();
     }
 
-    public void setStyle(CitationStyle newStyle) {
+    /// This method is used to determine whether citation style and citation type should be updated
+    /// Citation type and citation style are extracted into one method for more readability and uniformity
+    public void setCitationStyleParameters(CitationStyle newStyle, CSLCitationType newCitationType) throws CreationException, Exception {
+        boolean styleChanged;
+        boolean citationTypeIsChanged;
+
         if (currentStyle == null || !currentStyle.getName().equals(newStyle.getName())) {
             styleChanged = true;
-            currentStyle = newStyle;
+            this.currentStyle = newStyle;
         } else {
             styleChanged = false;
         }
+
+        if (this.citationType != newCitationType) {
+            this.citationType = newCitationType;
+            citationTypeIsChanged = true;
+        } else {
+            citationTypeIsChanged = false;
+        }
+
+        if (styleChanged || citationTypeIsChanged) {
+            updateAllCitationsWithNewStyle(currentStyle, newCitationType);
+        }
     }
 
     /// Inserts a citation for a group of entries.
     /// Comparable to LaTeX's \cite command.
     public void insertCitation(XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext bibDatabaseContext, BibEntryTypesManager bibEntryTypesManager)
             throws CreationException, com.sun.star.uno.Exception {
-        setStyle(selectedStyle);
-
-        if (inTextUsed) {
-            inTextNatureChanged = true;
-            inTextUsed = false;
-        } else {
-            inTextNatureChanged = false;
-        }
-
+        // If current citation style is not the same as passed-in citation type, then change it to the new citation style
+        // If current citation type is not "NORMAL", then change it to "NORMAL".
         // Placing this at the beginning reduces the number of updates needed by 1 (in the positive case)
-        if (styleChanged || inTextNatureChanged) {
-            updateAllCitationsWithNewStyle(currentStyle, false);
-            styleChanged = false;
-        }
+        setCitationStyleParameters(selectedStyle, CSLCitationType.NORMAL);
 
         String style = selectedStyle.getSource();
         boolean isNumericStyle = selectedStyle.isNumericStyle();
@@ -115,7 +120,7 @@ public void insertCitation(XTextCursor cursor, CitationStyle selectedStyle, List
         }
 
         OOText ooText = OOFormat.setLocaleNone(OOText.fromString(formattedCitation));
-        insertReferences(cursor, entries, ooText, isNumericStyle, false);
+        insertReferences(cursor, entries, ooText, isNumericStyle, CSLCitationType.NORMAL);
     }
 
     /// Inserts in-text citations for a group of entries.
@@ -124,19 +129,7 @@ public void insertCitation(XTextCursor cursor, CitationStyle selectedStyle, List
     /// @implNote Very similar to the {@link #insertCitation(XTextCursor, CitationStyle, List, BibDatabaseContext, BibEntryTypesManager) insertCitation} method.
     public void insertInTextCitation(XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext bibDatabaseContext, BibEntryTypesManager bibEntryTypesManager)
             throws CreationException, com.sun.star.uno.Exception {
-        setStyle(selectedStyle);
-
-        if (!inTextUsed) {
-            inTextUsed = true;
-            inTextNatureChanged = true;
-        } else {
-            inTextNatureChanged = false;
-        }
-
-        if (styleChanged || inTextNatureChanged) {
-            updateAllCitationsWithNewStyle(currentStyle, true);
-            styleChanged = false;
-        }
+        setCitationStyleParameters(selectedStyle, CSLCitationType.IN_TEXT);
 
         String style = selectedStyle.getSource();
         boolean isNumericStyle = selectedStyle.isNumericStyle();
@@ -172,16 +165,18 @@ public void insertInTextCitation(XTextCursor cursor, CitationStyle selectedStyle
             }
 
             OOText ooText = OOFormat.setLocaleNone(OOText.fromString(finalText));
-            insertReferences(cursor, List.of(currentEntry), ooText, isNumericStyle, true);
+            insertReferences(cursor, List.of(currentEntry), ooText, isNumericStyle, CSLCitationType.IN_TEXT);
         }
     }
 
     /// Inserts "empty" citations for a list of entries at the cursor to the document.
     /// Adds the entries to the list for which bibliography is to be generated.
     public void insertEmptyCitation(XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries)
             throws CreationException, com.sun.star.uno.Exception {
+        setCitationStyleParameters(selectedStyle, CSLCitationType.EMPTY);
+
         OOText emptyOOText = OOFormat.setLocaleNone(OOText.fromString(""));
-        insertReferences(cursor, entries, emptyOOText, selectedStyle.isNumericStyle(), false);
+        insertReferences(cursor, entries, emptyOOText, selectedStyle.isNumericStyle(), CSLCitationType.EMPTY);
     }
 
     /// Creates a "Bibliography" section in the document and inserts a list of references.
@@ -196,7 +191,7 @@ public void insertBibliography(XTextCursor cursor, CitationStyle selectedStyle,
 
         markManager.setRealTimeNumberUpdateRequired(isNumericStyle);
         markManager.readAndUpdateExistingMarks();
-        updateAllCitationsWithNewStyle(selectedStyle, inTextUsed);
+        updateAllCitationsWithNewStyle(selectedStyle, citationType);
         markManager.readAndUpdateExistingMarks();
 
         OOText title = OOFormat.paragraph(OOText.fromString(openOfficePreferences.getCslBibliographyTitle()), openOfficePreferences.getCslBibliographyHeaderFormat());
@@ -234,7 +229,7 @@ public void insertBibliography(XTextCursor cursor, CitationStyle selectedStyle,
     }
 
     /// Inserts references and also adds a space before the citation if not already present ("smart space").
-    private void insertReferences(XTextCursor cursor, List<BibEntry> entries, OOText ooText, boolean isNumericStyle, boolean isInText)
+    private void insertReferences(XTextCursor cursor, List<BibEntry> entries, OOText ooText, boolean isNumericStyle, CSLCitationType citationType)
             throws CreationException, com.sun.star.uno.Exception {
         boolean preceedingSpaceExists;
         XTextCursor checkCursor = cursor.getText().createTextCursorByRange(cursor.getStart());
@@ -251,10 +246,10 @@ private void insertReferences(XTextCursor cursor, List<BibEntry> entries, OOText
                 preceedingSpaceExists = checkCursor.getString().matches("\\R");
             }
         }
-        markManager.insertReferenceIntoOO(entries, document, cursor, ooText, !preceedingSpaceExists, openOfficePreferences.getAddSpaceAfter(), isInText);
+        markManager.insertReferenceIntoOO(entries, document, cursor, ooText, !preceedingSpaceExists, openOfficePreferences.getAddSpaceAfter(), citationType);
         markManager.setRealTimeNumberUpdateRequired(isNumericStyle);
         markManager.readAndUpdateExistingMarks();
-        inTextUsed = markManager.hasInTextMarks();
+        this.citationType = markManager.getCitationType();
     }
 
     /// Transforms the numbers in the citation to globally-unique (and thus, reusable) numbers.
@@ -280,7 +275,7 @@ private String updateSingleOrMultipleCitationNumbers(String citation, List<BibEn
     /// However, all "generation" of CSL style citations (via {@link CitationStyleGenerator}) occur in this class, and not in {@link CSLReferenceMarkManager}.
     /// Furthermore, {@link CSLReferenceMarkManager} is not composed of {@link CitationStyle}.
     /// Hence, we keep {@link CSLReferenceMarkManager} independent of {@link CitationStyleGenerator} and {@link CitationStyle}, and keep the following two methods here.
-    private void updateAllCitationsWithNewStyle(CitationStyle style, boolean isInTextStyle)
+    private void updateAllCitationsWithNewStyle(CitationStyle style, CSLCitationType citationType)
             throws com.sun.star.uno.Exception, CreationException {
         boolean isNumericStyle = style.isNumericStyle();
         boolean isAlphaNumericStyle = style.isAlphanumericStyle();
@@ -309,7 +304,11 @@ private void updateAllCitationsWithNewStyle(CitationStyle style, boolean isInTex
         // Next, we get the list of reference marks sorted in order of appearance in the document
         List<CSLReferenceMark> marksInOrder = markManager.getMarksInOrder();
 
-        if (isInTextStyle) {
+        if (citationType == CSLCitationType.EMPTY) {
+            for (CSLReferenceMark mark : marksInOrder) {
+                markManager.updateMarkAndTextWithNewStyle(mark, "", CSLCitationType.EMPTY);
+            }
+        } else if (citationType == CSLCitationType.IN_TEXT) {
             // Now, for each such reference mark, we get the entries to be updated
             for (CSLReferenceMark mark : marksInOrder) {
                 List<String> citationKeys = mark.getCitationKeys();
@@ -350,7 +349,7 @@ private void updateAllCitationsWithNewStyle(CitationStyle style, boolean isInTex
                     }
                 }
 
-                markManager.updateMarkAndTextWithNewStyle(mark, finalText.toString(), isInTextStyle);
+                markManager.updateMarkAndTextWithNewStyle(mark, finalText.toString(), CSLCitationType.IN_TEXT);
             }
         } else {
             // Same flow as above - for each such reference mark, we get the entries to be updated
@@ -373,7 +372,7 @@ private void updateAllCitationsWithNewStyle(CitationStyle style, boolean isInTex
 
                 String formattedCitation = CSLFormatUtils.transformHTML(newCitation);
 
-                markManager.updateMarkAndTextWithNewStyle(mark, formattedCitation, isInTextStyle);
+                markManager.updateMarkAndTextWithNewStyle(mark, formattedCitation, CSLCitationType.NORMAL);
             }
         }
     }
diff --git a/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLCitationType.java b/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLCitationType.java
@@ -0,0 +1,7 @@
+package org.jabref.logic.openoffice.oocsltext;
+
+public enum CSLCitationType {
+    NORMAL,
+    IN_TEXT,
+    EMPTY
+}
diff --git a/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLReferenceMark.java b/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLReferenceMark.java
@@ -17,26 +17,26 @@ public class CSLReferenceMark {
     private XTextContent textContent;
     private final List<String> citationKeys;
     private List<Integer> citationNumbers;
-    private boolean isInText;
+    private CSLCitationType citationType;
 
     public CSLReferenceMark(XNamed named, ReferenceMark referenceMark) {
         this.referenceMark = referenceMark;
         this.textContent = UnoRuntime.queryInterface(XTextContent.class, named);
         this.citationKeys = referenceMark.getCitationKeys();
         this.citationNumbers = referenceMark.getCitationNumbers();
-        this.isInText = referenceMark.isInText();
+        this.citationType = referenceMark.getCitationType();
     }
 
-    public static CSLReferenceMark of(List<String> citationKeys, List<Integer> citationNumbers, boolean inText, XMultiServiceFactory factory) throws Exception {
+    public static CSLReferenceMark of(List<String> citationKeys, List<Integer> citationNumbers, CSLCitationType citationType, XMultiServiceFactory factory) throws Exception {
         String uniqueId = CUID.randomCUID2(8).toString();
-        String name = buildReferenceName(citationKeys, citationNumbers, uniqueId, inText);
+        String name = buildReferenceName(citationKeys, citationNumbers, uniqueId, citationType);
         XNamed named = UnoRuntime.queryInterface(XNamed.class, factory.createInstance("com.sun.star.text.ReferenceMark"));
         named.setName(name);
-        ReferenceMark referenceMark = new ReferenceMark(name, citationKeys, citationNumbers, uniqueId, inText);
+        ReferenceMark referenceMark = new ReferenceMark(name, citationKeys, citationNumbers, uniqueId, citationType);
         return new CSLReferenceMark(named, referenceMark);
     }
 
-    private static String buildReferenceName(List<String> citationKeys, List<Integer> citationNumbers, String uniqueId, boolean inText) {
+    private static String buildReferenceName(List<String> citationKeys, List<Integer> citationNumbers, String uniqueId, CSLCitationType citationType) {
         StringBuilder nameBuilder = new StringBuilder();
         for (int i = 0; i < citationKeys.size(); i++) {
             if (i > 0) {
@@ -46,8 +46,15 @@ private static String buildReferenceName(List<String> citationKeys, List<Integer
                        .append(" ").append(ReferenceMark.PREFIXES[1]).append(citationNumbers.get(i));
         }
         nameBuilder.append(" ").append(uniqueId);
-        if (inText) {
-            nameBuilder.append(" ").append(ReferenceMark.IN_TEXT_MARKER);
+
+        // Embed citation nature into reference mark
+        switch (citationType) {
+            case IN_TEXT ->
+                    nameBuilder.append(" ").append(ReferenceMark.IN_TEXT_MARKER);
+            case EMPTY ->
+                    nameBuilder.append(" ").append(ReferenceMark.EMPTY_MARKER);
+            case NORMAL ->
+                    nameBuilder.append(" ").append(ReferenceMark.NORMAL_MARKER);
         }
         return nameBuilder.toString();
     }
@@ -73,6 +80,6 @@ public void updateTextContent(XTextContent newTextContent) {
     }
 
     public void updateName(String newName) {
-        this.referenceMark = new ReferenceMark(newName, this.citationKeys, this.citationNumbers, this.referenceMark.getUniqueId(), this.isInText);
+        this.referenceMark = new ReferenceMark(newName, this.citationKeys, this.citationNumbers, this.referenceMark.getUniqueId(), this.citationType);
     }
 }
diff --git a/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLReferenceMarkManager.java b/jablib/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLReferenceMarkManager.java
diff --git a/jablib/src/test/java/org/jabref/logic/openoffice/ReferenceMarkTest.java b/jablib/src/test/java/org/jabref/logic/openoffice/ReferenceMarkTest.java
