Some time ago I started to work on my thesis and the first thing that came to my mind was the need for proper tool for article gathering
The requirements were simple. The tool that would fit my needs:
- should allow to gather scientific papers and catalog them
- should allow to write text in Markdown-ish syntax
- should allow git to make versioning on documents (more or less it should be a text format)
- should allow to make a bibliography and add citations
and one not that important but it really makes a difference
- should allow to move around written text with VIM shortcuts
Sadly after some research I found that there is no one Swiss Army Knife tool
I experimented with:
- Google docs
- VIM with plugins
- Visual Studio Code with plugins
- Evernote
But none of them really solved all the issues and some of them were a pain in the ass to work with. Like for example VIM plugins…
And at the point when I almost started to write thesis in Latex…
I remind myself that there is a tool Zotero
Step 1 of 4 - Setup Zotero
Zotero [1] is a general tool that allow you to quickly add articles, citations to a common database of your project. With connectors to Firefox and Chrome after you visit websites you can easily add content you want to your Zotero project and then cite or make bibliography with the usage of Microsoft Office Word or LibreOffice
How it works?
To set it up you need to follow these steps:
- Sign up on website and download Zotero: https://www.zotero.org/
- Open Zotero tool and login. It should look more or less like this:
- Install connector for Chrome or Firefox: https://www.zotero.org/download/connectors
Now everything should be setup and you should be able to add your articles to Zotero project. To do that in Firefox you have to:
1) Visit website/article you are interested in
2) Click on the connector and choose where you would like to put an article
And that’s all. Now article was added to your database and should be visible in Zotero application
Step 2 of 4 - Setup Bibtex for Zotero
Visit website https://retorque.re/zotero-better-bibtex/installation/ and follow their instructions
When it’s properly installed you should see that in Zotero you have new options
Step 3 of 4 - Setup AsciiDoctor
You are probably familiar with Markdown. It allows you to write simple, well-formated documents like documentation for the Github project
AsciiDoctor is similar, but has more features
Asciidoctor is a fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby and runs on all major operating systems. [2]
To install it you need to follow instructions on website https://asciidoctor.org/docs/install-toolchain/
After installation two more packages are needed:
If you completed instalation of AsciiDoctor you can install them by typing following command in console
gem install asciidoctor-bibtex asciidoctor-pdf
Step 4 of 4 - start writing with Visual Studio Code
Add lines with config for ascii-doctor-bibtex at the top of your ascii-doc document
:bibtex-file: my-library.bibtex :bibtex-order: alphabetical :bibtex-style: ieee
And now you are ready to make citations. Let’s make some
:bibtex-file: my-library.bibtex :bibtex-order: alphabetical :bibtex-style: ieee How to use citation. citenp:[WhenHowUse] # Here is my bibliography: bibliography::[]
After that you need to run asciidoctor so the .pdf file will be created.
To do that open terminal and type: asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf my-doc.adoc
The output file should look like this:
At this point you might wonder how Zotero connected citation with AsciiDoctor. It’s all bases on key of citation that is inside downloaded my-library-bibtex file
When you open it you should see content which format looks like this:
@misc{WhenHowUse,
title = {When and How to Use Masks},
file = {Zotero/storage/B9LUPTU9/when-and-how-to-use-masks.html},
howpublished = {https://www.who.int/emergencies/diseases/novel-coronavirus-2019/advice-for-public/when-and-how-to-use-masks},
language = {en}
}As you can see the key for this particular citation is WhenHowUse. It was automatically generated and can be changed inside
Zotero
Now everything should be setup
One more thing. Generally you will have to use this asciidoctor command after every save. It’s good
to make a Visual Studio Code task for that
- Click Terminal
- Configure tasks
- Choose Create tasks.json file from template
- Choose other task
- Paste in the
task.json
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"type": "shell",
"command": "asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf my-doc.adoc",
"problemMatcher": [],
"group": {
"kind": "build",
"isDefault": true
}
}
]
}This will create a build task that will be invoked everytime you press Ctrl + Shift + B
Final notes
- To get more inside of Zotero workflow feel free to check up videos on youtube. It’s much easier then reading about it.
- To get more information of how to use AsciiDoc citation library it’s good to check its github samples https://github.com/asciidoctor/asciidoctor-bibtex/tree/master/samples
- When you write your text with AsciiDoctor it’s convenient to have its documentation in the browser tab. It makes writing much faster as you just check what AsciiDoctor tag you need. https://asciidoctor.org/docs/user-manual/
Important:
Whenever you want to change key of article of any other field you have to use Zotero tool and download .bibtex file again. Don’t modify my-library.bibtex
Sources
[1] “Zotero | Your Personal Research Assistant.” https://www.zotero.org/
[2] “Asciidoctor | A Fast, Open Source Text Processor and Publishing Toolchain for Converting AsciiDoc Content to HTML5, DocBook, PDF, and Other Formats.” https://asciidoctor.org/
[3] “Asciidoctor/Asciidoctor-Pdf: Asciidoctor PDF: A Native PDF Converter for AsciiDoc Based on Asciidoctor and Prawn, Written Entirely in Ruby.” https://github.com/asciidoctor/asciidoctor-pdf
[4] “Asciidoctor/Asciidoctor-Bibtex.” https://github.com/asciidoctor/asciidoctor-bibtex, Apr. 2020