2020-07-12 14:07:45 +10:00
# cadmus
Shell Scripts to Facilitate Effective Note Taking
2020-07-13 00:11:59 +10:00
2020-07-24 19:35:04 +10:00
> [See the Documentation here](https://ryangreenup.github.io/cadmus/index.html)
2020-07-14 01:40:13 +10:00
## Introduction
2020-07-13 00:22:22 +10:00
2020-07-20 17:00:05 +10:00
This is a **self-contained** shell script that uses pre-existing tools (such as TMSU and recoll) to provide an interface for markdown notes.
2020-07-14 00:04:46 +10:00
2020-07-20 17:00:05 +10:00
It's command based and prints out available subcommands for any given command, these means you can use a directory of markdown files like a personal wiki, much like OneNote/Evernote/Notable, for example:
2020-07-14 01:40:13 +10:00
2020-07-20 17:00:05 +10:00
![Mindmap of Program Flow ](./usage.svg "Diagram of the flow of the script" )
2020-07-14 01:40:13 +10:00
2020-07-20 17:00:05 +10:00
and an overview of what it looks like in the terminal
![](./media/Many_Examples.png)
2020-07-20 17:03:38 +10:00
For example if you wanted to extract all the tags from your markdown notes (either `#tags` or from the YAML), cadmus has a tool for that:
![](./media/TagsExample.gif)
2020-07-20 17:00:05 +10:00
Ultimately the idea is it is to act a menu to dispatch different scripts I already had so I could
more easily share those scripts with classmates.
The real heavy lifting is done by Pandoc, Recoll, ripgrep, skim/fzf, TMSU etc.
2020-07-13 00:22:22 +10:00
2020-07-13 00:11:59 +10:00
## Installation
2020-07-24 21:20:37 +10:00
[cadmus is available on the AUR ](https://aur.archlinux.org/packages/cadmus-notes/ ), generally however cadmus will operate in a portable fashion to `~/.cadmus/` , so just using `git` is fine as well:
2020-07-24 14:29:43 +10:00
2020-07-20 17:00:05 +10:00
### Automatic
Copy this into your shell:
2020-07-20 13:28:12 +10:00
``` bash
cd $(mktemp -d)
wget https://raw.githubusercontent.com/RyanGreenup/cadmus/master/install.sh
bash install.sh
```
2020-07-20 17:00:05 +10:00
- Cadmus will work from within a self-contained directory and add a symlink to `~/.local/bin`
- in this way it's zero lock-in, it does not modify your curr directory of Markdown files.
- Installation will automatically create a config file in its directory (which is by default `~/.cadmus`
- The script will list any [dependencies ](#dependencies ) that are not satisfied.
### Manual
2020-07-20 13:28:12 +10:00
To install manually:
2020-07-16 05:37:29 +10:00
1. satisfy [the dependencies ](#Dependencies )
2. [Set up Recoll ](#Configuring-recoll )
2020-07-20 13:28:12 +10:00
3. Download cadmus and put it into the `PATH`
2020-07-17 04:28:18 +10:00
```bash
2020-07-17 06:39:57 +10:00
git clone https://github.com/RyanGreenup/cadmus ~/.cadmus \
2020-07-20 05:10:02 +10:00
|| echo "Delete $HOME/.cadmus first"
2020-07-19 19:53:39 +10:00
mkdir -p $HOME/.local/bin
2020-07-20 05:10:02 +10:00
ln -s "$HOME/.cadmus/bin/cadmus" "$HOME/.local/bin/"
2020-07-17 04:28:18 +10:00
```
2020-07-20 05:10:02 +10:00
3. According to the [*SystemD Standard* ](https://www.freedesktop.org/software/systemd/man/file-hierarchy.html ) `~/.local/bin` should be in `$PATH` , if you are using some other init implementation you can add this directory to `"$PATH"` it by doing something like this:
2020-07-16 05:37:29 +10:00
2020-07-17 04:30:00 +10:00
``` bash
2020-07-20 05:10:02 +10:00
## Should work in bash/zsh/fish
echo $PATH | grep "$HOME/.local/bin" & > /dev/null & & echo "$HOME/.local/bin in path already" || ls "$HOME/.local/bin" & > /dev/null & & echo 'PATH="$PATH:$HOME/.local/bin"' >> $HOME/.profile
2020-07-17 04:30:00 +10:00
```
2020-07-17 04:28:18 +10:00
2020-07-20 17:00:05 +10:00
> When first run, the script will prompt you to make a config file in the directory in which it is run.
2020-07-17 04:28:18 +10:00
2020-07-20 17:00:05 +10:00
### Assumptions
2020-07-17 04:28:18 +10:00
2020-07-20 17:00:05 +10:00
It is assumed that:
2020-07-12 22:07:01 +10:00
2020-07-20 17:00:05 +10:00
1. Notes are:
1. *Markdown* files with a `.md` extension
3. Recoll updates it's index on the fly
* The notes directory will need to be indexed by *Recoll* in order for
the results to show up when using `cadmus search` .
3. SSD
* I use an SSD and so I let some scripts be pretty inefficient (for example something like `grep | cut |
xargs find` to avoid creating a variable), I don't know if HDD performance would be great.
5. All Notes have Unique Names
6. On *MacOS* you'll need to define `xdg-open` and have GNU coreutils, so do something like:
```bash
alias xdg-open='open & >/dev/null'
alias realpath=grealpath & >/dev/null
```
[*nushell*]: https://github.com/nushell/nushell
[*Fish*]: https://fishshell.com/
[*OMF*]: https://github.com/oh-my-fish/oh-my-fish
2020-07-13 22:40:34 +10:00
2020-07-20 17:00:05 +10:00
2020-07-15 16:10:13 +10:00
### Configuring recoll
2020-07-17 04:28:18 +10:00
Currently the search just uses the default recoll config, I intend to modify this to use `~/.cadmus` as a config directory so as to not interfere with the default config.
It isn't in practice an issue if `~/.recoll` is indexing more than the notes because you can just modify the call to *Skim* (`sk` ) in ..cadmus.. to start the call with `~/Notes/MD` .
2020-07-15 16:10:13 +10:00
<!-- -
By default *Cadmus* will use a rcoll configuration at `~/.cadmus` , this is to ensure that it doesn't conflict with any previous configuration.
Set this up by performing:
``` bash
mkdir ~/.cadmus
recoll -c ~/.cadmus
```
then select *index configuration* and configure recoll to have `~/Notes/MD` as the top directory and to exclude `~` , ideally `recoll` will index live which can configured with *indexing schedule* . *Recoll* will then start indexing the files and afterwards (≅ 1-2 minutes) the *GUI* will pop up and you can confirm that the indexing was successful.
|:note: NOTE|
| --- |
| If you want to change the notes directory change the variable `NOTES_DIR` in ** **< span style = "color:rgb(90,210,90);font-family:Courier New,Courier, monospace,serif;" > cadmus</ span > **** |
-->
2020-07-13 01:45:03 +10:00
2020-07-13 01:34:07 +10:00
2020-07-13 01:28:58 +10:00
2020-07-20 17:00:05 +10:00
## Design Philosophy
2020-07-14 19:29:06 +10:00
2020-07-25 18:34:41 +02:00
- ****< span style = "color:rgb(90,210,90);font-family:Courier New,Courier, monospace,serif;" > cadmus</ span > **** acts as a menu for scripts to achieve things
2020-07-20 17:00:05 +10:00
- The Actual work will be done by subscripts denoted by `description.bash`
- The subscripts will take the note directory as an argument so they are portable and modular
- The Arguments will be shifted and then all passed down to subfunctions
- the script name ~~will~~ should always be printed to the terminal so the individual
script can be repurposed with out fishing through code.
- Subscripts ~~will~~ should take *only one* argument (or `STDIN` )
- If the first argument is either `-h` or `--help` help will be printed and then `exit 0`
- This might lead to some limitations but the simplicity is for sanity, modularity and extensibility.
- Will always return absolute path.
- I played around with relative path but it got confusing when calling the script from inside a function inside a script, so instead if you want a relative path you should do `scriptname './' | xargs realpath --relative-to='./'`
- Be a Front end to tie together different scripts and tools
- Don't replicate work other people have done.
- Plain Text, Free as in Speech and Beer.
- try to make modular subscripts:
- Pipe in input, output goes to STDOUT
- Leave Aliases and piping to the user
- See [Recommended Aliases ](#recommended-aliases )
2020-07-13 01:45:03 +10:00
2020-07-12 22:07:01 +10:00
## Dependencies
2020-07-17 04:28:18 +10:00
<!-- -
This was a dependency but I switched to java script
- [R ](https://en.wikipedia.org/wiki/R_(programming_language ))
-->
2020-07-20 17:00:05 +10:00
- [bat ](https://github.com/sharkdp/bat )
- [cut ](https://www.gnu.org/software/coreutils/manual/html_node/The-cut-command.html )
- [fd ](https://github.com/sharkdp/fd )
- [find ](https://man7.org/linux/man-pages/man1/find.1.html )
- [fzf ](https://github.com/junegunn/fzf )
- [GNU realpath ](https://www.gnu.org/software/coreutils/manual/html_node/realpath-invocation.html#realpath-invocation )
- [grep ](https://www.gnu.org/software/grep/ )
2020-07-12 22:08:13 +10:00
- [highlight ](https://www.archlinux.org/packages/community/x86_64/highlight/ )
2020-07-20 17:00:05 +10:00
- jq < sup > [Arch ](https://www.archlinux.org/packages/community/x86_64/jq/ ) | [brew ](https://formulae.brew.sh/formula/jq#default ) | [ubuntu ](https://packages.ubuntu.com/search?keywords=jq ) </ sup >
- [mdcat ](https://aur.archlinux.org/packages/mdcat/ )< sup > AUR</ sup >
2020-07-12 22:08:13 +10:00
- [node ](https://nodejs.org/en/ )
2020-07-20 17:00:05 +10:00
- [Pandoc ](https://github.com/jgm/pandoc )
2020-07-12 22:08:13 +10:00
- [perl ](https://wiki.archlinux.org/index.php/Perl )
- [python ](https://www.python.org/download/releases/3.0/ )
- [ranger ](https://www.archlinux.org/packages/community/any/ranger/ )
2020-07-20 17:00:05 +10:00
- [recode ](https://www.archlinux.org/packages/extra/x86_64/recode/ )
- [Recoll ](https://www.lesbonscomptes.com/recoll/ )
- [rg ](https://www.google.com/search?client=firefox-b-d&q=ripgrep+github )
- Make sure to include `pcre2` , this comes in *Arch* , if using `cargo` :
```bash
cargo install ripgrep --features 'pcre2'
```
2020-07-12 22:08:13 +10:00
- [sd ](https://github.com/chmln/sd )
- [sed ](https://www.gnu.org/software/sed/ )
2020-07-20 17:00:05 +10:00
- [skim ](https://github.com/lotabout/skim )
- [tmsu ](https://aur.archlinux.org/packages/tmsu/ )< sup > AUR</ sup >
2020-07-23 21:26:00 +10:00
- [xclip ](https://www.archlinux.org/packages/extra/x86_64/xclip/ ) or [wl-clipboard ](https://github.com/bugaevc/wl-clipboard )
2020-07-16 21:16:20 +10:00
2020-07-17 04:31:13 +10:00
### Recommended for all Features
2020-07-21 21:08:18 +10:00
- [iproute2 ](https://jlk.fjfi.cvut.cz/arch/manpages/man/ip.8 ) (for the ip binary)
2020-07-20 17:00:05 +10:00
- if you're on mac [this stackExchange ](https://superuser.com/a/898971 ) answer suggests [iproute2 ](https://formulae.brew.sh/formula/iproute2mac#default ) may work
2020-07-21 21:08:18 +10:00
- tectonic
- texlive
2020-07-17 04:31:13 +10:00
- [Kitty ](https://sw.kovidgoyal.net/kitty/ )
- I've also heard good things about [iterm2 ](https://www.iterm2.com/ )
- [MkDocs ](https://pypi.org/project/mkdocs-material-extensions/ )
- [MkDocs Material Extensions ](https://pypi.org/project/mkdocs-material-extensions/ )
2020-07-20 17:00:05 +10:00
- [MkDocs Material Theme ](https://github.com/squidfunk/mkdocs-material )
- [nvim ](https://neovim.io/ )
- [tectonic ](https://tectonic-typesetting.github.io/en-US/ )
- [WeasyPrint ](https://aur.archlinux.org/packages/python-weasyprint/ )
2020-07-17 04:31:13 +10:00
2020-07-20 17:00:05 +10:00
### Interesting / Helpful / Recommended Generally (Not strictly necessary)
2020-07-17 04:31:13 +10:00
2020-07-20 17:00:05 +10:00
- [guake ](http://guake-project.org/ ) or [yakuake ](https://kde.org/applications/en/system/org.kde.yakuake )
- [MarkText ](https://github.com/marktext/marktext )
2020-07-17 04:31:13 +10:00
- mdless
2020-07-20 17:00:05 +10:00
- [readability-cli ](https://gitlab.com/gardenappl/readability-cli )
- [VNote ](https://github.com/tamlok/vnote )
2020-07-17 04:31:13 +10:00
- VSCode
2020-07-25 09:23:26 +10:00
- [vscode-memo ](https://github.com/svsool/vscode-memo/blob/master/CHANGELOG.md )
2020-07-17 04:31:13 +10:00
2020-07-17 04:08:31 +10:00
### PATH
2020-07-20 17:00:05 +10:00
If any dependencies are installed with `pip` or `cargo` it will be necessary to add these directories to your `PATH` :
2020-07-17 04:08:31 +10:00
``` bash
## bash
echo '
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
' >> ~/.bashrc
## zsh
echo '
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
' >> ~/.bashrc
## fish
echo '
set PATH $HOME/.local/bin $PATH
set PATH $HOME/bin $PATH
set PATH "$HOME/.cargo/bin $PATH
' >> ~/.config/fish/config.fish
```
2020-07-14 01:02:06 +10:00
## Recommended Aliases
2020-07-20 17:00:05 +10:00
I wrote all this with aliases in mind, when I settle on some aliases i'll put up my `fish` functions. (I also wanted autocomplete)
## Why / Comparison with other tools
So the boxes I needed ticked are, more or less:
𐄞
| | FOSS | Offline | Linux/BSD? | terminal? | RawFiles? | Markdown | AnyEditor? |
|-----------|------|---------|------------|-----------|-----------|----------|------------|
| OneNote | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| EverNote | ❌ | ? | ❌ | ❌ | ❌ | ❌ | ❌ |
| Notable | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| Zim | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| Obsidian | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| dokuwiki | ✅ | ❌ | ✅ | ❌ | ✅ | ✅* | ✅ |
| joplin | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ † |
| mediawiki | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ ‡ |
| Org-Mode | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Cadmus | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
> † You can't open the files from vim with FZF so it gets a no. <br>
> ‡ Unlike dokuwiki everything is in a database so it gets a no <br>
> \* With a Plugin <br>
2020-07-13 00:30:51 +10:00
## Related
- [DNote]
- [TNote]
- [Notable]
[Notable]: https://github.com/notable/notable
[TNote]: https://github.com/tasdikrahman/tnote
[DNote]: https://github.com/dnote
2020-07-14 04:26:05 +10:00
[tmpfs]: https://wiki.archlinux.org/index.php/Tmpfs
2020-07-14 04:32:20 +10:00
[shared_memory]: http://en.wikipedia.org/wiki/Shared_memory
2020-07-14 01:02:06 +10:00
2020-07-14 21:28:48 +10:00
[*stow*]: https://www.google.com/search?client=firefox-b-d& q=gnu+stow