From 8682b04ca91012ecac8e8866f035bbbc96f6265b Mon Sep 17 00:00:00 2001 From: constantinos Date: Mon, 14 Aug 2023 17:28:50 +0300 Subject: [PATCH] update library management --- content/article/int-library.md | 46 +++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/content/article/int-library.md b/content/article/int-library.md index cd7538f..15bdb4b 100644 --- a/content/article/int-library.md +++ b/content/article/int-library.md @@ -17,22 +17,40 @@ abstract: | [Calibre]: https://calibre-ebook.com/ "Calibre-ebook.com; free, open source and cross-platform eBook management software." [Library]: /library/BROWSE_LIBRARY.html "Project library." [Accorder book extensions]: https://gitlab.com/marcellmars/accorder/-/blob/master/accorder/utils/bibtex.py#L55 "Accorder supported book extensions (Gitlab)" +[Notepad++]: https://notepad-plus-plus.org/downloads/ "Notepad++ is a free and open-source text editor for Windows." + # Introduction Sandpoints is designed to be integrated with a library. The library is accessible via the red button at the top right corner of any content page, or at [Library][] . Key features of the library include: -- hosting collections maintained by different librarians; -- library catalogue search by Author, Title, or Tags; -- presentation of catalogue by book covers (default) or as list (select from top of the page); -- basic item metadata as well as the Librarian's description of an entry. -- referencing library items in entries of this site, and automating bibliographic citation via item id. +- library catalogue that can host various different file formats (e.g. ebooks, a/v media, and zip files; see [populating the library](#pop)); +- catalogue search by Author, Title, or Tags; +- presentation of library catalogue by book covers (default) or as list (select from top of the page); +- basic item metadata as well as the Librarian's description of every entry. +- referencing library items in entries of this site via item id, and automating bibliographic citations. +# Contribution workflow + +For better library maintenance it is recommended to have single designated librarian. +The optimal way to contribute to the library is by submitting a bibliographic collection exported via Zotero (as described in [Export bibliography collection](#zot)). This can be easily integrated with the existing library by the managing librarian. # Required software for library management - [Calibre][]: free & open source eBook management software available for Windows, OSX, and Linux. - [Accorder][]: a Python command line tool -- installation instructions below. - A command line interface (CLI; such as *Windows PowerShell*, *Git Bash*, or *Terminal* or *iTerm2* for macOS). -# Populating the library +# Library integration outline + +1. The library is maintained in [Calibre]. +2. The library is excluded from the Git repository of the site, because of its sub-optimal way of handling large non-text files (e.g. PDFs). +3. Adding items to the library can be done: + 1. directly to [Calibre], or + 2. by loading a bibliography exported from [Zotero] via [Accorder]. +4. To update the library, using the command line tool [Accorder]: + 1. Create a portable version of the library. + 2. Create a library catalogue (JSON dictionary located at `root/data/books/catalog.json`) +5. Upload the library via rsync. + +# Populating the library {#pop} Assuming you have a Calibre library running, you can add items from a range of file formats supported both by Calibre and Accorder. These are: `pdf, epub, mobi, azw, azw3, cbz, chm, djvu, doc, docx, fb2, htmlz, mbp, md, txt, zip`.[^vfa] @@ -55,8 +73,9 @@ Note that a Calibre library entry can have *multiple different files associated 10. Make sure that the item has a **book cover**. If not either click `Download cover` (which will try to find a cover from online databases), or click `Generate cover` to create one based on the item's metadata. 11. Click OK to save these changes. -## Via Zotero (requires Accorder setup) +## Via Zotero +### Export bibliography collection {#zot} To export items via [Zotero][] do the following: 1. Select an item, multiple items, or a collection, with *valid file attachments*[^vfa] which are *stored locally* (not on the Zotero cloud).[^local] 2. Right click and select `Export Item(s)`. @@ -67,6 +86,8 @@ To export items via [Zotero][] do the following: [^local]: To check if your Zotero file attachments are stored locally double click on a given item, to open its attachment. If the item is on the cloud Zotero will automatically download the associated file to your local database. +### Import bibliography collection to Calibre (requires Accorder setup) + To import the Zotero collection to Calibre do (for setting up accorder profiles see next section): ``` accorder build -b path/to/zotero/export/mycollection/mycollection.bib profile-name @@ -152,18 +173,15 @@ This command will build the library catalogue in JSON format. The catalogue incl The file *should be named* `catalog.json`, and *should be placed* inside a Sandpoints project in the directory `root/data/books/catalog.json`. Or, it can be directly compiled at that directory: ``` -accorder build -j /path/to/root/dir/data/books/catalog.json profile-name +accorder build -j /path/to/root/data/books/catalog.json profile-name ``` Note: The catalogue file can be opened and viewed with any text editor. It is formatted in a single line. Some text editors feature tools that can auto-format JSON files so that they are more easily readable. For example, [Notepad++][] for Windows, features the plugin *JSTools* that can auto-format JSON. - -[Notepad++]: https://notepad-plus-plus.org/downloads/ "Notepad++ is a free and open-source text editor for Windows." - # Deploy library -To deploy a library firstly use accorder to -- [build a library standalone web app](#build-lib), and -- [build a library catalogue](#build-catalog). +To deploy a library use [Accorder] to: +1. [build a library standalone web app](#build-lib). +2. [build a library catalogue](#build-catalog). 1. Place the library catalogue at the folder `data/books/` of the project, as in: ```