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.
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.
To insert the metadata of a title, create a volume dynamic block:
#+begin: volume
#+end:
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.
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:
- The heading is updated to the title + subtitle (if any).
booktag is added to the headline.- Some properties, e.g. the ISBN code of the book, are added.
- It inserts a thumbnail before the dynamic block.
To insert a TOC, create a volume-toc dynamic block in the same entry as the volume block:
#+begin: volume-toc
#+end:
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.
- 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.
- org-books is a framework for reading list management with Org mode.
- org-media-info creates an Org entry instead of producing the content of a dynamic block.