From ea14e487591f6c1edf9e1151a1227ec8d7568d78 Mon Sep 17 00:00:00 2001 From: "Guy B. deBros" Date: Wed, 27 May 2020 17:07:43 -0400 Subject: [PATCH] Cleaned up usage.md for clarity, formatting, and grammar. (#956) * 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. * more changes to the usage page Includes information about two new functions (`--delete`) and (`-contains`). It's starting to look quite different from the original... --- docs/usage.md | 238 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 156 insertions(+), 82 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index deb612be8..d56c94182 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,56 +1,44 @@ -# Basic Usage +# 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 +## Composing Entries ## -You can list the journals accessible by jrnl +Composing mode is entered by either starting `jrnl` without any arguments -- +which will launch an external editor -- or by just writing an entry on the +command line: ```sh -jrnl -ls -``` - -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 - -```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! What a nice guy. ``` !!! 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](./advanced.md)). -You can also import an entry directly from a file +You can also import an entry directly from a file: ```sh jrnl < my_entry.txt ``` -### Smart timestamps +### Specifying Date and Time ### -Timestamps that work: +If you don't specify a date and time (e.g., `jrnl finished writing letter to brother`), `jrnl` will create an entry using the current date and time. For retrospective entries, you can use a timestamp to tell `jrnl` where to put the entry. Timestamps can be entered using a variety of formats. Here are some that work: - at 6am - yesterday @@ -59,102 +47,188 @@ Timestamps that work: - 2 march 2012 - 7 apr - 5/20/1998 at 23:42 +- 2020-05-22T15:55-04:00 + +If you don't use a timestamp, `jrnl` will create an entry using the current +time. If you use a date only (no time), `jrnl` will use the default time +specified in your configuration file (see [advanced usage](./advanced.md)). +Behind the scenes, `jrnl` reorganizes entries in chronological order. + +### Using Tags ### + +`jrnl` supports tags. Note that because `#` is a reserved character, the default +tag symbol is `@`. You can specify your own tag symbol in the configuration +file. There is no limit to how many tags you can use in an entry. To use tags, +simply preface the desired tag with the symbol: + +```sh +jrnl Had a wonderful day at the @beach with @Tom and @Anna. +``` + +Although you can use capitals while tagging an entry, searches by tag are +case-insensitive. -### Starring entries +### Starring Entries ### -To mark an entry as a favourite, simply "star" it +To mark an entry as a favorite, simply "star" it using an asterisk (`*`): ```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). +!!! note Make sure that the asterisk (`*`) is **not** surrounded by whitespaces. +`jrnl Best day of my life! *` will not work because the `*` character has a +special meaning in most shells. -## Viewing +## Viewing Entries ## + +`jrnl` can display entries in a variety of ways. Entries are filtered using commands preceded by a single dash (`-`). Type `jrnl -h` for a list of +commands. + +It is possible to see all entries by entering `jrnl -until today`. However, in +most cases you will likely want to use a filter to see specific entries that +meet certain criteria. `jrnl` provides several filtering commands, prefaced by a +single dash (`-`), that allow you to find exactly what you're looking for. For +example, ```sh 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` is even more concise and works the +same way. If you want to see all of the entries you wrote from the beginning of +last year until the end of this past March, you would enter ```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 +Filter criteria that use more than one word require surrounding quotes (`""`). -```sh -jrnl -starred -``` +### Text Search ### -## Using Tags +The `-contains` command displays all entries containing a specific string. This +may be helpful when you're searching for entries and you can't remember if you +tagged any words when you wrote them. -Keep track of people, projects or locations, by tagging them with an `@` -in your entries +You may realize that you use a word a lot and want to turn it into a tag in all +of your previous entries. ```sh -jrnl Had a wonderful day on the @beach with @Tom and @Anna. +jrnl -contains "dogs" --edit ``` -You can filter your journal entries just like this: +opens your external editor so that you can add a tag symbol (`@` by default) to +all instances of the word "dogs." + +### Filtering by Tag ### + +You can filter your journal entries by tag. For example, ```sh jrnl @pinkie @WorldDomination ``` -Will print all entries in which either `@pinkie` or `@WorldDomination` -occurred. +displays all entries in which either `@pinkie` or `@WorldDomination` +occurred. Tag filters can be combined with other filters: ```sh -jrnl -n 5 -and @pinkie @WorldDomination +jrnl -n 5 @pinkie -and @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 +### Viewing Starred 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 `) +To display only your favorite (starred) entries, enter + +```sh +jrnl -starred +``` + +## Editing 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. 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). + +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, + +```sh +jrnl work -n 1 --edit +``` + +opens the most recent entry in the 'work' journal in your external editor. -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. +## Deleting Entries ## -You can also use this feature for deleting entries from your journal +The `--delete` command opens an interactive interface for deleting entries. The +date and title of each entry in the journal are presented one at a time, and you +can choose whether to keep or delete each entry. + +If no filters are specified, `jrnl` will ask you to keep or delete each entry in +the entire journal, one by one. If there are a lot of entries in the journal, it +may be more efficient to filter entries before passing the `--delete` command. + +Here's an example. Say you have a journal into which you've imported the last 12 +years of blog posts. You use the `@book` tag a lot, and for some reason you want +to delete some, but not all, of the entries in which you used that tag, but only +the ones you wrote at some point in 2004 or earlier. You're not sure which +entries you want to keep, and you want to look through them before deciding. +This is what you might enter: ```sh -jrnl @texas -until 'june 2012' --edit +jrnl -to 2004 @book --delete +``` + +`jrnl` will show you only the relevant entries, and you can choose the ones you +want to delete. + +You may want to delete _all_ of the entries containing `@book` that you wrote in +2004 or earlier. If there are dozens or hundreds, the easiest way would be to +use an external editor. Open an editor with the entries you want to delete... + +```sh +jrnl -to 2004 @book --edit +``` + +...select everything, delete it, save and close, and all of those entries are +removed from the journal. + +## Listing Journals ## + +To list all of your journals: + +```sh +jrnl -ls ``` -Just select all text, press delete, and everything is gone... +The journals displayed correspond to those specified in the `jrnl` configuration +file.