Cleaned up usage.md for clarity, formatting, and grammar.

While working on it, I hard-wrapped the lines to 80 characters. Hope that doesn't complicate things.

Note: I changed the Steve Buscemi quote to maintain compliance with the Code of Conduct.
This commit is contained in:
Guy B. deBros 2020-05-17 11:08:43 -04:00
parent 732831695f
commit 6179ea43e1

View file

@ -1,46 +1,45 @@
# Basic Usage
`jrnl` has two modes: **composing** and **viewing**. Basically, whenever
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.
`jrnl` has two modes: **composing** and **viewing**. Whenever you don't enter
any arguments that start with a dash (`-`) or double-dash (`--`), you're in
composing mode, meaning that you can write your entry on the command line.
We intentionally break a convention on command line arguments: all
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
is displayed or exported and are mutually exclusive (ie. you can only
specify one way to display or export your journal at a time).
We intentionally break a convention on command line arguments: all arguments
starting with a _single dash_ (`-`) will _filter_ your journal before viewing
it. Filter arguments can be combined arbitrarily. Arguments with a _double dash_
(`--`) will _control_ how your journal is displayed or exported. Control
arguments are mutually exclusive (i.e., you can only specify one way to display
or export your journal at a time).
## Listing Journals
You can list the journals accessible by jrnl
You can list the journals accessible by `jrnl`:
```sh
jrnl -ls
```
The journals displayed correspond to those specified in the jrnl
configuration file.
The journals displayed correspond to those specified in the `jrnl` configuration
file.
## Composing Entries
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
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
jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny.
jrnl today at 3am: I just met Steve Buscemi in a bar! He was on fire.
```
!!! 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 shells contain a certain number of reserved characters, such as `#` and
`*`. These characters, as well as unbalanced single or double quotation
marks, parentheses, and others, likely will cause problems. Although
reserved characters can be escaped using `\`, this is not ideal for
long-form writing. The solution: first enter `jrnl` and hit `return`. You
can then enter the text of your journal entry. Alternatively, you can `use
an external editor <advanced>`).
You can also import an entry directly from a file
@ -62,23 +61,23 @@ Timestamps that work:
### Starring entries
To mark an entry as a favourite, simply "star" it
To mark an entry as a favorite, simply "star" it
```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:
If you don't want to add a date (i.e., you want the date to be entered 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.*`
!!! 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).
Make sure that the asterisk sign is **not** surrounded by whitespaces. `jrnl
Best day of my life! *` will not work because the `*` sign has a special
meaning in most shells).
## Viewing
@ -86,15 +85,15 @@ The following options are equivalent:
jrnl -n 10
```
will list you the ten latest entries (if you're lazy, `jrnl -10` will do
the same),
lists the ten most recent entries (`jrnl -10` works the same way).
```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
displays everything that happened from the beginning of last year until the
beginning of the past March. To display only your favorite (starred) entries,
use
```sh
jrnl -starred
@ -103,58 +102,68 @@ jrnl -starred
## Using Tags
Keep track of people, projects or locations, by tagging them with an `@`
in your entries
in your entries:
```sh
jrnl Had a wonderful day on the @beach with @Tom and @Anna.
jrnl Had a wonderful day at the @beach with @Tom and @Anna.
```
You can filter your journal entries just like this:
You can filter your journal entries by tag. For example,
```sh
jrnl @pinkie @WorldDomination
```
Will print all entries in which either `@pinkie` or `@WorldDomination`
displays all entries in which either `@pinkie` or `@WorldDomination`
occurred.
```sh
jrnl -n 5 -and @pinkie @WorldDomination
```
the last five entries containing both `@pinkie` **and** `@worldDomination`.
You can change which symbols you'd like to use for tagging in the
configuration.
displays the last five entries containing both `@pinkie` **and**
`@worldDomination`. 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.
Entering `jrnl @pinkie @WorldDomination` will display entries in which both
tags are present because, although no command line arguments are given, all
of the input strings look like tags. `jrnl` will assume you want to filter
by tag, rather than create a new entry that consists only of tags.
## Editing older entries
You can edit selected entries after you wrote them. This is particularly
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>`)
## Editing Existing Entries
You can edit entries after writing them. This is particularly useful when your
journal file is encrypted. To use this feature, you need to have an external
editor configured in your configuration file (see `advanced usage <advanced>`).
You can also edit only the entries that match specific search criteria. For
example,
```sh
jrnl -until 1950 @texas -and @history --edit
```
Will open your editor with all entries tagged with `@texas` and
`@history` before 1950. You can make any changes to them you want; after
you save the file and close the editor, your journal will be updated.
opens your external editor displaying all entries tagged with `@texas` and
`@history` that were written before 1950. After making changes, save and close
the file, and only those entries will be modified (and encrypted, if
applicable).
Of course, if you are using multiple journals, you can also edit e.g.
the latest entry of your work journal with `jrnl work -n 1 --edit`. In
any case, this will bring up your editor and save (and, if applicable,
encrypt) your edited journal after you save and exit the editor.
If you are using multiple journals, it's easy to edit specific entries from
specific journals. Simply prefix the filter string with the name of the journal.
For example,
You can also use this feature for deleting entries from your journal
```sh
jrnl work -n 1 --edit
```
opens the most recent entry in the 'work' journal in your external editor.
You can also use this feature for deleting entries from your journal. Open an external editor with the entries you want to delete...
```sh
jrnl @texas -until 'june 2012' --edit
```
Just select all text, press delete, and everything is gone...
...select all text, delete it, save and close, and all of those entries are
removed from the journal.