mirror/cadmus
1
0
Fork 0
mirror of https://github.com/RyanGreenup/cadmus.git synced 2025-01-16 20:28:31 +01:00
Code Issues Releases Wiki Activity

Updated Readme to Reflect Install Script

Browse Source
This commit is contained in:
Ryan Greenup 2020-07-20 17:00:05 +10:00
parent a68010a252
commit 4a65bdcb57
4 changed files with 125 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
README.md
View File

@ -3,41 +3,28 @@ Shell Scripts to Facilitate Effective Note Taking
## Introduction
Essentially I ~~used to~~ have a dozen shell scripts in `~/bin` that I use to capture notes,
this is an attempt to wrap them into a single script and then have aliases to make them quick to access.
This is a **self-contained** shell script that uses pre-existing tools (such as TMSU and recoll) to provide an interface for markdown notes.
![](./MainMenu.png)
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:
The idea is that it is just a menu to dispatch different scripts so I could
share those scripts with classmates.
## Design Philosophy
![Mindmap of Program Flow](./usage.svg "Diagram of the flow of the script")
- ****<span style="color:rgb(90,210,90);font-family:Courier New,Courier, monospace,serif;">cadmus</span>**** acts as a menu for scripts to acheive things
- 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, Open Source.
- Be Modular
- Pipe in input, output goes to STDOUT
- Leave Aliases and piping to the user
- See [Recommended Aliases](#recommended-aliases)
- ****<span style="color:rgb(90,210,90);font-family:Courier New,Courier, monospace,serif;">cadmus</span>**** will take the notes directory from the global variable `CADMUS_NOTES_DIR`
- 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
and an overview of what it looks like in the terminal
![](./media/Many_Examples.png)
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.
## Installation
Cadmus will work from within a self-contained directory, in this way it's zero lock-in and does not modify your system other than a single simlink into "~/.local/bin".
### Automatic
Copy this into your shell:
Installation will automatically create a config file in its directory, to install automatically just run the following command and follow the prompts:
``` bash
cd $(mktemp -d)
@ -45,6 +32,14 @@ wget https://raw.githubusercontent.com/RyanGreenup/cadmus/master/install.sh
bash install.sh
```
- 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
To install manually:
1. satisfy [the dependencies](#Dependencies)
@ -64,37 +59,32 @@ To install manually:
```
4. When first running the script it will prompt you to make a config file in the directory in which it is run.
> When first run, the script will prompt you to make a config file in the directory in which it is run.
### Assumptions
It is assumed that:
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
<!---
4. Copy the help files to `/usr/share/cadmus`
5. Copy in the scripts, with [*stow*] something like this should be sensible:
```bash
exec bash
cd ~/DotFiles
if [[ -d ".git" ]]; then
echo "Adding Submodule";
git submodule add https://github.com/RyanGreenup/cadmus
else echo "Cloning Repository";
git clone https://github.com/RyanGreenup/cadmus
fi
stow -t $HOME -S cadmus
```
|:warning: WARNING |
| --- |
| Stow is [currently broken][stowIssue] on Arch If you are using Stow 2.3.1-2 downgrade |
> Downgrade with:
> sudo pacman -U https://archive.archlinux.org/packages/s/stow/stow-2.2.2-5-any.pkg.tar.xz
[stowIssue]: https://github.com/aspiers/stow/issues/65 -->
-->
### Configuring recoll
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.
@ -116,47 +106,29 @@ then select *index configuration* and configure recoll to have `~/Notes/MD` as t
| 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>**** |
-->
## Usage
It's all Menu driven so just follow the diagram to do what you need.
![Mindmap of Program Flow](./usage.svg "Diagram of the flow of the script")
## Design Philosophy
### Assumptions
It is assumed that:
1. Notes are:
1. *Markdown* files with a `.md` extension
2. Underneath `~/Notes` (you ma)
3. Recoll updates it's index on the fly
* `~/Notes` will need to be indexed by *Recoll* so the results will show up.
3. SSD
* I use an SSD and some scripts are pretty inefficient (like `grep | cut |
xargs find` to avoid creating a variable), I don't know if things like
would work on a HDD.
5. All Notes have Unique Names
6. On *MacOS* you'll need to define `xdg-open` so do something like:
```bash
alias xdg-open='open &>/dev/null'
```
<!---
2. You're going to use [Kitty](https://sw.kovidgoyal.net/kitty/)
* You could either change the source or use anoter terminal that supports
calling functions with `--`, e.g. `kitty -- nvim`
-->
<!---
5. I use [*Fish*] and *Oh My Fish* ([*OMF*]) as my default shell, this means `basename $SHELL` is `fish` for
me and even though this is written in `bash` maybe that could cause issues.
* Try [*Fish*] for a while, it's quite good, when you need to test something
it's easy to temporarily jump back with `exec zsh`.
* I wonder if this would work for [*nushell*]???
-->
[*nushell*]: https://github.com/nushell/nushell
[*Fish*]: https://fishshell.com/
[*OMF*]: https://github.com/oh-my-fish/oh-my-fish
- ****<span style="color:rgb(90,210,90);font-family:Courier New,Courier, monospace,serif;">cadmus</span>**** acts as a menu for scripts to acheive things
- 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)
## Dependencies
@ -164,57 +136,60 @@ It is assumed that:
This was a dependency but I switched to java script
- [R](https://en.wikipedia.org/wiki/R_(programming_language))
-->
- [highlight](https://www.archlinux.org/packages/community/x86_64/highlight/)
- [ip](https://jlk.fjfi.cvut.cz/arch/manpages/man/ip.8)
- [recode](https://www.archlinux.org/packages/extra/x86_64/recode/)
- [node](https://nodejs.org/en/)
- [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)
- [skim](https://github.com/lotabout/skim)
- [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'
```
- [GNU realpath](https://www.gnu.org/software/coreutils/manual/html_node/realpath-invocation.html#realpath-invocation)
- [grep](https://www.gnu.org/software/grep/)
- [highlight](https://www.archlinux.org/packages/community/x86_64/highlight/)
- 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>
- [node](https://nodejs.org/en/)
- [Pandoc](https://github.com/jgm/pandoc)
- [perl](https://wiki.archlinux.org/index.php/Perl)
- [python](https://www.python.org/download/releases/3.0/)
- [tmsu](https://aur.archlinux.org/packages/tmsu/)<sup>AUR</sup>
- [ranger](https://www.archlinux.org/packages/community/any/ranger/)
- [mdcat](https://aur.archlinux.org/packages/mdcat/)<sup>AUR</sup>
- [xclip](https://www.archlinux.org/packages/extra/x86_64/xclip/)
- [sd](https://github.com/chmln/sd)
- [fd](https://github.com/sharkdp/fd)
- [sed](https://www.gnu.org/software/sed/)
- [cut](https://www.gnu.org/software/coreutils/manual/html_node/The-cut-command.html)
- [grep](https://www.gnu.org/software/grep/)
- [find](https://man7.org/linux/man-pages/man1/find.1.html)
- [GNU realpath](https://www.gnu.org/software/coreutils/manual/html_node/realpath-invocation.html#realpath-invocation)
- [recode](https://www.archlinux.org/packages/extra/x86_64/recode/)
- [Recoll](https://www.lesbonscomptes.com/recoll/)
- [Pandoc](https://github.com/jgm/pandoc)
- [bat](https://github.com/sharkdp/bat)
- [jq]
- [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'
```
- [sd](https://github.com/chmln/sd)
- [sed](https://www.gnu.org/software/sed/)
- [skim](https://github.com/lotabout/skim)
- [tmsu](https://aur.archlinux.org/packages/tmsu/)<sup>AUR</sup>
- [xclip](https://www.archlinux.org/packages/extra/x86_64/xclip/)
### Recommended for all Features
- [WeasyPrint](https://aur.archlinux.org/packages/python-weasyprint/)
- [tectonic](https://tectonic-typesetting.github.io/en-US/)
- [nvim](https://neovim.io/)
- [ip](https://jlk.fjfi.cvut.cz/arch/manpages/man/ip.8)
- if you're on mac [this stackExchange](https://superuser.com/a/898971) answer suggests [iproute2](https://formulae.brew.sh/formula/iproute2mac#default) may work
- [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 Theme](https://github.com/squidfunk/mkdocs-material)
- [MkDocs Material Extensions](https://pypi.org/project/mkdocs-material-extensions/)
- [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/)
### Interesting / Helpful / Recommended Generally (Not strictly necessary)
- [guake](http://guake-project.org/) or [yakuake](https://kde.org/applications/en/system/org.kde.yakuake)
- [MarkText](https://github.com/marktext/marktext)
- [VNote](https://github.com/tamlok/vnote)
### recommended / Interesting / Helpful packages not required
- [readability-cli](https://gitlab.com/gardenappl/readability-cli)
- mdless
- [readability-cli](https://gitlab.com/gardenappl/readability-cli)
- [VNote](https://github.com/tamlok/vnote)
- VSCode
### PATH
If installed with `pip` or `cargo` it will be necessary to add these directories to your `PATH`:
If any dependencies are installed with `pip` or `cargo` it will be necessary to add these directories to your `PATH`:
``` bash
## bash
@ -240,7 +215,29 @@ set PATH "$HOME/.cargo/bin $PATH
## Recommended Aliases
I wrote all this with aliases in mind, when I settle on some aliases i'll put up my `fish` functions. (I also wanted to do some autocomplete.)
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>
## Related

BIN
media/Many_Commands_Bigger.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 419 KiB

BIN
media/Many_Examples.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 167 KiB

BIN
media/TagsExample.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.7 MiB