219 lines
No EOL
9.8 KiB
Markdown
219 lines
No EOL
9.8 KiB
Markdown
---
|
||
title: "Library Management (INTERNAL)"
|
||
date: "2023-06-29T18:59:19+03:00"
|
||
author: "anybody"
|
||
contributors:
|
||
draft: true
|
||
keywords:
|
||
- internal
|
||
- library
|
||
- journal management
|
||
abstract: |
|
||
(Internal)Library management guide for Sandpoints projects.
|
||
---
|
||
|
||
[Accorder]: https://pypi.org/project/accorder/ "Accorder at pypi.org."
|
||
[Zotero]: https://www.zotero.org/ "Zotero.org; free, open source and cross-platform citation management software."
|
||
[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)"
|
||
|
||
# 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 by multiple 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.
|
||
|
||
# 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
|
||
|
||
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]
|
||
|
||
Note that a Calibre library entry can have *multiple different files associated with it* (for example both a pdf and an epub), however, it cannot have two files of the same format.
|
||
|
||
## Via Calibre
|
||
|
||
1. Click `Add books`, or drag and drop a file (e.g. pdf, epub, zip) to Calibre.
|
||
2. Select the item and click `Edit metadata`, or press `e`.
|
||
3. Add/correct the item **title**.
|
||
4. Add/correct the name of the **author(s)**. Author names are entered as in `Name Surname`. Multiple authors are separated by ampersand as in `Jane Doe & John Doe`.
|
||
5. Automatically download metadata. Calibre should be able to download metadata automatically from online databases (this works mostly for commercial books).
|
||
1. With the author names and book title in place (ideally also the `ISBN` -- see step 7), . Click `Download metadata` or press `d`.
|
||
2. Calibre will find available metadata sets, which might include book cover and item description or review. Check if the
|
||
3. If Calibre fails to find available metadata, try to add the book ISBN and try again. Otherwise
|
||
6. Add **identifiers** such as ISBN, or DOI in the field `Ids`, as in `isbn:12345674896`. In case of multiple ids separate them with a semicolon(`;`).
|
||
7. Add **keywords** separated by commas, as in `game design, monograph`. Try to enter adequate keywords. If the item metadata were downloaded automatically review the keywords, as they are usually generic.
|
||
8. Add **publisher**.
|
||
9. Add **publication date** in the field `published`.
|
||
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)
|
||
|
||
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)`.
|
||
3. In the new dialogue select a BibTeX format and check the box `Export Files`.
|
||
4. Click OK, and select destination and filename (e.g. `mycollection.bib`)
|
||
|
||
[^vfa]: For valid file attachments see [Accorder book extensions][].
|
||
|
||
[^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.
|
||
|
||
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
|
||
```
|
||
|
||
# Building library standalone with Accorder
|
||
|
||
|
||
[Accorder][] is a Python command line tool developed by Marcell Mars used for amateur librarianship.
|
||
It's main features are:
|
||
- building a standalone portable web app version of a Calibre library accessible via `http`,
|
||
- compiling a JSON catalogue of a standalone library,
|
||
- transferring bibliographic items within `.bib` files (e.g. exported from [Zotero][] and including files) into Calibre.
|
||
|
||
## Install Accorder
|
||
To install accorder open a terminal and do:
|
||
```
|
||
pip3 install accorder
|
||
```
|
||
To upgrade accorder, do:
|
||
```
|
||
pip3 install --upgrade accorder
|
||
```
|
||
To check the version of your accorder installation do:
|
||
```
|
||
accorder --version
|
||
```
|
||
For a list and description of accorder commands do:
|
||
```
|
||
accorder --help
|
||
```
|
||
|
||
## Accorder profiles
|
||
|
||
Accorder requires to setup a `profile` that is associated with:
|
||
1. a librarian, and
|
||
2. a local Calibre library directory.
|
||
|
||
To show existing accorder profiles, do:
|
||
```
|
||
accorder configuration --show
|
||
```
|
||
|
||
If an accorder profile was already setup, the previous command will output:
|
||
```
|
||
..PROFILE: profile-name
|
||
....LIBRARIAN: librarians-name
|
||
....CALIBRE LIBRARY: /path/to/calibre/library/
|
||
```
|
||
It will also show the path of the *accorder.ini* file with configuration profile information.
|
||
|
||
## Create accorder configuration profile
|
||
|
||
To create a new accorder profile do:
|
||
```
|
||
accorder build -d /path/to/calibre/library/ -l librarians-name profile-name
|
||
```
|
||
|
||
This will setup a new profile and also build a standalone web app of the library.
|
||
The profile should now be visible in `accorder configuration -s`.
|
||
To edit elements of a profile configuration follow instructions in `accorder configuration --help`.
|
||
|
||
## Build a portable library
|
||
|
||
With accorder installed and a profile setup, to build a standalone web app of the library do:
|
||
```
|
||
accorder build profile-name
|
||
```
|
||
|
||
This will generate a portable version of the Calibre library by adding in the library directory:
|
||
1. a `BROWSE_LIBRARY.html` file, and
|
||
2. a folder titled `static` with necessary dependencies.
|
||
|
||
## Build library catalogue
|
||
|
||
To build a library catalogue that allows referencing library items from Sandpoints do:
|
||
|
||
```
|
||
accorder build -j /path/to/export/catalog.json profile-name
|
||
```
|
||
This command will build the library catalogue in JSON format. The catalogue includes a unique ID and metadata fields for every item of the library.
|
||
|
||
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
|
||
```
|
||
|
||
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-a-portable-library), and
|
||
- [build a library catalogue](#build-library-catalogue).
|
||
|
||
1. Place the library catalogue at the folder `data/books/` of the project, as in:
|
||
```
|
||
/root/data/books/catalog.json
|
||
```
|
||
2. Build library standalone web app, and copy the entire contents of the Calibre library directory (including the `static` folder and `BROWSE_LIBRARY.html`) to ...
|
||
> For local projects the library can be copied to:
|
||
> ```
|
||
> /root/content/library/
|
||
> ```
|
||
> so that `BROWSE_LIBRARY.html` is at: `root/content/library/BROWSE_LIBRARY.html`
|
||
|
||
# Link library item inside Sandpoints articles
|
||
|
||
To reference a library item inside a Markdown entry of this project do:
|
||
```
|
||
.
|
||
```
|
||
|
||
`the-book-id` is a placeholder for the unique id of a library item, which is in the style of `625e5562-38bc-4497-adaa-5142ef810c4a`.
|
||
|
||
To find the unique ID of a library item, do either of the following:
|
||
- Open the library catalogue (`/root/data/books/catalog.json`) with a text editor such as [Notepad++][]. Search for the book that you want to reference, and copy its `_id` field.
|
||
- Open the [Library][] find the item you want to reference, and copy the last part of it's URL after `.../book/`.
|
||
|
||
## Library reference example
|
||
|
||
The following example links to the library item at: `.../library/BROWSE_LIBRARY.html#/book/3ea44269-47eb-468b-906e-3104398aaa07`
|
||
Thus, the item unique id is: `3ea44269-47eb-468b-906e-3104398aaa07`.
|
||
|
||
*Formatting*:
|
||
```
|
||
Stalder, Felix. . Cambridge, UK ; Medford, MA: Polity Press, 2018.
|
||
```
|
||
|
||
*Appearance*:
|
||
|
||
Stalder, Felix. . Cambridge, UK ; Medford, MA: Polity Press, 2018.
|
||
|
||
---
|
||
|
||
|
||
Bib references that break:
|
||
- [how to play](bib:7f033665-ac6d-4bcd-8f05-f3a92987b910)
|
||
- [eliz](bib:55bcc3a3-40e6-4bce-bb7c-3645e3411a69)
|
||
- [infinite](bib:1d00c5a0-3c50-4c0c-83b3-ebaf6bca1dbb)
|
||
<!--
|
||
- 
|
||
- 
|
||
- 
|
||
- (bib:237e535c-f6f5-4d28-ad6f-6b47ae639df7)
|
||
- (bib:10823ff0-fdc9-44be-a537-10bb234d2348)
|
||
- (bib:1b258738-63e9-4af0-83eb-c9f9e9521aa3) (zip)
|
||
- --> |