mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-05-10 08:38:32 +02:00
[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
parent
374cae687a
commit
47310f71a1
6 changed files with 98 additions and 184 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <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
|
||||
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)
|
||||
|
|
|
|||
5
docs/theme/index.html
vendored
5
docs/theme/index.html
vendored
|
|
@ -82,11 +82,6 @@
|
|||
<h3>Accessible anywhere.</h3>
|
||||
<p>Sync your journals with Dropbox and capture your thoughts where ever you are</p>
|
||||
</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>
|
||||
<i class="icon github"></i>
|
||||
<h3>Free & Open Source.</h3>
|
||||
|
|
|
|||
104
docs/usage.md
104
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 <advanced>`).
|
||||
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 <advanced>`).
|
||||
|
||||
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 <advanced>`)
|
||||
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 <advanced>`)
|
||||
|
||||
``` 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).
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue