[PATCH] oc-csl: Add support for sub-bibliographies

[PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

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

Dear All,

the attached patch adds support for filter-based sub-bibliographies in the "csl"
org-cite export processor. It supports the same syntax for specifying
filters as the biblatex processor and supports some of the biblatex
filter types, concretely, entry-type and keyword based filtering. It
also supports filtering based on CSL type (as opposed to bib(la)tex
type) and using any Lisp predicate as a filter.

best wishes,
András

[-- Attachment #2: 0001-oc-csl.el-Add-support-for-sub-bibliographies.patch --]
[-- Type: text/x-patch, Size: 7968 bytes --]

From 50db7f8ae94cf9a3799eccdf3d7ee69a2e7c4505 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Mon, 11 Jul 2022 19:13:48 +0200
Subject: [PATCH] oc-csl.el: Add support for sub-bibliographies

* lisp/oc-csl.el (org-cite-csl--rendered-bibliographies): New function
to collect all #+print_bibliography keywords with their properties and
call Citeproc to render all sub-bibliographies in one go as required
by the API.  Return the formatted bibliographies as values in an alist
in which keys are the #+print_bibliography keyword options as plists.
Cache the return value in the export communication channel.
(org-cite-csl--bibliography-filter): New helper function to convert
plists representing #+print_bibliography options to the alist filter
form expected by Citeproc.
(org-cite-csl--rendered-citations): Call
`org-cite-csl--rendered-bibliographies' before rendering citations to
make sure that the complete sub-bibliography information is added to
the processor and, therefore, citation numbers are correct.
(org-cite-csl--render-bibliography): Instead of directly calling
Citeproc to render the bibliography, call
`org-cite-csl--rendered-bibliographies' and retrieve the formatted
bibliography from its return value based on the options passed as the
`props' argument.
---
 etc/ORG-NEWS   | 13 +++++++-
 lisp/oc-csl.el | 83 +++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 88 insertions(+), 8 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 4cda357f1..ce8675dea 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -239,7 +239,7 @@ This behaviour can be changed by supplying a =:align= parameter.
 
 The tabbing environment can be useful when generating simple tables which
 can be span multiple pages and when table cells are allowed to overflow.
-*** Support for =nocite= citations in the "csl" export processor
+*** Support for =nocite= citations and sub-bibliographies in the "csl" export processor
 
 The "csl" citation export processor now supports =nocite= style
 citations that add items to the printed bibliography without visible
@@ -251,6 +251,17 @@ instance,
 #+end_src
 
 includes all available items in the printed bibliography.
+
+The "csl" export processor now also supports sub-bibliographies that
+show only a subset of the references based on some criterion.  For
+example,
+
+#+begin_src org
+#+print_bibliography: :type book :keyword ai
+#+end_src
+
+prints a sub-bibliography containing the book entries with =ai= among
+their keywords.
 ** New functions and changes in function arguments
 
 *** New function ~org-element-cache-map~ for quick mapping across Org elements
diff --git a/lisp/oc-csl.el b/lisp/oc-csl.el
index a2bd6653c..0b2fe5c41 100644
--- a/lisp/oc-csl.el
+++ b/lisp/oc-csl.el
@@ -90,11 +90,23 @@
 ;; The part of the suffix before the locator is appended to reference's prefix.
 ;; If no locator term is used, but a number is present, then "page" is assumed.
 
+;; Filtered sub-bibliographies can be printed by passing filtering
+;; options to the "print_bibliography" keywords.  E.g.,
+;;
+;;    #+print_bibliography: :type book keyword: emacs
+;;
+;; If you need to use a key multiple times, you can separate its
+;; values with commas, but without any space in-between:
+;;
+;;    #+print_bibliography: :keyword abc,xyz :type article
+
 ;; This library was heavily inspired by and borrows from András Simonyi's
 ;; Citeproc Org (<https://github.com/andras-simonyi/citeproc-org>) library.
 ;; Many thanks to him!
 
 ;;; Code:
+(require 'cl-lib)
+(require 'map)
 (require 'bibtex)
 (require 'json)
 (require 'oc)
@@ -559,6 +571,10 @@ OUTPUT using Citeproc."
 	  (citeproc-append-citations structures processor))
 	(when nocite-ids
 	  (citeproc-add-uncited nocite-ids processor))
+        ;; All bibliographies have to be rendered in order to have
+        ;; correct citation numbers even if there are several
+        ;; sub-bibliograhies.
+        (org-cite-csl--rendered-bibliographies info)
 	(let (result
 	      (rendered (citeproc-render-citations
 			 processor
@@ -572,6 +588,62 @@ OUTPUT using Citeproc."
 	  (plist-put info :cite-citeproc-rendered-citations result)
 	  result))))
 
+(defun org-cite-csl--bibliography-filter (bib-props)
+  "Return the sub-bibliography filter corresponding to bibliography properties.
+
+BIB-PROPS should be a plist representing the properties
+associated with a \"print_bibliography\" keyword, as returned by
+`org-cite-bibliography-properties'."
+  (let (result
+	(remove-keyword-colon (lambda (x) (intern (substring (symbol-name x) 1)))))
+    (map-do
+     (lambda (key value)
+       (pcase key
+         ((or :keyword :notkeyword :nottype :notcsltype :filter)
+          (dolist (v (split-string value ","))
+	    (push (cons  (funcall remove-keyword-colon key) v) result)))
+         ((or :type :csltype)
+          (if (string-match-p "," value)
+              (user-error "The \"%s\" print_bibliography option does not support comma-separated values" key)
+            (push (cons (funcall remove-keyword-colon key) value) result)))))
+     bib-props)
+    result))
+
+(defun org-cite-csl--rendered-bibliographies (info)
+  "Return the rendered bibliographies.
+
+INFO is the export state, as a property list.
+
+Return an (OUTPUTS PARAMETERS) list where OUTPUTS is an alist
+of (BIB-PROPS . OUTPUT) pairs where each key is a property list
+of a \"print_bibliography\" keyword and the corresponding OUTPUT
+value is the bibliography as rendered by Citeproc."
+  (or (plist-get info :cite-citeproc-rendered-bibliographies)
+      (let (bib-plists bib-filters)
+        ;; Collect bibliography property lists and the corresponding
+        ;; Citeproc sub-bib filters.
+	(org-element-map (plist-get info :parse-tree) 'keyword
+          (lambda (keyword)
+            (when (equal "PRINT_BIBLIOGRAPHY" (org-element-property :key keyword))
+              (let ((bib-plist (org-cite-bibliography-properties keyword)))
+                (push bib-plist bib-plists)
+                (push (org-cite-csl--bibliography-filter bib-plist) bib-filters)))))
+        (setq bib-filters (nreverse bib-filters)
+              bib-plists (nreverse bib-plists))
+        ;; Render and return all bibliographies.
+        (let ((processor (org-cite-csl--processor info)))
+          (citeproc-add-subbib-filters bib-filters processor)
+          (pcase-let* ((format (org-cite-csl--output-format info))
+                       (`(,rendered-bibs . ,parameters)
+                        (citeproc-render-bib
+                         (org-cite-csl--processor info)
+                         format
+                         (org-cite-csl--no-citelinks-p info)))
+                       (outputs (cl-mapcar #'cons bib-plists rendered-bibs))
+                       (result (list outputs parameters)))
+            (plist-put info :cite-citeproc-rendered-bibliographies result)
+            result)))))
+
 \f
 ;;; Export capability
 (defun org-cite-csl-render-citation (citation _style _backend info)
@@ -585,16 +657,13 @@ INFO is the export state, as a property list."
       ;; process.
       (org-cite-parse-objects output))))
 
-(defun org-cite-csl-render-bibliography (_keys _files _style _props _backend info)
+(defun org-cite-csl-render-bibliography (_keys _files _style props _backend info)
   "Export bibliography.
 INFO is the export state, as a property list."
   (org-cite-csl--barf-without-citeproc)
-  (pcase-let* ((format (org-cite-csl--output-format info))
-               (`(,output . ,parameters)
-                (citeproc-render-bib
-                 (org-cite-csl--processor info)
-                 format
-                 (org-cite-csl--no-citelinks-p info))))
+  (pcase-let*  ((format (org-cite-csl--output-format info))
+		(`(,outputs ,parameters) (org-cite-csl--rendered-bibliographies info))
+		(output (cdr (assoc props outputs))))
     (pcase format
       ('html
        (concat
-- 
2.25.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

> the attached patch adds support for filter-based sub-bibliographies in the "csl"
> org-cite export processor. It supports the same syntax for specifying
> filters as the biblatex processor and supports some of the biblatex
> filter types, concretely, entry-type and keyword based filtering. It
> also supports filtering based on CSL type (as opposed to bib(la)tex
> type) and using any Lisp predicate as a filter.

Thanks! LGTM!

Can you please also document the new feature in the manual? Especially,
the CLS-specific filter options. It is not clear what are they.

Best,
Ihor

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

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

Dear All,

On Sat, 16 Jul 2022 at 10:43, Ihor Radchenko <yantar92@gmail.com> wrote:
any Lisp predicate as a filter.

> Thanks! LGTM!
>
> Can you please also document the new feature in the manual? Especially,
> the CLS-specific filter options. It is not clear what are they.

many thanks for looking into the patch! I've attached a rather
speculative patch documenting "PRINT_BIBLIOGRAPHY" options in the
manual including the ones added by my first patch. I'm unsure about a
lot of things (e.g., maybe it's too detailed about the CSL options),
but perhaps it's a useful starting point.

best wishes,
András

[-- Attachment #2: 0001-doc-org-manual.org-Document-PRINT_BIBLIOGRAPHY-optio.patch --]
[-- Type: text/x-patch, Size: 2576 bytes --]

From c77494b8bff82433d4bf23631ab67e5ff3ece581 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Wed, 20 Jul 2022 23:54:32 +0200
Subject: [PATCH] * doc/org-manual.org: Document "PRINT_BIBLIOGRAPHY" options

---
 doc/org-manual.org | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 26d18f533..c4f262dd0 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16815,6 +16815,49 @@ should print.
 
 : #+print_bibliography:
 
+The "biblatex" and "csl" export processors support passing additional
+bibliography options through a property list attached to the
+=PRINT_BIBLIOGRAPHY= keyword.  E.g.,
+
+: #+print_bibliography: :type book :keyword algebra
+
+Values including spaces must be surrounded with double quotes.  If you
+need to use a key multiple times, you can separate its values with
+commas, but without any space in-between:
+
+: #+print_bibliography: :keyword algebra,logic :title "Primary Sources"
+
+A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords
+with or without additional options.  The "biblatex" export processor
+accepts all options supported by BibLaTeX's ~\printbibliography~
+command, while the "csl" processor accepts the following ones:
+
+- =:keyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field contains all given keywords.
+
+- =:notkeyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field does not contain any of the given keywords.
+
+- =:type <entrytype>= :: Print only entries whose type is
+  =<entrytype>=.  Entry type is the BibTeX/BibLaTeX entry type if this
+  information is available (the entry was read from a BibTeX/BibLaTeX
+  bibliography) and the CSL entry type otherwise.
+
+- =:nottype <entrytype(,entrytype2...)>= :: Print only entries whose
+  type is not among the given entry types.  Entry type is determined
+  as in the case of =:type=.
+
+- =:csltype <entrytype>= :: Print only entries whose CSL entry type
+  (possibly based on a conversion from BibTeX/BibLaTeX to CSL) is
+  =<entrytype>=.
+
+- =:notcsltype <entrytype(,entrytype2)>= :: Print only entries whose
+  CSL entry type (possibly based on a conversion from BibTeX/BibLaTeX
+  to CSL) is not among the listed entry types.
+
+- =:filter <predicate>= :: Print only entries for which the given
+  Emacs Lisp predicate returns a non-~nil~ value.
+
 * Working with Source Code
 :PROPERTIES:
 :DESCRIPTION: Export, evaluate, and tangle code blocks.
-- 
2.25.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

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

...of course, I managed to leave a typo in the manual patch, please
ignore the earlier version and consider the attached one.

best wishes,
András

On Thu, 21 Jul 2022 at 00:03, András Simonyi <andras.simonyi@gmail.com> wrote:
>
> Dear All,
>
> On Sat, 16 Jul 2022 at 10:43, Ihor Radchenko <yantar92@gmail.com> wrote:
> any Lisp predicate as a filter.
>
> > Thanks! LGTM!
> >
> > Can you please also document the new feature in the manual? Especially,
> > the CLS-specific filter options. It is not clear what are they.
>
> many thanks for looking into the patch! I've attached a rather
> speculative patch documenting "PRINT_BIBLIOGRAPHY" options in the
> manual including the ones added by my first patch. I'm unsure about a
> lot of things (e.g., maybe it's too detailed about the CSL options),
> but perhaps it's a useful starting point.
>
> best wishes,
> András

[-- Attachment #2: 0001-doc-org-manual.org-Document-PRINT_BIBLIOGRAPHY-optio.patch --]
[-- Type: text/x-patch, Size: 2579 bytes --]

From c5e7cc0cd30795bead429037216390237382cc38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Wed, 20 Jul 2022 23:54:32 +0200
Subject: [PATCH] * doc/org-manual.org: Document "PRINT_BIBLIOGRAPHY" options

---
 doc/org-manual.org | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 26d18f533..c43d1d574 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16815,6 +16815,49 @@ should print.
 
 : #+print_bibliography:
 
+The "biblatex" and "csl" export processors support passing additional
+bibliography options through a property list attached to the
+=PRINT_BIBLIOGRAPHY= keyword.  E.g.,
+
+: #+print_bibliography: :type book :keyword algebra
+
+Values including spaces must be surrounded with double quotes.  If you
+need to use a key multiple times, you can separate its values with
+commas, but without any space in-between:
+
+: #+print_bibliography: :keyword algebra,logic :title "Primary Sources"
+
+A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords
+with or without additional options.  The "biblatex" export processor
+accepts all options supported by BibLaTeX's ~\printbibliography~
+command, while the "csl" processor accepts the following ones:
+
+- =:keyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field contains all given keywords.
+
+- =:notkeyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field does not contain any of the given keywords.
+
+- =:type <entrytype>= :: Print only entries whose type is
+  =<entrytype>=.  Entry type is the BibTeX/BibLaTeX entry type if this
+  information is available (the entry was read from a BibTeX/BibLaTeX
+  bibliography) and the CSL entry type otherwise.
+
+- =:nottype <entrytype(,entrytype2...)>= :: Print only entries whose
+  type is not among the given entry types.  Entry type is determined
+  as in the case of =:type=.
+
+- =:csltype <entrytype>= :: Print only entries whose CSL entry type
+  (possibly based on a conversion from BibTeX/BibLaTeX to CSL) is
+  =<entrytype>=.
+
+- =:notcsltype <entrytype(,entrytype2...)>= :: Print only entries whose
+  CSL entry type (possibly based on a conversion from BibTeX/BibLaTeX
+  to CSL) is not among the listed entry types.
+
+- =:filter <predicate>= :: Print only entries for which the given
+  Emacs Lisp predicate returns a non-~nil~ value.
+
 * Working with Source Code
 :PROPERTIES:
 :DESCRIPTION: Export, evaluate, and tangle code blocks.
-- 
2.25.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

> ...of course, I managed to leave a typo in the manual patch, please
> ignore the earlier version and consider the attached one.

Thanks!
Could you please create a dedicated subsection under "15 Citation
handling" instead of documenting PRINT_BIBLIOGRAPHY together with export
processors? The section should contain a general overview of what
PRINT_BIBLIOGRAPHY does and that it can appear multiple times. Then,
further sub-sub-section will detail on CSL and LaTeX-based processors.

> +The "biblatex" and "csl" export processors support passing additional
> +bibliography options through a property list attached to the
> +=PRINT_BIBLIOGRAPHY= keyword.  E.g.,

Please use "for example" instead of e.g. Not everyone knows Latin or
technical English.

Best,
Ihor

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

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

Dear All,

On Sat, 23 Jul 2022 at 05:59, Ihor Radchenko <yantar92@gmail.com> wrote:
> Could you please create a dedicated subsection under "15 Citation> handling" instead of documenting PRINT_BIBLIOGRAPHY together with export
> processors? The section should contain a general overview of what
> PRINT_BIBLIOGRAPHY does and that it can appear multiple times. Then,
> further sub-sub-section will detail on CSL and LaTeX-based processors.

Dear Ihor, thanks a lot for your comments, I've attached a new version
in which I tried to implement your suggestions.

best wishes,
András

[-- Attachment #2: 0001-doc-org-manual.org-Document-PRINT_BIBLIOGRAPHY-optio.patch --]
[-- Type: text/x-patch, Size: 3282 bytes --]

From d77255421e05f8e1f090e89b17334aed0bdf4fe4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Wed, 20 Jul 2022 23:54:32 +0200
Subject: [PATCH] * doc/org-manual.org: Document "PRINT_BIBLIOGRAPHY" options

---
 doc/org-manual.org | 56 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 26d18f533..e45acc0f0 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16810,11 +16810,65 @@ conformant to the Harvard style and the specification of the
 Wolkers-Kluwer publisher; since it relies on the ~bibtex~ processor of
 your LaTeX installation, it won't export to anything but PDF.
 
+** Bibliography printing 
+
 The =PRINT_BIBLIOGRAPHY= keyword specifies where the bibliography
-should print.
+should print (note the colon):
 
 : #+print_bibliography:
 
+A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords,
+and the keyword can be used with or without additional options.
+Options can be used, for example, to print only entries that belong to
+a certain category or control formatting.  The set of supported
+=PRINT_BIBLIOGRAPHY= options and their interpretation varies between
+the different citation export processors, and several of them do not
+support passing options at all.
+
+*** Bibliography options
+
+The "biblatex" and "csl" export processors support bibliography
+options through a property list attached to the =PRINT_BIBLIOGRAPHY=
+keyword.  For example,
+
+: #+print_bibliography: :type book :keyword algebra
+
+Values including spaces must be surrounded with double quotes.  If you
+need to use a key multiple times, you can separate its values with
+commas, but without any space in-between:
+
+: #+print_bibliography: :keyword algebra,logic :title "Primary Sources"
+
+The "biblatex" export processor accepts all options supported by
+BibLaTeX's ~\printbibliography~ command, while the "csl" processor
+accepts the following ones:
+
+- =:keyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field contains all given keywords.
+
+- =:notkeyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field does not contain any of the given keywords.
+
+- =:type <entrytype>= :: Print only entries whose type is
+  =<entrytype>=.  Entry type is the BibTeX/BibLaTeX entry type if this
+  information is available (the entry was read from a BibTeX/BibLaTeX
+  bibliography) and the CSL entry type otherwise.
+
+- =:nottype <entrytype(,entrytype2...)>= :: Print only entries whose
+  type is not among the given entry types.  Entry type is determined
+  as in the case of =:type=.
+
+- =:csltype <entrytype>= :: Print only entries whose CSL entry type
+  (possibly based on a conversion from BibTeX/BibLaTeX to CSL) is
+  =<entrytype>=.
+
+- =:notcsltype <entrytype(,entrytype2...)>= :: Print only entries whose
+  CSL entry type (possibly based on a conversion from BibTeX/BibLaTeX
+  to CSL) is not among the listed entry types.
+
+- =:filter <predicate>= :: Print only entries for which the given
+  Emacs Lisp predicate returns a non-~nil~ value.
+
 * Working with Source Code
 :PROPERTIES:
 :DESCRIPTION: Export, evaluate, and tangle code blocks.
-- 
2.25.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

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

András Simonyi <andras.simonyi@gmail.com> writes:

> Dear Ihor, thanks a lot for your comments, I've attached a new version
> in which I tried to implement your suggestions.

Thanks!

I have made some changes to the patch, mostly fixing grammar issues (the
ones I can notice). I also changed the sub-section from "Bibliography
options" to "Bibliography options in "biblatex" and "csl" export processors"

See the attached.

Reading through the patch, I noticed that :title option is not
documented. Does it mean :title is not supported by csl processor?

Best,
Ihor


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Document-PRINT_BIBLIOGRAPHY-optio.patch --]
[-- Type: text/x-patch, Size: 3448 bytes --]

From f0217cc4dafa9dbb2eaa3fd22c1270d34aac109d Mon Sep 17 00:00:00 2001
Message-Id: <f0217cc4dafa9dbb2eaa3fd22c1270d34aac109d.1658648142.git.yantar92@gmail.com>
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Wed, 20 Jul 2022 23:54:32 +0200
Subject: [PATCH] * doc/org-manual.org: Document "PRINT_BIBLIOGRAPHY" options

---
 doc/org-manual.org | 58 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index d5bd9092f..1e08c316b 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16818,11 +16818,67 @@ ** Citation export processors
 Wolkers-Kluwer publisher; since it relies on the ~bibtex~ processor of
 your LaTeX installation, it won't export to anything but PDF.
 
+** Printing bibliography
+
 The =PRINT_BIBLIOGRAPHY= keyword specifies where the bibliography
-should print.
+should be printed (note the colon):
 
 : #+print_bibliography:
 
+A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords.
+Each of the keywords will trigger printing the bibliography.
+
+The keywords can be used with or without additional options.  Options
+can be used, for example, to print only entries that belong to a
+certain category or to control formatting.  The set of supported
+=PRINT_BIBLIOGRAPHY= options and their interpretation varies between
+the different citation export processors.  Some export processors do
+not support passing options.
+
+*** Bibliography options in "biblatex" and "csl" export processors
+
+The "biblatex" and "csl" export processors support bibliography
+options through a property list attached to the =PRINT_BIBLIOGRAPHY=
+keyword.  For example,
+
+: #+print_bibliography: :type book :keyword algebra
+
+Values including spaces must be surrounded with double quotes.  If you
+need to use a key multiple times, you can separate its values with
+commas, but without any space in-between:
+
+: #+print_bibliography: :keyword algebra,logic :title "Primary Sources"
+
+The "biblatex" export processor accepts all options supported by
+BibLaTeX's ~\printbibliography~ command, while the "csl" processor
+accepts the following ones:
+
+- =:keyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field contains all given keywords.
+
+- =:notkeyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field does not contain any of the given keywords.
+
+- =:type <entrytype>= :: Print only entries whose type is
+  =<entrytype>=.  Entry type is the BibTeX/BibLaTeX entry type if this
+  information is available (the entry was read from a BibTeX/BibLaTeX
+  bibliography) and the CSL entry type otherwise.
+
+- =:nottype <entrytype(,entrytype2...)>= :: Print only entries whose
+  type is not among the given entry types.  Entry type is determined
+  as in the case of =:type=.
+
+- =:csltype <entrytype>= :: Print only entries whose CSL entry type
+  (possibly based on a conversion from BibTeX/BibLaTeX to CSL) is
+  =<entrytype>=.
+
+- =:notcsltype <entrytype(,entrytype2...)>= :: Print only entries whose
+  CSL entry type (possibly based on a conversion from BibTeX/BibLaTeX
+  to CSL) is not among the listed entry types.
+
+- =:filter <predicate>= :: Print only entries for which the given
+  Emacs Lisp predicate returns a non-~nil~ value.
+
 * Working with Source Code
 :PROPERTIES:
 :DESCRIPTION: Export, evaluate, and tangle code blocks.
-- 
2.35.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

Dear All,

On Sun, 24 Jul 2022 at 09:41, Ihor Radchenko <yantar92@gmail.com> wrote:
>
> Thanks!
>
> I have made some changes to the patch, mostly fixing grammar issues (the
> ones I can notice). I also changed the sub-section from "Bibliography
> options" to "Bibliography options in "biblatex" and "csl" export processors"
>
> See the attached.

Thanks a lot for the improvements! The only suggested change which I'm
not sure about is the renaming of the section "Bibliography printing"
to "Printing bibliography" Neither of them are ideal but it's
difficult to find a formulation which sounds OK and is noncommittal
regarding the number of bibliographies (a single one vs. several). Of
the two, I feel that "Printing bibliography" is slightly worse because
of the missing determiner before "bibliography", maybe "Printing
bibliographies" would be better? Admittedly, as a non-native user of
English my intuitions do not count for much, so it'd be nice to hear
the opinion of some of the native speaker list members.

> Reading through the patch, I noticed that :title option is not
> documented. Does it mean :title is not supported by csl processor?

yes :title is not supported by the "csl" processor. Should we perhaps
replace the example with another one using a multi-word keyword, like

:  #+print_bibliography: :nottype proceedings,article :keyword "algebraic logic"

WDTY?
best wishes,
András

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Bruce D'Arcus]

On Mon, Jul 25, 2022 at 2:26 PM András Simonyi <andras.simonyi@gmail.com> wrote:
>
> Dear All,
>
> On Sun, 24 Jul 2022 at 09:41, Ihor Radchenko <yantar92@gmail.com> wrote:
> >
> > Thanks!
> >
> > I have made some changes to the patch, mostly fixing grammar issues (the
> > ones I can notice). I also changed the sub-section from "Bibliography
> > options" to "Bibliography options in "biblatex" and "csl" export processors"
> >
> > See the attached.
>
> Thanks a lot for the improvements! The only suggested change which I'm
> not sure about is the renaming of the section "Bibliography printing"
> to "Printing bibliography" Neither of them are ideal but it's
> difficult to find a formulation which sounds OK and is noncommittal
> regarding the number of bibliographies (a single one vs. several). Of
> the two, I feel that "Printing bibliography" is slightly worse because
> of the missing determiner before "bibliography", maybe "Printing
> bibliographies" would be better? Admittedly, as a non-native user of
> English my intuitions do not count for much, so it'd be nice to hear
> the opinion of some of the native speaker list members.

I'm a native speaker.

I think "Bibliography printing" sounds like the best option, since it
doesn't really preclude there are multiple.

"Printing bibliographies" would also be OK.

I don't think "Printing bibliography" really works.

Bruce

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Fraga, Eric]

"Printing a bibliography" would also work.
-- 
: Eric S Fraga, with org release_9.5.4-648-gdf1814 in Emacs 29.0.50

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

>> See the attached.
>
> Thanks a lot for the improvements! The only suggested change which I'm
> not sure about is the renaming of the section "Bibliography printing"
> to "Printing bibliography" Neither of them are ideal but it's
> difficult to find a formulation which sounds OK and is noncommittal
> regarding the number of bibliographies (a single one vs. several). Of
> the two, I feel that "Printing bibliography" is slightly worse because
> of the missing determiner before "bibliography", maybe "Printing
> bibliographies" would be better? Admittedly, as a non-native user of
> English my intuitions do not count for much, so it'd be nice to hear
> the opinion of some of the native speaker list members.

I am also a non-native speaker, so lets obey the Bruce's judgment.

>> Reading through the patch, I noticed that :title option is not
>> documented. Does it mean :title is not supported by csl processor?
>
> yes :title is not supported by the "csl" processor. Should we perhaps
> replace the example with another one using a multi-word keyword, like
>
> :  #+print_bibliography: :nottype proceedings,article :keyword "algebraic logic"
>
> WDTY?

An example without :title will be less confusing.

Though I am wondering why csl does not support :title. It feels like a
natural thing to have.

Best,
Ihor

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

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

Dear All,

On Tue, 26 Jul 2022 at 07:37, Ihor Radchenko <yantar92@gmail.com> wrote:
> I am also a non-native speaker, so lets obey the Bruce's judgment.
...
> > yes :title is not supported by the "csl" processor. Should we perhaps
> > replace the example with another one using a multi-word keyword, like

I've attached a new version of the patch with
- "Bibliography printing" as the subsection title,
- an added "the" in the subsubsection title "Bibliography options in
the "biblatex" and "csl" export processors",
- an improved example.

> Though I am wondering why csl does not support :title. It feels like a
> natural thing to have.

The biblatex "title" option is for changing the title of the
bibliography section which is created and printed out by biblatex by
default.
In contrast to the LaTeX-based export processors, the "csl"  and  the
"basic" export processors print out only the list of entries, and it's
up to the user to manually include a bibliography section heading in
the document if they want one, so the "title" option is not really
applicable, at least not in the same way.

best wishes,
András

[-- Attachment #2: 0001-doc-org-manual.org-Document-PRINT_BIBLIOGRAPHY-optio.patch --]
[-- Type: text/x-patch, Size: 3393 bytes --]

From 89af0b909b8d16486a488470c5f9dd2d185379b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Thu, 28 Jul 2022 22:50:26 +0200
Subject: [PATCH] * doc/org-manual.org: Document "PRINT_BIBLIOGRAPHY" options

---
 doc/org-manual.org | 58 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 596ab3723..c740750a2 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16818,11 +16818,67 @@ conformant to the Harvard style and the specification of the
 Wolkers-Kluwer publisher; since it relies on the ~bibtex~ processor of
 your LaTeX installation, it won't export to anything but PDF.
 
+** Bibliography printing
+
 The =PRINT_BIBLIOGRAPHY= keyword specifies where the bibliography
-should print.
+should be printed (note the colon):
 
 : #+print_bibliography:
 
+A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords.
+Each of the keywords will trigger printing the bibliography.
+
+The keywords can be used with or without additional options.  Options
+can be used, for example, to print only entries that belong to a
+certain category or to control formatting.  The set of supported
+=PRINT_BIBLIOGRAPHY= options and their interpretation varies between
+the different citation export processors.  Some export processors do
+not support passing options.
+
+*** Bibliography options in the "biblatex" and "csl" export processors
+
+The "biblatex" and "csl" export processors support bibliography
+options through a property list attached to the =PRINT_BIBLIOGRAPHY=
+keyword.  For example,
+
+: #print_bibliography: :keyword algebra :type book
+
+Values including spaces must be surrounded with double quotes.  If you
+need to use a key multiple times, you can separate its values with
+commas, but without any space in-between:
+
+: #print_bibliography: :keyword "algebraic logic" :nottype article,book
+
+The "biblatex" export processor accepts all options supported by
+BibLaTeX's ~\printbibliography~ command, while the "csl" processor
+accepts the following ones:
+
+- =:keyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field contains all given keywords.
+
+- =:notkeyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field does not contain any of the given keywords.
+
+- =:type <entrytype>= :: Print only entries whose type is
+  =<entrytype>=.  Entry type is the BibTeX/BibLaTeX entry type if this
+  information is available (the entry was read from a BibTeX/BibLaTeX
+  bibliography) and the CSL entry type otherwise.
+
+- =:nottype <entrytype(,entrytype2...)>= :: Print only entries whose
+  type is not among the given entry types.  Entry type is determined
+  as in the case of =:type=.
+
+- =:csltype <entrytype>= :: Print only entries whose CSL entry type
+  (possibly based on a conversion from BibTeX/BibLaTeX to CSL) is
+  =<entrytype>=.
+
+- =:notcsltype <entrytype(,entrytype2...)>= :: Print only entries whose
+  CSL entry type (possibly based on a conversion from BibTeX/BibLaTeX
+  to CSL) is not among the listed entry types.
+
+- =:filter <predicate>= :: Print only entries for which the given
+  Emacs Lisp predicate returns a non-~nil~ value.
+
 * Working with Source Code
 :PROPERTIES:
 :DESCRIPTION: Export, evaluate, and tangle code blocks.
-- 
2.25.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

> I've attached a new version of the patch with
> - "Bibliography printing" as the subsection title,
> - an added "the" in the subsubsection title "Bibliography options in
> the "biblatex" and "csl" export processors",
> - an improved example.

Thanks! LGTM in general.

>> Though I am wondering why csl does not support :title. It feels like a
>> natural thing to have.
>
> The biblatex "title" option is for changing the title of the
> bibliography section which is created and printed out by biblatex by
> default.
> In contrast to the LaTeX-based export processors, the "csl"  and  the
> "basic" export processors print out only the list of entries, and it's
> up to the user to manually include a bibliography section heading in
> the document if they want one, so the "title" option is not really
> applicable, at least not in the same way.

This is an important point. I think that we should describe this gotcha
in the "Bibliography printing". oc-basic and oc-csl just print the list
of bibliography entries, while oc-bibtex/oc-natbib/oc-biblatex insert a
separate section. It is a very important information and users should be
aware of it. Also, this is kind of annoying - this way mixing oc-bibtex
and oc-basic for LaTeX and non-LaTeX export gets awkward.

Best,
Ihor

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

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

Dear All,

On Fri, 29 Jul 2022 at 03:32, Ihor Radchenko <yantar92@gmail.com> wrote:

> This is an important point. I think that we should describe this gotcha
> in the "Bibliography printing". oc-basic and oc-csl just print the list
> of bibliography entries, while oc-bibtex/oc-natbib/oc-biblatex insert a
> separate section. It is a very important information and users should be
> aware of it.

I agree, so I've attached a new version in which a sentence is added
about this difference in behaviour.

Also, this is kind of annoying - this way mixing oc-bibtex
> and oc-basic for LaTeX and non-LaTeX export gets awkward.

Yes, in the long run we might want to unify the behaviour of the
processors in this respect. OTOH changing "basic" and "csl" to
automatically print a heading would be a breaking change, e.g., AFAIK,
ox-hugo currently adds a heading on its own when org-cite is used for
bibliography printing with the "csl" processor.

best wishes,
András

> Best,
> Ihor

[-- Attachment #2: 0001-doc-org-manual.org-Document-PRINT_BIBLIOGRAPHY-optio.patch --]
[-- Type: text/x-patch, Size: 3637 bytes --]

From b765d8bd65ece076041b8c280c0a7f076a376338 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Simonyi?= <andras.simonyi@gmail.com>
Date: Thu, 28 Jul 2022 22:50:26 +0200
Subject: [PATCH] * doc/org-manual.org: Document "PRINT_BIBLIOGRAPHY" options

---
 doc/org-manual.org | 63 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 596ab3723..9ec49c14e 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16818,11 +16818,72 @@ conformant to the Harvard style and the specification of the
 Wolkers-Kluwer publisher; since it relies on the ~bibtex~ processor of
 your LaTeX installation, it won't export to anything but PDF.
 
+** Bibliography printing
+
 The =PRINT_BIBLIOGRAPHY= keyword specifies where the bibliography
-should print.
+should be printed (note the colon):
 
 : #+print_bibliography:
 
+The bibliography printed by the LaTeX-based export processors
+"bibtex", "natbib" and "biblatex" has a chapter or section heading by
+default, while the "basic" and "csl" processors print the list of
+bibliography entries without a heading.
+
+A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords.
+Each of the keywords will trigger printing the bibliography.
+
+The keywords can be used with or without additional options.  Options
+can be used, for example, to print only entries that belong to a
+certain category or to control formatting.  The set of supported
+=PRINT_BIBLIOGRAPHY= options and their interpretation varies between
+the different citation export processors.  Some export processors do
+not support passing options.
+
+*** Bibliography options in the "biblatex" and "csl" export processors
+
+The "biblatex" and "csl" export processors support bibliography
+options through a property list attached to the =PRINT_BIBLIOGRAPHY=
+keyword.  For example,
+
+: #print_bibliography: :keyword algebra :type book
+
+Values including spaces must be surrounded with double quotes.  If you
+need to use a key multiple times, you can separate its values with
+commas, but without any space in-between:
+
+: #print_bibliography: :keyword "algebraic logic" :nottype article,book
+
+The "biblatex" export processor accepts all options supported by
+BibLaTeX's ~\printbibliography~ command, while the "csl" processor
+accepts the following ones:
+
+- =:keyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field contains all given keywords.
+
+- =:notkeyword <keyword(,keyword2...)>= :: Print only entries whose
+  keyword field does not contain any of the given keywords.
+
+- =:type <entrytype>= :: Print only entries whose type is
+  =<entrytype>=.  Entry type is the BibTeX/BibLaTeX entry type if this
+  information is available (the entry was read from a BibTeX/BibLaTeX
+  bibliography) and the CSL entry type otherwise.
+
+- =:nottype <entrytype(,entrytype2...)>= :: Print only entries whose
+  type is not among the given entry types.  Entry type is determined
+  as in the case of =:type=.
+
+- =:csltype <entrytype>= :: Print only entries whose CSL entry type
+  (possibly based on a conversion from BibTeX/BibLaTeX to CSL) is
+  =<entrytype>=.
+
+- =:notcsltype <entrytype(,entrytype2...)>= :: Print only entries whose
+  CSL entry type (possibly based on a conversion from BibTeX/BibLaTeX
+  to CSL) is not among the listed entry types.
+
+- =:filter <predicate>= :: Print only entries for which the given
+  Emacs Lisp predicate returns a non-~nil~ value.
+
 * Working with Source Code
 :PROPERTIES:
 :DESCRIPTION: Export, evaluate, and tangle code blocks.
-- 
2.25.1

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

>> This is an important point. I think that we should describe this gotcha
>> in the "Bibliography printing". oc-basic and oc-csl just print the list
>> of bibliography entries, while oc-bibtex/oc-natbib/oc-biblatex insert a
>> separate section. It is a very important information and users should be
>> aware of it.
>
> I agree, so I've attached a new version in which a sentence is added
> about this difference in behaviour.

Thanks!
Applied onto main via 24d2826f0.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=24d2826f049068e0d2afac19a2669a3ff8fdad6a

> Also, this is kind of annoying - this way mixing oc-bibtex
>> and oc-basic for LaTeX and non-LaTeX export gets awkward.
>
> Yes, in the long run we might want to unify the behaviour of the
> processors in this respect. OTOH changing "basic" and "csl" to
> automatically print a heading would be a breaking change, e.g., AFAIK,
> ox-hugo currently adds a heading on its own when org-cite is used for
> bibliography printing with the "csl" processor.

Can we then change the oc-biblatex et al defaults to output
\printbibliography[heading=none]
?

Best,
Ihor

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

Dear All,

On Sun, 31 Jul 2022 at 04:32, Ihor Radchenko <yantar92@gmail.com> wrote:

> Can we then change the oc-biblatex et al defaults to output
> \printbibliography[heading=none]
> ?
>
> Best,
> Ihor

unfortunately, IUC, for bibtex suppressing the heading requires the
(possibly local) redefinition of some commands, e.g.
\thebibliography or \section which I find too intrusive.  For natbib
there seems to be a similar situation regarding \bibsection. Because
of this I think it'd be more viable to change the "csl" and "basic"
processors to produce a section heading by default and provide options
to set the title and depth or to suppress it, even if this breaks some
extensions/configurations. (BTW, the predecessor of oc-csl,
citeproc-org added a section heading and org-ref might be doing so
too.)

best wishes,
András

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

> the attached patch adds support for filter-based sub-bibliographies in the "csl"
> org-cite export processor. It supports the same syntax for specifying
> filters as the biblatex processor and supports some of the biblatex
> filter types, concretely, entry-type and keyword based filtering. It
> also supports filtering based on CSL type (as opposed to bib(la)tex
> type) and using any Lisp predicate as a filter.

Applied onto main via 7e0761184.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=7e076118443ed6ccfa95390cdd17b3464859abd3

Best,
Ihor