From b09b2b479222b6b46790bb08bbb035920207afd0 Mon Sep 17 00:00:00 2001
From: Zeping Lee <zepinglee@gmail.com>
Date: Sat, 27 Jul 2024 10:22:10 +0800
Subject: [PATCH] Update docs

---
 docs/citation-style-language-doc.tex | 78 +++++++++++++++++++++++++---
 1 file changed, 70 insertions(+), 8 deletions(-)

diff --git a/docs/citation-style-language-doc.tex b/docs/citation-style-language-doc.tex
index 6580e795..fcd88ff0 100644
--- a/docs/citation-style-language-doc.tex
+++ b/docs/citation-style-language-doc.tex
@@ -14,10 +14,14 @@
 \NewDocumentCommand\field{m}{\texttt{#1}}
 \NewDocumentCommand\entrytype{m}{\texttt{#1}}
 
+\lstdefinestyle{plain}{
+  basicstyle = \ttfamily\small,
+  basewidth  = 0.51em,
+}
+
 \lstnewenvironment{LaTeXdemo}{
   \lstset{
-    basicstyle = \ttfamily\small,
-    basewidth  = 0.51em,
+    style      = plain,
     frame      = single,
     gobble     = 2,
     language   = [LaTeX]TeX,
@@ -26,8 +30,7 @@
 
 \lstnewenvironment{bash}{
   \lstset{
-    basicstyle = \ttfamily\small,
-    basewidth  = 0.51em,
+    style      = plain,
     % gobble     = 2,
     language   = bash,
   }
@@ -152,7 +155,6 @@ \section{Getting started}
 \end{enumerate}
 
 
-
 \section{Package setup}
 
 \begin{function}{\cslsetup}
@@ -262,6 +264,8 @@ \section{Package setup}
 By default, it is the \cs{parindent} at when printed out.
 
 
+\section{Bibliographic resources}
+
 \begin{function}{\addbibresource}
   \begin{syntax}
     \cs{addbibresource}\marg{resource}
@@ -279,6 +283,49 @@ \section{Package setup}
   \addbibresource{file2.yaml, file3.bib}
 \end{LaTeXdemo}
 
+CSL-JSON is the bibliographic metadata format for CSL styles.
+Below is an example entry in this format. Each entry must have these two
+fields: \texttt{id} and \texttt{type} and the former is the entry keys that
+appears in the \cs{cite} command. The accepted entry types and fields are
+listed in Appendix \ref{sec:entry-types} and Appendix \ref{sec:entry-fields},
+respectively. In most cases, one does not manually write CSL-JSON but exports
+from a reference manager like Zotero or Mendeley.
+
+\begin{lstlisting}[style=plain,gobble=2,frame=single]
+  {
+    "id": "ITEM-1",
+    "type": "book",
+    "author": [
+      {
+        "family": "D'Arcus",
+        "given": "Bruce"
+      }
+    ],
+    "issued": {
+      "date-parts": [
+        [ 2005, 11, 22 ]
+      ]
+    },
+    "publisher": "Routledge",
+    "title": "Boundaries of dissent: Protest and state power in the media age"
+  }
+\end{lstlisting}
+
+The traditional Bib(La)TeX format is also supported. It's internally converted
+to CSL-JSON format. However there are some differences.
+
+In a Bib(La)TeX database, the titles (includding \texttt{booktitle}s) should
+be written in title case with propper words enclosed with braces (e.g.,
+“\texttt{The \{Feynman\} Lectures on Physics}”). However CSL requires the
+titles stored in sentence case (“\texttt{The Feynman lectures on physics}”).
+By default the BibTeX-to-CSL translation does this case conversion.
+It checks the original case and skips the titles that are already in sentence
+case. For example, the lowercase word “lectures” in “The Feynman lectures on
+physics” indicates the whole title is in sentence case and citeproc-lua does
+not convert it. This behavior can be turned off by specifying
+\opt{check-sentence-case = false} in the optional argument of
+\cs{addbibresource}.
+
 
 \section{Citation commands}
 
@@ -589,7 +636,7 @@ \subsection{Bibliography Sections}
 to the global section.
 
 
-\subsection{Bibliography Headings}
+\subsection{Bibliography headings}
 
 \begin{function}{\defbibheading}
   \begin{syntax}
@@ -612,7 +659,6 @@ \subsection{Bibliography Headings}
   }
 \end{LaTeXdemo}
 
-
 The following are predefined headings which can be used directly.
 
 \begin{description}
@@ -631,8 +677,24 @@ \subsection{Bibliography Headings}
 \end{description}
 
 
+\subsection{Bibliography categories}
+
+\begin{function}{\DeclareBibliographyCategory}
+  \begin{syntax}
+    \cs{DeclareBibliographyCategory}\marg{category}
+  \end{syntax}
+\end{function}
+
+This command declares a new \meta{category} for use with the \opt{category} and
+\opt{notcategory} options in \cs{printbibliography}.
+
+\begin{function}{\addtocategory}
+  \begin{syntax}
+    \cs{addtocategory}\marg{category}\marg{entrykey, \dots}
+  \end{syntax}
+\end{function}
 
-% \markdownInput{bib-csl-mapping.md}
+This command assigns the \meta{entrykey}s to \meta{category}.
 
 
 \section{Compatibility with other packages}