emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: "András Simonyi" <andras.simonyi@gmail.com>
To: Timothy <orgmode@tec.tecosaur.net>
Cc: Ihor Radchenko <yantar92@posteo.net>, emacs-orgmode@gnu.org
Subject: Re: [PATCH] oc-csl: Improve LaTeX bibliography formatting
Date: Tue, 27 Dec 2022 23:32:45 +0100	[thread overview]
Message-ID: <CAOWRwxBMJkE_bd1Sn2XUDbe6tGvZRA-zmxC_dnqnokyZ-1LuTg@mail.gmail.com> (raw)
In-Reply-To: <CAOWRwxCA9xRnQoYDo8ZTs+03x_FnWB+myG-ERWOg9xadSWm5iA@mail.gmail.com>

[-- Attachment #1: Type: text/plain, Size: 1032 bytes --]

Dear All,
I have attached a new version of the patch with added ascii "illustrations".
best wishes,

On Tue, 13 Dec 2022 at 20:03, András Simonyi <andras.simonyi@gmail.com> wrote:
> Dear All,
> On Tue, 13 Dec 2022 at 17:07, Timothy <orgmode@tec.tecosaur.net> wrote:
> > Perhaps an ASCII approximation in an example block could work? Even if it’s
> > exaggerated to give the idea.
> yes, I'm also thinking of first trying to produce something in ASCII
> as the docstring will probably need it anyway,
> and we can think about the image version afterwards -- it might turn
> out that the text version is already sufficient for the news (and
> maybe later on for the manual).
> best wishes,
> András
> > All the best,
> > Timothy
> >
> > --
> > Timothy (‘tecosaur’/‘TEC’), Org mode contributor.
> > Learn more about Org mode at <https://orgmode.org/>.
> > Support Org development at <https://liberapay.com/org-mode>,
> > or support my work at <https://liberapay.com/tec>.

[-- Attachment #2: 0001-oc-csl-Improve-LaTeX-bibliography-formatting.patch --]
[-- Type: text/x-patch, Size: 10988 bytes --]

From 2bdbb02901b9831f3bb6b3d29ff8050eadd69e46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Tue, 27 Dec 2022 23:15:34 +0100
Subject: [PATCH] oc-csl: Improve LaTeX bibliography formatting

* lisp/oc-csl.el (org-cite-csl--output-format): Use the dedicated
'org-latex' citeproc formatter to export references in LaTeX.
(org-cite-csl-latex-preamble, org-cite-csl--generate-latex-preamble,
org-cite-csl-finalizer): Insert a preamble fragment compatible with
the 'org-latex' citeproc formatter.
org-cite-csl-latex-label-width-per-char): Introduce additional
variables to control bibliography formatting.

* etc/ORG-NEWS: Describe the introduced new options.
 etc/ORG-NEWS   |  27 +++++++++
 lisp/oc-csl.el | 145 +++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 155 insertions(+), 17 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index d4e9b4368..1185a51b2 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,6 +13,33 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
 * Version 9.7 (not released yet)
 ** New options
+*** New custom settings for the "csl" citation export processor's LaTeX output
+The settings ~org-cite-csl-latex-label-separator~ and
+~org-cite-csl-latex-label-width-per-char~ allow the user to control
+the indentation of entries for labeled bibliography styles when the
+"csl" citation processor is used for LaTeX export.  The indentation
+length is computed as the sum of ~org-cite-csl-latex-label-separator~
+and the maximal label width, for example:
+    indentation length
+max. label width  separator
+[Doe22]                    John Doe. A title...
+[DoeSmithJones19]          John Doe, Jane Smith and...
+[SmithDoe02]               Jane Smith and John Doe...
+The maximal label width, in turn, is calculated as the product of
+~org-cite-csl-latex-label-width-per-char~ and the maximal label length
+measured in characters.
+The setting ~org-cite-csl-latex-preamble~ makes it possible to
+customize the entire LaTeX fragment that the "csl" citation processor injects
+into the preamble.
 *** New ~org-latex-listings-src-omit-language~ customization for LaTeX export
 The ~org-latex-listings-src-omit-language~ customization variable
diff --git a/lisp/oc-csl.el b/lisp/oc-csl.el
index 1ccb74e92..11194b9b4 100644
--- a/lisp/oc-csl.el
+++ b/lisp/oc-csl.el
@@ -214,6 +214,111 @@ Used only when `second-field-align' is activated by the used CSL style."
   :type 'string
   :safe #'stringp)
+(defcustom org-cite-csl-latex-label-separator "0.6em"
+  "Distance between citation label and bibliography item for LaTeX
+output in valid LaTeX units.  Used only when `second-field-align'
+is activated by the used CSL style.
+The indentation length in these cases is computed as the sum of
+`org-cite-csl-latex-label-separator' and the maximal label width,
+for example,
+    indentation length
+max. label width  separator
+[Doe22]                    John Doe. A title...
+[DoeSmithJones19]          John Doe, Jane Smith and...
+[SmithDoe02]               Jane Smith and John Doe...
+The maximal label width, in turn, is calculated as the product of
+`org-cite-csl-latex-label-width-per-char' and the maximal label
+length measured in characters."
+  :group 'org-cite
+  :package-version '(Org . "9.7")
+  :type 'string
+  :safe #'stringp)
+(defcustom org-cite-csl-latex-label-width-per-char "0.45em"
+  "Character width in LaTeX units for calculating entry label widths.
+Used only when `second-field-align' is activated by the used CSL
+See the documentation of `org-cite-csl-latex-label-separator' for
+  :group 'org-cite
+  :package-version '(Org . "9.7")
+  :type 'string
+  :safe #'stringp)
+;; The following was inspired by and in many details follows how
+;; Pandoc's (<https://github.com/jgm/pandoc>) default LaTeX template
+;; handles CSL output.  Many thanks to the author, John MacFarlane!
+(defcustom org-cite-csl-latex-preamble
+  "\\usepackage{calc}
+\\setlength{\\csllabelwidth}{[CSL-LABELWIDTH-PER-CHAR] * [CSL-MAXLABEL-CHARS]}
+\\newenvironment{cslbibliography}[2] % 1st arg. is hanging-indent, 2nd entry spacing.
+ {% By default, paragraphs are not indented.
+  \\setlength{\\parindent}{0pt}
+  % Hanging indent is turned on when first argument is 1.
+  \\ifodd #1
+  \\let\\oldpar\\par
+  \\def\\par{\\hangindent=\\cslhangindent\\oldpar}
+  \\fi
+  % Set entry spacing based on the second argument.
+  \\setlength{\\parskip}{\\parskip +  #2\\baselineskip}
+ }%
+ {}
+\\newcommand{\\cslleftmargin}[1]{\\parbox[t]{\\csllabelsep + \\csllabelwidth}{#1}}
+  {\\parbox[t]{\\linewidth - \\csllabelsep - \\csllabelwidth}{#1}\\break}
+  {\\leavevmode\\vadjust pre{\\hypertarget{citeproc_bib_item_#1}{}}#2}
+ {\\protect\\hyper@linkstart{cite}{citeproc_bib_item_#1}#2\\hyper@linkend}
+  "LaTeX preamble content inserted by the `csl' citation processor.
+This preamble can be anything as long as it provides definitions
+for the environment and commands that Citeproc's `org-latex'
+formatter uses for formatting citations and bibliographies.  In
+particular, it has to define
+- the commands \\cslblock{<text>}, \\cslleftmargin{<text>},
+  \\cslrightinline{<text>} and \\cslindent{<text>} for formatting
+  text that have, respectively, the CSL display attributes
+  `block', `left-margin', `right-inline' and `indent';
+- the commands \\cslcitation{<item_no>}{<item_text>} and
+  \\cslbibitem{<item_no>}{<item_text>}, which are used to
+  format individual citations and bibliography items, including
+  hyperlinking citations to the corresponding bibliography entry
+  using their numerical id, which is passed as the first,
+  <item_no> argument;
+- and the environment \\cslbibliography{<hanging-indent>}{<entry-spacing>},
+  in which bibliographies are wrapped; the value of the
+  <hanging-indent> argument is 1 if hanging indent should be
+  applied and 0 if not, while the <entry-spacing> argument is an
+  integer specifying the number of extra line-heights
+  required between bibliography entries in addition to normal
+  line spacing.
+When present, the placeholders [CSL-HANGINDENT], [CSL-LABELSEP],
+respectively, by the contents of the customizable variables
+`org-cite-csl-latex-hanging-indent', `org-cite-csl-latex-label-separator',
+`org-cite-csl-latex-label-width-per-char', and the maximal label length
+in the bibliography measured in characters."
+  :group 'org-cite
+  :type 'string
+  :package-version '(Org . "9.7"))
 ;;; Internal variables
 (defconst org-cite-csl--etc-dir
@@ -413,7 +518,7 @@ corresponding to one of the output formats supported by Citeproc: `html',
   (let ((backend (plist-get info :back-end)))
      ((org-export-derived-backend-p backend 'html) 'html)
-     ((org-export-derived-backend-p backend 'latex) 'latex)
+     ((org-export-derived-backend-p backend 'latex) 'org-latex)
      (t 'org))))
 (defun org-cite-csl--style-file (info)
@@ -670,6 +775,21 @@ value is the bibliography as rendered by Citeproc."
             (plist-put info :cite-citeproc-rendered-bibliographies result)
+(defun org-cite-csl--generate-latex-preamble (info)
+  "Generate the CSL-related part of the LaTeX preamble.
+INFO is the export state, as a property list."
+  (let* ((parameters (cadr (org-cite-csl--rendered-bibliographies info)))
+         (max-offset (cdr (assq 'max-offset parameters)))
+         (result org-cite-csl-latex-preamble))
+    (map-do (lambda (placeholder replacement)
+              (when (string-match placeholder result)
+                (setq result (replace-match replacement t t result))))
+            `("\\[CSL-HANGINDENT\\]" ,org-cite-csl-latex-hanging-indent
+              "\\[CSL-LABELSEP\\]" ,org-cite-csl-latex-label-separator
+              "\\[CSL-LABELWIDTH-PER-CHAR\\]" ,org-cite-csl-latex-label-width-per-char
+              "\\[CSL-MAXLABEL-CHARS\\]" ,(number-to-string max-offset)))
+    result))
 ;;; Export capability
 (defun org-cite-csl-render-citation (citation _style _backend info)
@@ -688,8 +808,8 @@ INFO is the export state, as a property list."
 INFO is the export state, as a property list."
   (pcase-let*  ((format (org-cite-csl--output-format info))
-		(`(,outputs ,parameters) (org-cite-csl--rendered-bibliographies info))
-		(output (cdr (assoc props outputs))))
+                (`(,outputs ,parameters) (org-cite-csl--rendered-bibliographies info))
+                (output (cdr (assoc props outputs))))
     (pcase format
@@ -714,12 +834,7 @@ INFO is the export state, as a property list."
-      ('latex
-       (if (cdr (assq 'hanging-indent parameters))
-           (format "\\begin{hangparas}{%s}{1}\n%s\n\\end{hangparas}"
-                   org-cite-csl-latex-hanging-indent
-                   output)
-         output))
+      ('org-latex output)
        ;; Parse Org output to re-export it during the regular export
        ;; process.
@@ -730,18 +845,14 @@ INFO is the export state, as a property list."
 OUTPUT is the export document, as a string.  INFO is the export state, as a
 property list."
-  (if (not (eq 'latex (org-cite-csl--output-format info)))
+  (if (not (eq 'org-latex (org-cite-csl--output-format info)))
       (save-excursion (insert output))
       (when (search-forward "\\begin{document}" nil t)
-        (goto-char (match-beginning 0))
-        ;; Ensure that \citeprocitem is defined for citeproc-el.
-        (insert "\\makeatletter\n\\newcommand{\\citeprocitem}[2]{\\hyper@linkstart{cite}{citeproc_bib_item_#1}#2\\hyper@linkend}\n\\makeatother\n\n")
-        ;; Ensure there is a \usepackage{hanging} somewhere or add one.
-        (let ((re (rx "\\usepackage" (opt "[" (*? nonl) "]") "{hanging}")))
-          (unless (re-search-backward re nil t)
-            (insert "\\usepackage[notquote]{hanging}\n"))))
+	(goto-char (match-beginning 0))
+	;; Insert the CSL-specific parts of the LaTeX preamble.
+	(insert (org-cite-csl--generate-latex-preamble info)))

  reply	other threads:[~2022-12-27 22:33 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-11-06  9:42 [PATCH] oc-csl: Improve LaTeX bibliography formatting András Simonyi
2022-11-07  2:47 ` Ihor Radchenko
2022-11-07 11:15   ` András Simonyi
2022-11-08  5:26     ` Ihor Radchenko
2022-12-11 19:00       ` András Simonyi
2022-12-12  9:07         ` Ihor Radchenko
2022-12-12 11:15           ` András Simonyi
2022-12-12 11:24             ` Ihor Radchenko
2022-12-29 15:40               ` Bastien Guerry
2022-12-31 12:22                 ` Screenshots in ORG-NEWS (was: [PATCH] oc-csl: Improve LaTeX bibliography formatting) Ihor Radchenko
2023-01-02 15:11                   ` Screenshots in ORG-NEWS Bastien
2023-01-03 10:34                     ` Ihor Radchenko
2023-01-03 12:36                       ` Bastien
2022-12-13 16:05           ` [PATCH] oc-csl: Improve LaTeX bibliography formatting Timothy
2022-12-13 19:03             ` András Simonyi
2022-12-27 22:32               ` András Simonyi [this message]
2022-12-29 10:14                 ` Ihor Radchenko
2022-12-29 21:51                   ` András Simonyi

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CAOWRwxBMJkE_bd1Sn2XUDbe6tGvZRA-zmxC_dnqnokyZ-1LuTg@mail.gmail.com \
    --to=andras.simonyi@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=orgmode@tec.tecosaur.net \
    --cc=yantar92@posteo.net \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).