From 47310f71a1e3204290704fe455e4901ca337fe85 Mon Sep 17 00:00:00 2001 From: Micah Jerome Ellison Date: Sat, 5 Oct 2019 15:50:04 -0700 Subject: [PATCH] [GH-666] updating documentation to reflect v2 behavior: * new config location and file type * removing mentions of DayOne support * removing mention of pip install jrnl[encrypted] --- docs/advanced.md | 80 ++++++++++---------------------- docs/installation.md | 17 +------ docs/overview.md | 4 -- docs/recipes.md | 72 +++++++++++++---------------- docs/theme/index.html | 5 -- docs/usage.md | 104 +++++++++++++++++------------------------- 6 files changed, 98 insertions(+), 184 deletions(-) diff --git a/docs/advanced.md b/docs/advanced.md index 2a6fd6b4..0375da10 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -3,15 +3,19 @@ ## Configuration File You can configure the way jrnl behaves in a configuration file. By -default, this is `~/.jrnl_config`. If you have the `XDG_CONFIG_HOME` +default, this is `~/.config/jrnl/jrnl.yaml`. If you have the `XDG_CONFIG_HOME` variable set, the configuration file will be saved as -`$XDG_CONFIG_HOME/jrnl/.jrnl_config`. +`$XDG_CONFIG_HOME/jrnl/jrnl.yaml`. !!! note - On Windows, The configuration file is typically found at `C:\Users\[Your Username]\.jrnl_config`. + On Windows, the configuration file is typically found at `%USERPROFILE%\.config\jrnl\jrnl.yaml`. -The configuration file is a simple JSON file with the following options -and can be edited with any plain text editor. +The configuration file is a YAML file with the following options +and can be edited with a plain text editor. + +!!! note + Backup your config file before editing. Changes to the config file + have destructive effects on your journal! - `journals` paths to your journal files @@ -51,46 +55,16 @@ and can be edited with any plain text editor. Or use the built-in prompt or an external editor to compose your entries. -## DayOne Integration - -Using your DayOne journal instead of a flat text file is dead simple -- -instead of pointing to a text file, change your `.jrnl_config` to point -to your DayOne journal. This is a folder named something like -`Journal_dayone` or `Journal.dayone`, and it's located at - - - `~/Library/Application Support/Day One/` by default - - `~/Dropbox/Apps/Day One/` if you're syncing with Dropbox and - - `~/Library/Mobile - Documents/5U8NS4GX82~com~dayoneapp~dayone/Documents/` if you're - syncing with iCloud. - -Instead of all entries being in a single file, each entry will live in a -separate `plist` file. So your `.jrnl_config` should look like this: - -``` javascript -{ - ... - "journals": { - "default": "~/journal.txt", - "dayone": "~/Library/Mobile Documents/5U8NS4GX82~com~dayoneapp~dayone/Documents/Journal_dayone" - } -} -``` - ## Multiple journal files You can configure `jrnl`to use with multiple journals (eg. -`private` and `work`) by defining more journals in your `.jrnl_config`, +`private` and `work`) by defining more journals in your `jrnl.yaml`, for example: -``` javascript -{ -... - "journals": { - "default": "~/journal.txt", - "work": "~/work.txt" - } -} +``` yaml +journals: + default: ~\journal.txt + work: ~\work.txt ``` The `default` journal gets created the first time you start `jrnl` @@ -106,26 +80,22 @@ will both use `~/work.txt`, while `jrnl -n 3` will display the last three entries from `~/journal.txt` (and so does `jrnl default -n 3`). You can also override the default options for each individual journal. -If you `.jrnl_config` looks like this: +If your `jrnl.yaml` looks like this: -``` javascript -{ - ... - "encrypt": false - "journals": { - "default": "~/journal.txt", - "work": { - "journal": "~/work.txt", - "encrypt": true - }, - "food": "~/my_recipes.txt", -} +``` yaml +encrypt: false +journals: +default: ~/journal.txt +work: + journal: ~/work.txt + encrypt: true +food: ~/my_recipes.txt ``` Your `default` and your `food` journals won't be encrypted, however your `work` journal will! You can override all options that are present at -the top level of `.jrnl_config`, just make sure that at the very least -you specify a `"journal": ...` key that points to the journal file of +the top level of `jrnl.yaml`, just make sure that at the very least +you specify a `journal: ...` key that points to the journal file of that journal. !!! note diff --git a/docs/installation.md b/docs/installation.md index 36b694ce..8bf29bb0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -15,27 +15,12 @@ On other platforms, install *jrnl* using pip pip install jrnl ``` -Or, if you want the option to encrypt your journal, - -``` sh -pip install jrnl[encrypted] -``` - -to install the dependencies for encrypting journals as well. - - -!!! note - Installing the encryption library, `pycrypto`, requires a `gcc` compiler. For this reason, jrnl will - not install `pycrypto` unless explicitly told so like this. You can [install PyCrypto manually](https://www.dlitz.net/software/pycrypto/) - first or install it with `pip install pycrypto` if you have a `gcc` compiler. - Also note that when using zsh, the correct syntax is `pip install "jrnl[encrypted]"` (note the quotes). - The first time you run `jrnl` you will be asked where your journal file should be created and whether you wish to encrypt it. ## Quickstart -to make a new entry, just type +To make a new entry, just type ``` sh jrnl yesterday: Called in sick. Used the time to clean the house and spent 4h on writing my book. diff --git a/docs/overview.md b/docs/overview.md index 8a0ec10f..86211814 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -8,10 +8,6 @@ files - you can put them into a Dropbox folder for instant syncing and you can be assured that your journal will still be readable in 2050, when all your fancy iPad journal applications will long be forgotten. -`jrnl` also plays nice with the fabulous -[DayOne](http://dayoneapp.com) and can read and write directly from and -to DayOne Journals. - Optionally, your journal can be encrypted using the [256-bit AES](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard). diff --git a/docs/recipes.md b/docs/recipes.md index 570b3a8c..04604e6d 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -7,7 +7,7 @@ If I want to find out how often I mentioned my flatmates Alberto and Melo in the same entry, I run -``` sh +```sh jrnl @alberto --tags | grep @melo ``` @@ -22,7 +22,7 @@ each tag occurred in this filtered journal. Finally, we pipe this to You can do things like -``` sh +```sh jrnl @fixed -starred -n 10 -until "jan 2013" --short ``` @@ -33,14 +33,14 @@ January 1, 2013 that are tagged with `@fixed`. How much did I write last year? -``` sh +```sh jrnl -from "jan 1 2013" -until "dec 31 2013" | wc -w ``` Will give you the number of words you wrote in 2013. How long is my average entry? -``` sh +```sh expr $(jrnl --export text | wc -w) / $(jrnl --short | wc -l) ``` @@ -50,11 +50,10 @@ print exactly one line per entry). ### Importing older files -If you want to import a file as an entry to jrnl, you can just do `jrnl -< entry.ext`. But what if you want the modification date of the file to +If you want to import a file as an entry to jrnl, you can just do `jrnl < entry.ext`. But what if you want the modification date of the file to be the date of the entry in jrnl? Try this -``` sh +```sh echo `stat -f %Sm -t '%d %b %Y at %H:%M: ' entry.txt` `cat entry.txt` | jrnl ``` @@ -63,7 +62,7 @@ then combine it with the contents of the file before piping it to jrnl. If you do that often, consider creating a function in your `.bashrc` or `.bash_profile` -``` sh +```sh jrnlimport () { echo `stat -f %Sm -t '%d %b %Y at %H:%M: ' $1` `cat $1` | jrnl } @@ -83,7 +82,7 @@ Another nice solution that allows you to define individual prompts comes from [Jacobo de Vera](https://github.com/maebert/jrnl/issues/194#issuecomment-47402869): -``` sh +```sh function log_question() { echo $1 @@ -102,26 +101,24 @@ For timestamps that have a space between data and time components, select fields 1 and 2 as shown. For timestamps that have no whitespace, select only field 1. -``` sh +```sh jrnl -on "$(jrnl --short | shuf -n 1 | cut -d' ' -f1,2)" ``` ## External editors To use external editors for writing and editing journal entries, set -them up in your `.jrnl_config` (see `advanced usage ` for +them up in your `jrnl.yaml` (see `advanced usage ` for details). Generally, after writing an entry, you will have to save and close the file to save the changes to jrnl. ### Sublime Text To use Sublime Text, install the command line tools for Sublime Text and -configure your `.jrnl_config` like this: +configure your `jrnl.yaml` like this: -``` json -{ - "editor": "subl -w" -} +```yaml +editor: "subl -w" ``` Note the `-w` flag to make sure jrnl waits for Sublime Text to close the @@ -133,22 +130,20 @@ Similar to Sublime Text, MacVim must be started with a flag that tells the the process to wait until the file is closed before passing control back to journal. In the case of MacVim, this is `-f`: -``` json -{ - "editor": "mvim -f" -} +<<<<<<< HEAD + +```yaml +editor: "mvim -f" ``` ### iA Writer On OS X, you can use the fabulous [iA Writer](http://www.iawriter.com/mac) to write entries. Configure your -`.jrnl_config` like this: +`jrnl.yaml` like this: -``` json -{ - "editor": "open -b pro.writer.mac -Wn" -} +```yaml +editor: "open -b pro.writer.mac -Wn" ``` What does this do? `open -b ...` opens a file using the application @@ -160,19 +155,17 @@ If the `pro.writer.mac` bundle identifier is not found on your system, you can find the right string to use by inspecting iA Writer's `Info.plist` file in your shell: -``` sh +```sh grep -A 1 CFBundleIdentifier /Applications/iA\ Writer.app/Contents/Info.plist ``` ### Notepad++ on Windows To set [Notepad++](http://notepad-plus-plus.org/) as your editor, edit -the jrnl config file (`.jrnl_config`) like this: +the jrnl config file (`jrnl.yaml`) like this: -``` json -{ - "editor": "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession", -} +```yaml +editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession" ``` The double backslashes are needed so jrnl can read the file path @@ -181,12 +174,10 @@ its own Notepad++ window. ### Visual Studio Code -To set [Visual Studo Code](https://code.visualstudio.com) as your editor on Linux, edit `.jrnl_config` like this: +To set [Visual Studo Code](https://code.visualstudio.com) as your editor on Linux, edit `jrnl.yaml` like this: -```json -{ - "editor": "/usr/bin/code --wait", -} +```yaml +editor: "/usr/bin/code --wait" ``` The `--wait` argument tells VS Code to wait for files to be written out before handing back control to jrnl. @@ -196,14 +187,13 @@ On MacOS you will need to add VS Code to your PATH. You can do that by adding: ```sh export PATH="\$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin" ``` + to your `.bash_profile`, or by running the **Install 'code' command in PATH** command from the command pallet in VS Code. Then you can add: -```javascript -{ - "editor": "code --wait", -} +```yaml +editor: "code --wait" ``` -to ``.jrnl_config``. See also the [Visual Studio Code documentation](https://code.visualstudio.com/docs/setup/mac) +to `jrnl.yaml`. See also the [Visual Studio Code documentation](https://code.visualstudio.com/docs/setup/mac) diff --git a/docs/theme/index.html b/docs/theme/index.html index 0c179210..a0f620fb 100755 --- a/docs/theme/index.html +++ b/docs/theme/index.html @@ -82,11 +82,6 @@

Accessible anywhere.

Sync your journals with Dropbox and capture your thoughts where ever you are

-
- -

DayOne compatible.

-

Read, write and search your DayOne journal from the command line.

-

Free & Open Source.

diff --git a/docs/usage.md b/docs/usage.md index fa5050a0..269bdce9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,15 +1,15 @@ # Basic Usage `jrnl` has two modes: **composing** and **viewing**. Basically, whenever -you *don't* supply any arguments that start +you _don't_ supply any arguments that start with a dash or double-dash, you're in composing mode, meaning you can write your entry on the command line or an editor of your choice. We intentionally break a convention on command line arguments: all -arguments starting with a *single dash* -will *filter* your journal before viewing +arguments starting with a _single dash_ +will _filter_ your journal before viewing it, and can be combined arbitrarily. Arguments with a -*double dash* will control how your journal +_double dash_ will control how your journal is displayed or exported and are mutually exclusive (ie. you can only specify one way to display or export your journal at a time). @@ -17,7 +17,7 @@ specify one way to display or export your journal at a time). You can list the journals accessible by jrnl -``` sh +```sh jrnl -ls ``` @@ -30,21 +30,21 @@ Composing mode is entered by either starting `jrnl` without any arguments -- which will prompt you to write an entry or launch your editor -- or by just writing an entry on the prompt, such as -``` sh +```sh jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny. ``` !!! note - Most shell contains a certain number of reserved characters, such as `#` - and `*`. Unbalanced quotes, parenthesis, and so on will also get into - the way of your editing. - For writing longer entries, just enter `jrnl` - and hit `return`. Only then enter the text of your journal entry. - Alternatively, `use an external editor `). +Most shell contains a certain number of reserved characters, such as `#` +and `*`. Unbalanced quotes, parenthesis, and so on will also get into +the way of your editing. +For writing longer entries, just enter `jrnl` +and hit `return`. Only then enter the text of your journal entry. +Alternatively, `use an external editor `). You can also import an entry directly from a file -``` sh +```sh jrnl < my_entry.txt ``` @@ -52,51 +52,51 @@ jrnl < my_entry.txt Timestamps that work: - - at 6am - - yesterday - - last monday - - sunday at noon - - 2 march 2012 - - 7 apr - - 5/20/1998 at 23:42 +- at 6am +- yesterday +- last monday +- sunday at noon +- 2 march 2012 +- 7 apr +- 5/20/1998 at 23:42 ### Starring entries To mark an entry as a favourite, simply "star" it -``` sh +```sh jrnl last sunday *: Best day of my life. ``` If you don't want to add a date (ie. your entry will be dated as now), The following options are equivalent: - - `jrnl *: Best day of my life.` - - `jrnl *Best day of my life.` - - `jrnl Best day of my life.*` +- `jrnl *: Best day of my life.` +- `jrnl *Best day of my life.` +- `jrnl Best day of my life.*` !!! note - Just make sure that the asterisk sign is **not** surrounded by - whitespaces, e.g. `jrnl Best day of my life! *` will **not** work (the - reason being that the `*` sign has a special meaning on most shells). +Just make sure that the asterisk sign is **not** surrounded by +whitespaces, e.g. `jrnl Best day of my life! *` will **not** work (the +reason being that the `*` sign has a special meaning on most shells). ## Viewing -``` sh +```sh jrnl -n 10 ``` will list you the ten latest entries (if you're lazy, `jrnl -10` will do the same), -``` sh +```sh jrnl -from "last year" -until march ``` everything that happened from the start of last year to the start of last march. To only see your favourite entries, use -``` sh +```sh jrnl -starred ``` @@ -105,20 +105,20 @@ jrnl -starred Keep track of people, projects or locations, by tagging them with an `@` in your entries -``` sh +```sh jrnl Had a wonderful day on the @beach with @Tom and @Anna. ``` You can filter your journal entries just like this: -``` sh +```sh jrnl @pinkie @WorldDomination ``` Will print all entries in which either `@pinkie` or `@WorldDomination` occurred. -``` sh +```sh jrnl -n 5 -and @pineapple @lubricant ``` @@ -127,18 +127,18 @@ You can change which symbols you'd like to use for tagging in the configuration. !!! note - `jrnl @pinkie @WorldDomination` will switch to viewing mode because - although **no** command line arguments are given, all the input strings - look like tags - *jrnl* will assume you want to filter by tag. +`jrnl @pinkie @WorldDomination` will switch to viewing mode because +although **no** command line arguments are given, all the input strings +look like tags - _jrnl_ will assume you want to filter by tag. ## Editing older entries You can edit selected entries after you wrote them. This is particularly -useful when your journal file is encrypted or if you're using a DayOne -journal. To use this feature, you need to have an editor configured in -your journal configuration file (see `advanced usage `) +useful when your journal file is encrypted. To use this feature, you need +to have an editor configured in your journal configuration file (see +`advanced usage `) -``` sh +```sh jrnl -until 1950 @texas -and @history --edit ``` @@ -153,30 +153,8 @@ encrypt) your edited journal after you save and exit the editor. You can also use this feature for deleting entries from your journal -``` sh +```sh jrnl @girlfriend -until 'june 2012' --edit ``` Just select all text, press delete, and everything is gone... - -### Editing DayOne Journals - -DayOne journals can be edited exactly the same way, however the output -looks a little bit different because of the way DayOne stores its -entries: - -```md -# af8dbd0d43fb55458f11aad586ea2abf -2013-05-02 15:30 I told everyone I built my @robot wife for sex. -But late at night when we're alone we mostly play Battleship. - -# 2391048fe24111e1983ed49a20be6f9e -2013-08-10 03:22 I had all kinds of plans in case of a @zombie attack. -I just figured I'd be on the other side. -``` - -The long strings starting with hash symbol are the so-called UUIDs, -unique identifiers for each entry. Don't touch them. If you do, then the -old entry would get deleted and a new one written, which means that you -could lose DayOne data that jrnl can't handle (such as as the entry's -geolocation).