diff --git a/docs/advanced.md b/docs/advanced.md index a9f1fb27b..c0b1195cb 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -5,109 +5,15 @@ ## Configuration File -You can configure the way jrnl behaves in a configuration file. By -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.yaml`. - -!!! note - On Windows, the configuration file is typically found at `%USERPROFILE%\.config\jrnl\jrnl.yaml`. - -The configuration file is a YAML file with the following options -and can be edited with a plain text editor. - -!!! note - Backup your journal and config file before editing. Changes to the config file - can have destructive effects on your journal! - -- `journals` - paths to your journal files -- `editor` - if set, executes this command to launch an external editor for - writing your entries, e.g. `vim`. Some editors require special - options to work properly, see `FAQ ` for details. -- `encrypt` - if `true`, encrypts your journal using AES. -- `tagsymbols` - Symbols to be interpreted as tags. (See note below) -- `default_hour` and `default_minute` - if you supply a date, such as `last thursday`, but no specific - time, the entry will be created at this time -- `timeformat` - how to format the timestamps in your journal, see the [python docs](http://docs.python.org/library/time.html#time.strftime) for reference -- `highlight` - if `true`, tags will be highlighted in cyan. -- `linewrap` - controls the width of the output. Set to `false` if you don't want to wrap long lines. -- `colors` - dictionary that controls the colors used to display journal entries. It has four subkeys, which are: `body`, `date`, `tags`, and `title`. Current valid values are: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`, and `NONE`. `colorama.Fore` is used for colorization, and you can find the [docs here](https://github.com/tartley/colorama#colored-output). To disable colored output, set the value to `NONE`. If you set the value of any color subkey to an invalid color, no color will be used. -- `display_format` - specifies formatter to use, formatters available are: - `boxed`, `fancy`, `json`, `markdown`, `md`, `tags`, `text`, `txt`, `xml`, or `yaml`. - -!!! note - Although it seems intuitive to use the `#` - character for tags, there's a drawback: on most shells, this is - interpreted as a meta-character starting a comment. This means that if - you type - - > `jrnl Implemented endless scrolling on the #frontend of our website.` - - your bash will chop off everything after the `#` before passing it to - `jrnl`. To avoid this, wrap your input into quotation marks like - this: - - > `jrnl "Implemented endless scrolling on the #frontend of our website."` - - Or use the built-in prompt or an external editor to compose your - entries. - -### Modifying Configurations from the Command line - -You can override a configuration field for the current instance of `jrnl` using `--config-override CONFIG_KEY CONFIG_VALUE` where `CONFIG_KEY` is a valid configuration field, specified in dot-notation and `CONFIG_VALUE` is the (valid) desired override value. - -You can specify multiple overrides as multiple calls to `--config-override`. -!!! note - These overrides allow you to modify ***any*** field of your jrnl configuration. We trust that you know what you are doing. - -#### Examples: - -``` sh -#Create an entry using the `stdin` prompt, for rapid logging -jrnl --config-override editor "" - -#Populate a project's log -jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel - -#Pass multiple overrides -jrnl --config-override display_format fancy --config-override linewrap 20 \ ---config-override colors.title green - -``` - -### Using an alternate config - -You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where -`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file. - -#### Examples: - -``` -# Use personalised configuration file for personal journal entries -jrnl --config-file ~/foo/jrnl/personal-config.yaml - -# Use alternate configuration file for work-related entries -jrnl --config-file ~/foo/jrnl/work-config.yaml - -# Use default configuration file (created on installation) -jrnl -``` +`jrnl` has a wide variety of options that can be customized through the config file, +including templates, formats, multiple journals, and more. See +the [configuration file reference](./reference-config-file.md) for details +or read on for some common use cases. - -## Multiple journal files +### Multiple journal files You can configure `jrnl`to use with multiple journals (eg. -`private` and `work`) by defining more journals in your `jrnl.yaml`, +`private` and `work`) by defining more journals in your [config file](./reference-config-file.md), for example: ``` yaml @@ -167,12 +73,46 @@ journals: The `work` journal is encrypted, prints to `json` by default, and is edited using an existing window of VSCode. Similarly, the `food` journal prints to markdown by default, but uses all the other defaults. +### Modifying Configurations from the Command line + +You can override a configuration field for the current instance of `jrnl` using `--config-override CONFIG_KEY CONFIG_VALUE` where `CONFIG_KEY` is a valid configuration field, specified in dot notation and `CONFIG_VALUE` is the (valid) desired override value. The dot notation can be used to change config keys within other keys, such as `colors.title` for the `title` key within the `colors` key. + +You can specify multiple overrides as multiple calls to `--config-override`. !!! note - Changing `encrypt` to a different value will not encrypt or decrypt your - journal file, it merely says whether or not your journal - is encrypted. Hence manually changing - this option will most likely result in your journal file being - impossible to load. + These overrides allow you to modify ***any*** field of your jrnl configuration. We trust that you know what you are doing. + +#### Examples: + +``` sh +#Create an entry using the `stdin` prompt, for rapid logging +jrnl --config-override editor "" + +#Populate a project's log +jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel + +#Pass multiple overrides +jrnl --config-override display_format fancy --config-override linewrap 20 \ +--config-override colors.title green + +``` + +### Using an alternate config + +You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where +`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file. + +#### Examples: + +``` +# Use personalised configuration file for personal journal entries +jrnl --config-file ~/foo/jrnl/personal-config.yaml + +# Use alternate configuration file for work-related entries +jrnl --config-file ~/foo/jrnl/work-config.yaml + +# Use default configuration file (created on first run) +jrnl +``` ## Known Issues diff --git a/docs/contributing.md b/docs/contributing.md index 71c1d3375..b12ce7bea 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -28,9 +28,9 @@ To edit the documentation, edit the `docs/*.md` files on the **develop** branch. The `gh-pages` branch is automatically maintained and generated after your changes are merged. You should never have to edit that branch. -### Recipes and external editors +### External editors and tips and tricks -If you'd like to share a jrnl command line trick that you find useful, or advice on how to integrate a particular external editor, you may find it worthwhile to add it to the ["Recipes" section](recipes.md). +If you'd like to share a jrnl command line trick that you find useful, you may find it worthwhile to add it to the ["Tips and Tricks" section](tips-and-tricks.md). For advice on how to integrate a particular external editor, you can add to the ["External Editors" section](external-editors.md). ## Testing diff --git a/docs/encryption.md b/docs/encryption.md index ae1af43f4..06217f013 100644 --- a/docs/encryption.md +++ b/docs/encryption.md @@ -35,6 +35,14 @@ replaces the encrypted journal file with a plain text file. You can also specify a filename, e.g., `jrnl --decrypt plain_text_copy.txt`, to leave the original encrypted file untouched and create a new plain text file next to it. +!!! note + Changing `encrypt` in your [config file](./reference-config-file.md) to + a different value will not encrypt or decrypt your + journal file. It merely says whether or not your journal + is encrypted. Hence manually changing + this option will most likely result in your journal file being + impossible to load. This is why the above commands are necessary. + ## Storing Passwords in Your Keychain Nobody can recover or reset your `jrnl` password. If you lose it, diff --git a/docs/external-editors.md b/docs/external-editors.md new file mode 100644 index 000000000..8797325aa --- /dev/null +++ b/docs/external-editors.md @@ -0,0 +1,95 @@ +# External editors + +Configure your preferred external editor by updating the `editor` option +in your [configuration file](./reference-config-file.md#editor) + +!!! note + To save and log any entry edits, save and close the file. + +If your editor is not in your operating system's `PATH` environment variable, +then you will have to enter in the full path of your editor. + +## Sublime Text + +To use [Sublime Text](https://www.sublimetext.com/), install the command line +tools for Sublime Text and configure your `jrnl.yaml` like this: + +```yaml +editor: "subl -w" +``` + +Note the `-w` flag to make sure `jrnl` waits for Sublime Text to close the +file before writing into the journal. + +## Visual Studio Code + +[Visual Studio Code](https://code.visualstudio.com) also requires a flag +that tells the process to wait until the file is closed before exiting: + +```yaml +editor: "code --wait" +``` + +On Windows, `code` is not added to the path by default, so you'll need to +enter the full path to your `code.exe` file, or add it to the `PATH` variable. + +## MacVim + +Also 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`: + +```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.yaml` like this: + +```yaml +editor: "open -b pro.writer.mac -Wn" +``` + +What does this do? `open -b ...` opens a file using the application +identified by the bundle identifier (a unique string for every app out +there). `-Wn` tells the application to wait until it's closed before +passing back control, and to use a new instance of the application. + +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 +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.yaml`) like this: + +```yaml +editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession" +``` + +The double backslashes are needed so `jrnl` can read the file path +correctly. The `-multiInst -nosession` options will cause `jrnl` to open +its own Notepad++ window. + + +## emacs + +To use `emacs` as your editor, edit the `jrnl` config file (`jrnl.yaml`) like this: + +```yaml +editor: emacsclient -a "" -c +``` + +When you're done editing the message, save and `C-x #` to close the buffer and stop the emacsclient process. + +## Other editors + +If you're using another editor and would like to share, feel free to [contribute documentation](./contributing.md#editing-documentation) on it. \ No newline at end of file diff --git a/docs/reference-command-line.md b/docs/reference-command-line.md new file mode 100644 index 000000000..d0020d243 --- /dev/null +++ b/docs/reference-command-line.md @@ -0,0 +1,128 @@ +# Command Line Reference + +## Synopsis +``` +usage: jrnl [--debug] [--help] [--version] [--list] [--encrypt] [--decrypt] + [--import] [-on DATE] [-today-in-history] [-month DATE] + [-day DATE] [-year DATE] [-from DATE] [-to DATE] [-contains TEXT] + [-and] [-starred] [-n [NUMBER]] [-not [TAG]] [--edit] [--delete] + [--format TYPE] [--tags] [--short] + [--config-override CONFIG_KEY CONFIG_VALUE] + [--config-file CONFIG_FILE_PATH] + [[...]] +``` + +## Standalone Commands + +These commands will exit after they complete. You may only run one at a time. + +### --help +Show a help message. + +### --version +Print version and license information. + +### --list +List the config file location, all configured journals, and their locations. + +### ---encrypt +Encrypt a journal. See [encryption](encryption.md) for more information. + +### --decrypt +Decrypt a journal. See [encryption](encryption.md) for more information. + + +### --import +Import entries from another journal. If any entries have the exact same content +and timestamp, they will be deduplicated. + +Optional parameters: +```sh +--file FILENAME +``` +Specify a file to import. If not provided, `jrnl` will use STDIN as the data source. + +```sh +--format TYPE +``` +Specify the format of the file that is being imported. Defaults to the same data +storage method that jrnl uses. See [formats](formats.md) for more information. + +## Writing new entries +See [Basic Usage](usage.md). + +## Searching + +To find entries from your journal, use any combination of the below filters. +Only entries that match all the filters will be displayed. + +When specifying dates, you can use the same kinds of dates you use for new +entries, such as `yesterday`, `today`, `Tuesday`, or `2021-08-01`. + +| Search Argument | Description | +| --- | --- | +| -on DATE | Show entries on this date | +| -today-in-history | Show entries of today over the years | +| -month DATE | Show entries on this month of any year | +| -day DATE | Show entries on this day of any month | +| -year DATE | Show entries of a specific year | +| -from DATE | Show entries after, or on, this date | +| -to DATE | Show entries before, or on, this date (alias: -until) | +| -contains TEXT | Show entries containing specific text (put quotes around text with spaces) | +| -and | Show only entries that match all conditions, like saying "x AND y" (default: OR) | +| -starred | Show only starred entries (marked with *) | +| -n [NUMBER] | Show a maximum of NUMBER entries (note: '-n 3' and '-3' have the same effect) | +| -not [TAG] | Exclude entries with this tag | + +## Searching Options +These help you do various tasks with the selected entries from your search. +If used on their own (with no search), they will act on your entire journal. + +### --edit +Opens the selected entries in your configured editor. It will fail if the +`editor` key is not set in your config file. + +Once you begin editing, you can add multiple entries and delete entries +by modifying the text in your editor. When your editor closes, jrnl reads +the temporary file you were editing and makes the changes to your journal. + +### --delete +Interactively deletes selected entries. You'll be asked to confirm deletion of +each entry. + +### --format TYPE +Display selected entries in an alternate format. See [formats](formats.md). + +#### Optional parameters +```sh +--file FILENAME +``` +Write output to file instead of STDOUT. In most shells, the +same effect can be achieved using `>`. + +### --tags + +Alias for '--format tags'. Returns a list of all tags and the number of times +they occur within the searched entries. If there are no tags found, `jrnl` will output a message saying so. + +### --short +Only shows the date and titles of the searched entries. + +## Configuration arguments + +### --config-override CONFIG_KEY CONFIG_VALUE + +Override configured key-value pair with CONFIG_KV_PAIR for this command invocation only. To access config keys that aren't at the top level, separate the keys with a dot, such as `colors.title` to access the `title` key within the `colors` key. Read [advanced usage](./advanced.md) for examples. + +### --config-file CONFIG_FILE_PATH + +Use the config file at CONFIG_FILE_PATH for this command invocation only. +Read [advanced usage](./advanced.md) for examples. + +## Other Arguments + +### --debug +Prints information useful for troubleshooting while `jrnl` executes. + +### --diagnostic +Prints diagnostic information useful for [reporting issues](https://github.com/jrnl-org/jrnl/issues). \ No newline at end of file diff --git a/docs/reference-config-file.md b/docs/reference-config-file.md new file mode 100644 index 000000000..97ec290cf --- /dev/null +++ b/docs/reference-config-file.md @@ -0,0 +1,117 @@ +# Configuration File Reference + +`jrnl` stores its information in a YAML configuration file. + +!!! note + Backup your journal and config file before editing. Changes to the config file + can have destructive effects on your journal! + +## Config location +You can find your configuration file location by running: +`jrnl --list` + +By default, the configuration file 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.yaml`. + +!!! note + On Windows, the configuration file is typically found at + `%USERPROFILE%\.config\jrnl\jrnl.yaml`. + + +## Config format +The configuration file is a [YAML](https://yaml.org/) file and can be edited with +a text editor. + +## Config keys + +### journals + +Describes each journal used by `jrnl`. Each indented key after this key is +the name of a journal. + +If a journal key has a value, that value will be interpreted as the path +to the journal. Otherwise, the journal needs the additional indented key +`journal` to specify its path. + +All keys below can be specified for each journal at the same level as the +`journal` key. If a key conflicts with a top-level key, the journal-specific +key will be used instead. + +### editor +If set, executes this command to launch an external editor for +writing and editing your entries. The path to a temporary file +is passed after it, and `jrnl` processes the file once +the editor is closed. + +Some editors require special options to work properly. See +[External Editors](external-editors.md) for details. + +### encrypt +If `true`, encrypts your journal using AES. Do not change this +value for journals that already have data in them. + +### template +The path to a text file to use as a template for new entries. Only works when you +have the `editor` field configured. + +### tagsymbols +Symbols to be interpreted as tags. + +!!! note + Although it seems intuitive to use the `#` + character for tags, there's a drawback: on most shells, this is + interpreted as a meta-character starting a comment. This means that if + you type + + > `jrnl Implemented endless scrolling on the #frontend of our website.` + + your bash will chop off everything after the `#` before passing it to + `jrnl`. To avoid this, wrap your input into quotation marks like + this: + + > `jrnl "Implemented endless scrolling on the #frontend of our website."` + + Or use the built-in prompt or an external editor to compose your + entries. + +### default_hour and default_minute +Entries will be created at this time if you supply a date but no specific time (for example, `last thursday`). + +### timeformat +Defines how to format the timestamps as they are stored in your journal. +See the [python docs](http://docs.python.org/library/time.html#time.strftime) for reference. + +Do not change this for an existing journal, since that might lead +to data loss. + +If you would just like to change how `jrnl` displays dates, +use display_format instead. + +!!! note + `jrnl` doesn't support the `%z` or `%Z` time zone identifiers. + +### highlight +If `true`, tags will be highlighted in cyan. + +### linewrap +Controls the width of the output. Set to `false` if you don't want to +wrap long lines. + +### colors +A dictionary that controls the colors used to display journal entries. +It has four subkeys, which are: `body`, `date`, `tags`, and `title`. + +Current valid values are: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, +`MAGENTA`, `CYAN`, `WHITE`, and `NONE`. + +`colorama.Fore` is used for colorization, and you can find the [docs here](https://github.com/tartley/colorama#colored-output). + +To disable colored output, set the value to `NONE`. + +### display_format +Specifies formatter to use by default. See [formats](formats.md). + +### version +`jrnl` automatically updates this field to the version that it is running. +There is no need to change this field manually. diff --git a/docs/recipes.md b/docs/tips-and-tricks.md similarity index 63% rename from docs/recipes.md rename to docs/tips-and-tricks.md index 713b38c3a..a158916c5 100644 --- a/docs/recipes.md +++ b/docs/tips-and-tricks.md @@ -1,10 +1,11 @@ -# FAQ +# Tips and Tricks -## Recipes +This page contains tips and tricks for using `jrnl`, often in conjunction +with other tools, including external editors. -### Co-occurrence of tags +## Co-occurrence of tags If I want to find out how often I mentioned my flatmates Alberto and Melo in the same entry, I run @@ -20,7 +21,7 @@ tag `@alberto`, and then the `--tags` option will print out how often each tag occurred in this filtered journal. Finally, we pipe this to `grep` which will only display the line containing `@melo`. -### Combining filters +## Combining filters You can do things like @@ -31,7 +32,7 @@ jrnl @fixed -starred -n 10 -to "jan 2013" --short To get a short summary of the 10 most recent, favourite entries before January 1, 2013 that are tagged with `@fixed`. -### Statistics +## Statistics How much did I write last year? @@ -50,7 +51,7 @@ This will first get the total number of words in the journal and divide it by the number of entries (this works because `jrnl --short` will 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 < entry.ext`. But what if you want the modification date of the file to be the date of the entry in `jrnl`? Try this @@ -70,7 +71,7 @@ jrnlimport () { } ``` -### Using templates +## Using templates !!! note Templates require an [external editor](./advanced.md) be configured. @@ -79,7 +80,7 @@ A template is a code snippet that makes it easier to use repeated text each time a new journal entry is started. There are two ways you can utilize templates in your entries. -#### 1. Command line arguments +### 1. Command line arguments If you had a `template.txt` file with the following contents: @@ -98,11 +99,11 @@ jrnl < template.txt # Imports template.txt as the most recent entry jrnl -1 --edit # Opens the most recent entry in the editor ``` -#### 2. Include the template file in `jrnl.yaml` +### 2. Include the template file in `jrnl.yaml` A more efficient way to work with a template file is to declare the file -in your config file by changing the `template` setting from `false` to the -template file's path in double quotes: +in your [config file](./reference-config-file.md) by changing the `template` +setting from `false` to the template file's path in double quotes: ```sh ... @@ -121,7 +122,7 @@ logged as a new entry in the journal you specified in the original argument. jrnl -n 1 ``` -### Prompts on shell reload +## Prompts on shell reload If you'd like to be prompted each time you refresh your shell, you can include this in your `.bash_profile`: @@ -142,7 +143,7 @@ questions in the example above. Each answer will be logged as a separate journal entry at the `default_hour` and `default_minute` listed in your `jrnl.yaml` [config file](../advanced/#configuration-file). -### Display random entry +## Display random entry You can use this to select one title at random and then display the whole entry. The invocation of `cut` needs to match the format of the timestamp. @@ -155,7 +156,7 @@ jrnl -on "$(jrnl --short | shuf -n 1 | cut -d' ' -f1,2)" ``` -### Launch a terminal for rapid logging +## Launch a terminal for rapid logging You can use this to launch a terminal that is the `jrnl` stdin prompt so you can start typing away immediately. ```bash @@ -180,7 +181,7 @@ Mod4+Mod1+j bindsym Mod4+Mod1+j exec --no-startup-id alacritty -t floating-jrnl -e jrnl --config-override editor "" for_window[title="floating *"] floating enable ``` -### Visualize Formatted Markdown in the CLI +## Visualize Formatted Markdown in the CLI Out of the box, `jrnl` can output journal entries in Markdown. To visualize it, you can pipe to [mdless](https://github.com/ttscoff/mdless), which is a [less](https://en.wikipedia.org/wiki/Less_(Unix))-like tool that allows you to visualize your Markdown text with formatting and syntax highlighting from the CLI. You can use this in any shell that supports piping. @@ -207,94 +208,3 @@ display_format: markdown For more information on how `jrnl` outputs your entries in Markdown, please visit the [Formats](./formats.md) section. -## External editors - -Configure your preferred external editor by updating the `editor` option -in your `jrnl.yaml` file. (See [advanced usage](./advanced.md) for details). - -!!! note - To save and log any entry edits, save and close the file. - -If your editor is not in your operating system's `PATH` environment variable, -then you will have to enter in the full path of your editor. - -### Sublime Text - -To use [Sublime Text](https://www.sublimetext.com/), install the command line -tools for Sublime Text and configure your `jrnl.yaml` like this: - -```yaml -editor: "subl -w" -``` - -Note the `-w` flag to make sure `jrnl` waits for Sublime Text to close the -file before writing into the journal. - -### Visual Studio Code - -[Visual Studio Code](https://code.visualstudio.com) also requires a flag -that tells the process to wait until the file is closed before exiting: - -```yaml -editor: "code --wait" -``` - -On Windows, `code` is not added to the path by default, so you'll need to -enter the full path to your `code.exe` file, or add it to the `PATH` variable. - -### MacVim - -Also 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`: - -```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.yaml` like this: - -```yaml -editor: "open -b pro.writer.mac -Wn" -``` - -What does this do? `open -b ...` opens a file using the application -identified by the bundle identifier (a unique string for every app out -there). `-Wn` tells the application to wait until it's closed before -passing back control, and to use a new instance of the application. - -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 -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.yaml`) like this: - -```yaml -editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession" -``` - -The double backslashes are needed so `jrnl` can read the file path -correctly. The `-multiInst -nosession` options will cause `jrnl` to open -its own Notepad++ window. - - -### emacs - -To use `emacs` as your editor, edit the `jrnl` config file (`jrnl.yaml`) like this: - -```yaml -editor: emacsclient -a "" -c -``` - -When you're done editing the message, save and `C-x #` to close the buffer and stop the emacsclient process. diff --git a/docs/usage.md b/docs/usage.md index 6d5cd765e..1a4de2a24 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -55,14 +55,15 @@ If you don't specify a date and time (e.g., `jrnl finished writing letter to bro 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)). +specified in your [configuration file](./reference-config-file.md#default_hour-and-default_minute). Behind the scenes, `jrnl` reorganizes entries in chronological order. ### Using Tags ### `jrnl` supports tags. The default tag symbol is `@` (largely because `#` is a -reserved character). You can specify your own tag symbol in the configuration -file. To use tags, preface the desired tag with the symbol: +reserved character). You can specify your own tag symbol in the +[configuration file](./reference-config-file.md#tagsymbols). To use tags, preface the +desired tag with the symbol: ```sh jrnl Had a wonderful day at the @beach with @Tom and @Anna. @@ -157,7 +158,7 @@ jrnl -n 5 @pinkie -and @WorldDomination 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. +in the [configuration file](./reference-config-file.md#tagsymbols). !!! note Entering `jrnl @pinkie @WorldDomination` will display entries in which both @@ -183,8 +184,8 @@ jrnl -starred 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, +editor configured in your [configuration file](./reference-config-file.md#editor). You +can also edit only the entries that match specific search criteria. For example, ```sh jrnl -to 1950 @texas -and @history --edit @@ -248,5 +249,5 @@ To list all of your journals: jrnl --list ``` -The journals displayed correspond to those specified in the `jrnl` configuration -file. +The journals displayed correspond to those specified in the `jrnl` +[configuration file](./reference-config-file.md#journals). diff --git a/mkdocs.yml b/mkdocs.yml index 5515d0fa0..3838c1ce3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,6 +26,11 @@ nav: - Privacy and Security: privacy-and-security.md - Formats: formats.md - Advanced Usage: advanced.md - - Recipes: recipes.md + - 'External Editors': external-editors.md + - 'Tips and Tricks': tips-and-tricks.md + - 'Reference': + - Command Line: reference-command-line.md + - Configuration File: reference-config-file.md - 'Contributing': - Contributing to jrnl: contributing.md +