1# readit23Tooling for managing structured reading notes for scientific publications.45## Motivation67When reading scientific papers and books I usually take notes.8Currently, I primarily use markdown for note taking. Markdown has the9disadvantages that it does not enforce any structure regarding these10notes and it doesn't allow me to search them efficiently, e.g. find all11publications on a specific topic. In an attempt to improve my reading12notes, I came up with this repository.1314## Status1516Work in progress, I am (more or less) happy with the input format. The17tooling is still in very early stages of development. Tooling for18finding entries and generating reference graphs is available as a proof19of concept. Additionally, I would like to add tooling for interacting20with fields (e.g. list all field names) and tooling for generating HTML21output. The existing tooling also needs to be improved significantly.2223## Features2425* Simple plain-text input format26* [CHICKEN Scheme][chicken website] module for parsing the format27* Work in progress tooling for interacting with files of this format28 * `readit`: Allows finding entries by field values.29 * `readit-graph`: Allows generating reference graphs.3031## Installation3233If a correctly configured chicken toolchain is available run:3435 $ chicken-install -test3637This will compile `readit` and add the binary to your `$PATH`.38Additionally, it will perform some basic functionality tests.3940### Building without installing4142If installation is not desired, build `readit` as follows:4344 $ export CHICKEN_REPOSITORY_PATH="${CHICKEN_REPOSITORY_PATH}:$(pwd)"45 $ chicken-install -n -test4647This will create a `readit` binary in the current working directory.4849## Syntax5051The input file is based on reading list entries with associated52information. Each entry consists of a current state, either read `x` or53unread `-`, a unique identifier, and a description (e.g. publication54title). Additionally, key-value pairs and notes can be optionally55associated with an entry, both must be indented by either 4 spaces or56one tab. The syntax of the input format is specified using parser57combinators in the file `parser.scm`.5859The optional key-value pairs are entirely user-chosen. Two special types60are provided for field values: References and sets. References are61enclosed in square brackets and contain (one or more) references to the62unique identifiers of other entries. Sets are collections of multiple63values, e.g. multiple author names, sets are specified using curly64brackets.6566The optional notes are separated from key-value pairs using an empty67line (even when fields are omitted). The reference and set literals68cannot currently be used in the notes section. At the moment, notes are69just uninterpreted plain text. As such, the note format is currently70entirely up to the user, it is (for example) possible to use markdown71syntax for notes.7273## Example7475Consider the following input file:7677 x [rfc7252]: The Constrained Application Protocol (CoAP)78 * Authors: {Zach Shelby, Klaus Hartke, Carsten Bormann}7980 - [rfc7228]: Terminology for Constrained-Node Networks81 * Authors: {Carsten Bormann, Mehmet Ersue, Ari Keranen}82 * DOI: 10.17487/RFC722883 * Topics: {Internet of Things, Constrained Devices}84 * References: [rfc7252]8586 * Introduces different Internet of Things related terms87 * Differentiates different classes of constrained devices8889This file contains reading list entries for [RFC 7252][rfc7252] and90[RFC 7228][rfc7228]. Only the latter contains notes, both make use of91optional fields. Tooling is provided for finding entries by fields. For92example, to find a publication by a specific field value, e.g. a93publication with a specific `DOI`, the `readit` tool must be invoked as94follows:9596 $ readit -f test.readit -v "10.17487/RFC7228" DOI97 - [rfc7228]: Terminology for Constrained-Node Networks9899As the value of the `DOI` field is neither a reference nor a set, this100query only matches entries providing a `DOI` field with this exact101value. For set values the tool only checks if any element in the set102matches the value. As an example, this can be used to find all103publications co-authored by `Carsten Bormann`:104105 $ readit -f test.readit -v "Carsten Bormann" "Authors"106 x [rfc7252]: The Constrained Application Protocol (CoAP)107 - [rfc7228]: Terminology for Constrained-Node Networks108109To find all publications written by both `Carsten Bormann` and `Mehmet110Ersue`, the `-v` flag can be passed more than once. For example:111112 $ readit -f test.readit -v "Carsten Bormann" -v "Mehmet Ersue" "Authors"113 - [rfc7228]: Terminology for Constrained-Node Networks114115## License116117This program is free software: you can redistribute it and/or modify it118under the terms of the GNU General Public License as published by the119Free Software Foundation, either version 3 of the License, or (at your120option) any later version.121122This program is distributed in the hope that it will be useful, but123WITHOUT ANY WARRANTY; without even the implied warranty of124MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General125Public License for more details.126127You should have received a copy of the GNU General Public License along128with this program. If not, see <http://www.gnu.org/licenses/>.129130[chicken website]: https://call-cc.org/131[rfc7252]: https://tools.ietf.org/html/rfc7252132[rfc7228]: https://tools.ietf.org/html/rfc7228