From d99c0fd9f3d3bffecada4a482d7c4110f731542e Mon Sep 17 00:00:00 2001 From: constantinos Date: Tue, 11 Jul 2023 13:54:48 +0300 Subject: [PATCH] Internal article for Sandpoints Library Management --- content/article/int-library.md | 219 +++++++++++++++++++++++++++++++++ content/print/p-library.md | 7 ++ 2 files changed, 226 insertions(+) create mode 100644 content/article/int-library.md create mode 100644 content/print/p-library.md diff --git a/content/article/int-library.md b/content/article/int-library.md new file mode 100644 index 0000000..59771c5 --- /dev/null +++ b/content/article/int-library.md @@ -0,0 +1,219 @@ +--- +title: "Library Management (INTERNAL)" +date: "2023-06-29T18:59:19+03:00" +author: "anybody" +contributors: +draft: true +keywords: + - internal + - library + - management +abstract: | + 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: +``` +![Link caption](bib:the-book-id). +``` + +`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. ![The Digital Condition](bib:3ea44269-47eb-468b-906e-3104398aaa07). Cambridge, UK ; Medford, MA: Polity Press, 2018. +``` + +*Appearance*: + +Stalder, Felix. ![The Digital Condition](bib:3ea44269-47eb-468b-906e-3104398aaa07). 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) + \ No newline at end of file diff --git a/content/print/p-library.md b/content/print/p-library.md new file mode 100644 index 0000000..0fe3991 --- /dev/null +++ b/content/print/p-library.md @@ -0,0 +1,7 @@ +--- +title: "Library Managment Guide Print (internal)" +date: "2023-07-11T13:36:25+03:00" +author: "anybody" +draft: true +print: "article/int-library.md" +---