Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/akirak/org-volume

Org dynamic blocks for metadata of books
https://github.com/akirak/org-volume

books emacs org-mode

Last synced: 7 days ago
JSON representation

Org dynamic blocks for metadata of books

Awesome Lists containing this project

README 

        
* org-volume

[[https://github.com/akirak/org-volume/actions/workflows/lint.yml][file:https://github.com/akirak/org-volume/actions/workflows/lint.yml/badge.svg]]



This package provides Org dynamic blocks for metadata of volumes of

medium such as books.



It retrieves information from web sites and APIs and insert it into

a block in Org. It builds a search query from the current Org

entry.



It also provides a command for updating the current Org entry from

the retrieved information. For example, it can update the heading

to match the accurate title of the volume, add a tag to denote the

format, and set entry properties which will be convenient for

scripting.



Out of the box it supports retrieving information of books using

Google Books API v1.



It is designed to be extensible, so you can add custom media types

and metadata providers. For example, it would be possible to add

providers for video, music, etc.

# Add CI badges here



#+BEGIN_HTML

#+END_HTML

[[file:screenshots/screenshot-1.svg]]

** Table of contents

:PROPERTIES:

:TOC: siblings

:END:

-  [[#installation][Installation]]

-  [[#usage][Usage]]

  -  [[#books-via-google-books-api][Books (via Google Books API)]]

    -  [[#retrieving-metadata-for-the-heading][Retrieving metadata for the heading]]

    -  [[#updating-the-org-entry][Updating the Org entry]]

    -  [[#inserting-the-table-of-contents-of-the-book][Inserting the table of contents of the book]]

-  [[#license][License]]



** Installation

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:07]

:END:

This package is not available from MELPA yet.

** Usage

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:08]

:END:

At present, =org-volume= package only provides a built-in support for Google Books API v1.

You can add other providers by adding entries to =org-volume-site-alist= variable.

*** Books (via Google Books API)

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:15]

:END:

**** Retrieving metadata for the heading

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:09]

:END:

To insert the metadata of a title, create a =volume= dynamic block:



#+begin_src org

  ,#+begin: volume

  ,#+end:

#+end_src



If you run =C-c C-c= on the block, it retrieves information from the default site, i.e. Google Books, and insert a list into the block.



By default, the search query is built from the heading of the Org entry.

Alternatively, you can explicitly set a query as =:q= parameter of the block.



Multiple search results can be inserted into the block, but if you set

=:limit= to 1 in the block header, it lets you select a candidate

interactively.



It also supports =:lang= parameter which can be used to set the language.

The default value is ="en"=, which stands for English.



You can override the default parameters by customizing =org-volume-dblock-defaults= variable.

**** Updating the Org entry

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:12]

:END:

Once you generate the =volume= block, you can update the Org entry from the metadata.



If you run =org-volume-update-entry-from-dblock= on the block, the entry is updated as follows:



1. The heading is updated to the title + subtitle (if any).

2. =book= tag is added to the headline.

3. Some properties, e.g. the ISBN code of the book, are added.

4. It inserts a thumbnail before the dynamic block.

**** Inserting the table of contents of the book

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:15]

:END:

After you update the Org entry, you can optionally add the table of contents (TOC) of the book

if it is published from one of the supported publishers.

At present, only [[https://pragprog.com/][Pragmatic Bookshelf]] is supported.



To insert a TOC, create a =volume-toc= dynamic block in the same entry as the =volume= block:



#+begin_src org

  ,#+begin: volume-toc

  ,#+end:

#+end_src



It must reside under the same Org headline, and it doesn't work inside subtrees.



When you run =C-c C-c= on the dynamic block, it finds a web page for the title on the publisher's web site, scrape the web page, and extract and insert the TOC into the block.



You can add support for more publishers by extending =org-volume-publisher-site-list=.

Some publishers may prevent bots from accessing their web sites, so you cannot retrieve TOCs of books from those publishers.



When you scrape data from websites, make sure that you remain a good developer:



- Check Terms of Use of the web site you are trying to scrape.

- Stick with common practices of ethical web scraping.

** Alternatives

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 19:26]

:END:

- [[https://github.com/yantar92/org-capture-ref][org-capture-ref]] lets you insert citation information using org-capture and supports various backends. I didn't know of it when I wrote org-volume, but you should have a look at it instead.

- [[https://github.com/lepisma/org-books][org-books]] is a framework for reading list management with Org mode.

- [[https://github.com/floscr/org-media-info][org-media-info]] creates an Org entry instead of producing the content of a dynamic block.

** License

:PROPERTIES:

:CREATED_TIME: [2021-02-14 Sun 14:08]

:END:

GPL v3