[[https://github.com/sbsdev/catalog/actions/workflows/clojure.yml][https://github.com/sbsdev/catalog/actions/workflows/clojure.yml/badge.svg]]

* Kati

Kati is a web-based system to generate catalogs of new items in the
library. It takes [[https://www.loc.gov/marc/bibliographic/][MARC21 XML]] bibliographic data from the library
system and produces catalogs in various formats such as [[http://www.access-for-all.ch/en/pdf-lab/pdf-accessibility-checker-pac.html][accessible PDF]]
or [[https://en.wikipedia.org/wiki/DTBook][DTBook XML]]. The PDFs contain either all of the new catalog items or
various subsets of the items such as all new large print books or all
new audio books for example.

For the DTBook there are actually two variations produced. One can be
used for the production of Braille with a separate tool chain (such as
[[https://github.com/sbsdev/pipeline-mod-sbs][pipeline-mod-sbs]] for example) while the other is imported into [[http://www.daisy.org/project/obi][Obi]] for
audio production.

[[https://versions.deps.co/sbsdev/catalog][https://versions.deps.co/sbsdev/catalog/status.svg]]

** Build and Installation

Kati is based on Luminus version "4.10". You can build it with
[[https://github.com/technomancy/leiningen][Leiningen]]:

#+BEGIN_SRC shell
lein uberjar
#+END_SRC

The resulting jar can be run as follows:

#+BEGIN_SRC shell
java -Dconf=dev-config.edn -jar catalog.jar
#+END_SRC

*** Release

#+BEGIN_SRC shell
lein release :minor
#+END_SRC

** Documentation

- [[https://sbsdev.github.io/catalog][API Docs]]

*** Data structure

The data is read from [[https://www.loc.gov/marc/bibliographic/][MARC21 XML]] and converted into a Clojure sequence
of sorted maps. These maps are quite free form, they contain different
fields depending on the format of the entry, e.g. a braille book might
have a grade while an audio book probably has a narrator. The entries
are validated through prismatic/schema. The maps are sorted to
maintain order, which is later used to emit the genres or sub-genres in
the desired sequence and to create the TOC accordingly.

*** Output generation

For most outputs the sequence of entries is grouped by format and
genre (possibly sub-genre) and essentially converted into a tree of
maps. This tree is then passed to the different output functions that
render the data. Most of these generate a [[https://github.com/weavejester/hiccup][hiccup style]] data structure
from the tree which is then passed to [[https://xmlgraphics.apache.org/fop/][Apache FOP]] or used as is in the
case of [[https://en.wikipedia.org/wiki/DTBook][DTBook XML]]. The text formatter just generates text from the
tree structure.

**** Accessible PDF

Quite a bit of work has gone into making sure the PDF produced by FOP
is accessible. Roles are attached to the appropriate elements,
atifacts are tagged as such and alt texts are added using the
~fox:alt-text~ attributes.

*** Database

A relational db is used to persist the data. Well, it is really more
used like a [[https://en.wikipedia.org/wiki/Document-oriented_database][document-oriented database]] as we essentially just store
the sequence of entries as an [[https://github.com/edn-format/edn][edn]] string. For the exact details refer
to the [[https://github.com/sbsdev/catalog/blob/master/resources/schema.sql][schema]].

*** Markdown

The editorial part of some of the catalogs is edited directly in the
browser using markdown. In the browser this is implemented using
[[http://www.codingdrama.com/bootstrap-markdown/][Bootstrap Markdown]] and [[https://github.com/evilstreak/markdown-js/releases/download/v0.6.0-beta1/markdown-browser-0.6.0-beta1.tgz][markdown-browser]]. On the server side we use
[[https://github.com/theJohnnyBrown/endophile][endophile]] to convert markdown into clj data structures which are then
again converted to a [[https://github.com/weavejester/hiccup][hiccup style]] data structure.

** Configuration and Dependencies
Installation and configuration can be done using an [[https://github.com/sbsdev/sbs-infrastructure/blob/master/kati.yml][ansible
installation script]] which automates the whole process.

Mostly you will need Java, and some fonts.

** License

Copyright © 2015-2023 Swiss Library for the Blind, Visually Impaired and Print Disabled.

Distributed under the [[http://www.gnu.org/licenses/agpl-3.0.html][GNU Affero General Public License]]. See the file LICENSE.