From 6179ea43e131d3967cca59af6b368ac1463d13c3 Mon Sep 17 00:00:00 2001 From: "Guy B. deBros" Date: Sun, 17 May 2020 11:08:43 -0400 Subject: [PATCH] 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. --- docs/usage.md | 125 +++++++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 58 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index deb612be..22b7747c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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 `). + 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 `). 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 `) +## 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 `). +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.