[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]
This commit is contained in:
Micah Jerome Ellison 2019-10-05 15:50:04 -07:00
parent 374cae687a
commit 47310f71a1
6 changed files with 98 additions and 184 deletions

View file

@ -3,15 +3,19 @@
## Configuration File ## Configuration File
You can configure the way jrnl behaves in a configuration file. By 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 variable set, the configuration file will be saved as
`$XDG_CONFIG_HOME/jrnl/.jrnl_config`. `$XDG_CONFIG_HOME/jrnl/jrnl.yaml`.
!!! note !!! 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 The configuration file is a YAML file with the following options
and can be edited with any plain text editor. 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` - `journals`
paths to your journal files 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 Or use the built-in prompt or an external editor to compose your
entries. 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 ## Multiple journal files
You can configure `jrnl`to use with multiple journals (eg. 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: for example:
``` javascript ``` yaml
{ journals:
... default: ~\journal.txt
"journals": { work: ~\work.txt
"default": "~/journal.txt",
"work": "~/work.txt"
}
}
``` ```
The `default` journal gets created the first time you start `jrnl` 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`). three entries from `~/journal.txt` (and so does `jrnl default -n 3`).
You can also override the default options for each individual journal. 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 ``` yaml
{ encrypt: false
... journals:
"encrypt": false default: ~/journal.txt
"journals": { work:
"default": "~/journal.txt", journal: ~/work.txt
"work": { encrypt: true
"journal": "~/work.txt", food: ~/my_recipes.txt
"encrypt": true
},
"food": "~/my_recipes.txt",
}
``` ```
Your `default` and your `food` journals won't be encrypted, however your Your `default` and your `food` journals won't be encrypted, however your
`work` journal will! You can override all options that are present at `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 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 you specify a `journal: ...` key that points to the journal file of
that journal. that journal.
!!! note !!! note

View file

@ -15,27 +15,12 @@ On other platforms, install *jrnl* using pip
pip install jrnl 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 The first time you run `jrnl` you will be asked where your journal file
should be created and whether you wish to encrypt it. should be created and whether you wish to encrypt it.
## Quickstart ## Quickstart
to make a new entry, just type To make a new entry, just type
``` sh ``` sh
jrnl yesterday: Called in sick. Used the time to clean the house and spent 4h on writing my book. jrnl yesterday: Called in sick. Used the time to clean the house and spent 4h on writing my book.

View file

@ -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, you can be assured that your journal will still be readable in 2050,
when all your fancy iPad journal applications will long be forgotten. 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 Optionally, your journal can be encrypted using the [256-bit
AES](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard). AES](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard).

View file

@ -50,8 +50,7 @@ print exactly one line per entry).
### Importing older files ### Importing older files
If you want to import a file as an entry to jrnl, you can just do `jrnl 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
< entry.ext`. But what if you want the modification date of the file to
be the date of the entry in jrnl? Try this be the date of the entry in jrnl? Try this
```sh ```sh
@ -109,19 +108,17 @@ jrnl -on "$(jrnl --short | shuf -n 1 | cut -d' ' -f1,2)"
## External editors ## External editors
To use external editors for writing and editing journal entries, set To use external editors for writing and editing journal entries, set
them up in your `.jrnl_config` (see `advanced usage <advanced>` for them up in your `jrnl.yaml` (see `advanced usage <advanced>` for
details). Generally, after writing an entry, you will have to save and details). Generally, after writing an entry, you will have to save and
close the file to save the changes to jrnl. close the file to save the changes to jrnl.
### Sublime Text ### Sublime Text
To use Sublime Text, install the command line tools for Sublime Text and 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 ```yaml
{ editor: "subl -w"
"editor": "subl -w"
}
``` ```
Note the `-w` flag to make sure jrnl waits for Sublime Text to close the 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 the the process to wait until the file is closed before passing control
back to journal. In the case of MacVim, this is `-f`: back to journal. In the case of MacVim, this is `-f`:
``` json <<<<<<< HEAD
{
"editor": "mvim -f" ```yaml
} editor: "mvim -f"
``` ```
### iA Writer ### iA Writer
On OS X, you can use the fabulous [iA On OS X, you can use the fabulous [iA
Writer](http://www.iawriter.com/mac) to write entries. Configure your Writer](http://www.iawriter.com/mac) to write entries. Configure your
`.jrnl_config` like this: `jrnl.yaml` like this:
``` json ```yaml
{ editor: "open -b pro.writer.mac -Wn"
"editor": "open -b pro.writer.mac -Wn"
}
``` ```
What does this do? `open -b ...` opens a file using the application What does this do? `open -b ...` opens a file using the application
@ -167,12 +162,10 @@ grep -A 1 CFBundleIdentifier /Applications/iA\ Writer.app/Contents/Info.plist
### Notepad++ on Windows ### Notepad++ on Windows
To set [Notepad++](http://notepad-plus-plus.org/) as your editor, edit 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 ```yaml
{ editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession"
"editor": "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession",
}
``` ```
The double backslashes are needed so jrnl can read the file path The double backslashes are needed so jrnl can read the file path
@ -181,12 +174,10 @@ its own Notepad++ window.
### Visual Studio Code ### 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 ```yaml
{ editor: "/usr/bin/code --wait"
"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. 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 ```sh
export PATH="\$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin" 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. 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: Then you can add:
```javascript ```yaml
{ editor: "code --wait"
"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)

View file

@ -82,11 +82,6 @@
<h3>Accessible anywhere.</h3> <h3>Accessible anywhere.</h3>
<p>Sync your journals with Dropbox and capture your thoughts where ever you are</p> <p>Sync your journals with Dropbox and capture your thoughts where ever you are</p>
</section> </section>
<section>
<i class="icon dayone"></i>
<h3>DayOne compatible.</h3>
<p>Read, write and search your DayOne journal from the command line.</p>
</section>
<section> <section>
<i class="icon github"></i> <i class="icon github"></i>
<h3>Free &amp; Open Source.</h3> <h3>Free &amp; Open Source.</h3>

View file

@ -1,15 +1,15 @@
# Basic Usage # Basic Usage
`jrnl` has two modes: **composing** and **viewing**. Basically, whenever `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 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. write your entry on the command line or an editor of your choice.
We intentionally break a convention on command line arguments: all We intentionally break a convention on command line arguments: all
arguments starting with a *single dash* arguments starting with a _single dash_
will *filter* your journal before viewing will _filter_ your journal before viewing
it, and can be combined arbitrarily. Arguments with a 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 is displayed or exported and are mutually exclusive (ie. you can only
specify one way to display or export your journal at a time). specify one way to display or export your journal at a time).
@ -129,14 +129,14 @@ configuration.
!!! note !!! note
`jrnl @pinkie @WorldDomination` will switch to viewing mode because `jrnl @pinkie @WorldDomination` will switch to viewing mode because
although **no** command line arguments are given, all the input strings although **no** command line arguments are given, all the input strings
look like tags - *jrnl* will assume you want to filter by tag. look like tags - _jrnl_ will assume you want to filter by tag.
## Editing older entries ## Editing older entries
You can edit selected entries after you wrote them. This is particularly 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 useful when your journal file is encrypted. To use this feature, you need
journal. To use this feature, you need to have an editor configured in to have an editor configured in your journal configuration file (see
your journal configuration file (see `advanced usage <advanced>`) `advanced usage <advanced>`)
```sh ```sh
jrnl -until 1950 @texas -and @history --edit jrnl -until 1950 @texas -and @history --edit
@ -158,25 +158,3 @@ jrnl @girlfriend -until 'june 2012' --edit
``` ```
Just select all text, press delete, and everything is gone... 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).