mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-05-11 00:58:31 +02:00
Explicit code blocks in docs
This commit is contained in:
Manuel Ebert
parent
7003b3d13a
commit
7f5564c63c
7 changed files with 99 additions and 38 deletions
2
docs/_themes/jrnl/static/less/docs.less
vendored
2
docs/_themes/jrnl/static/less/docs.less
vendored
|
|
@ -114,7 +114,7 @@ a:hover, a:active
|
|||
background: desaturate(lighten(@terminal,10), 10);
|
||||
pre {color: white;}
|
||||
}
|
||||
.highlight-python
|
||||
.highlight-python, .highlight-sh
|
||||
{
|
||||
.terminal;
|
||||
pre
|
||||
|
|
|
|||
|
|
@ -84,12 +84,11 @@ You can configure _jrnl_ to use with multiple journals (eg. ``private`` and ``wo
|
|||
}
|
||||
}
|
||||
|
||||
The ``default`` journal gets created the first time you start _jrnl_. Now you can access the ``work`` journal by using ``jrnl work`` instead of ``jrnl``, eg. ::
|
||||
The ``default`` journal gets created the first time you start _jrnl_. Now you can access the ``work`` journal by using ``jrnl work`` instead of ``jrnl``, eg.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl work at 10am: Meeting with @Steve
|
||||
|
||||
::
|
||||
|
||||
jrnl work -n 3
|
||||
|
||||
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``).
|
||||
|
|
|
|||
|
|
@ -7,11 +7,15 @@ Encrypting and decrypting
|
|||
-------------------------
|
||||
|
||||
|
||||
If you don't choose to encrypt your file when you run `jrnl` for the first time, you can encrypt your existing journal file or change its password using ::
|
||||
If you don't choose to encrypt your file when you run `jrnl` for the first time, you can encrypt your existing journal file or change its password using
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --encrypt
|
||||
|
||||
If it is already encrypted, you will first be asked for the current password. You can then enter a new password and your plain journal will replaced by the encrypted file. Conversely, ::
|
||||
If it is already encrypted, you will first be asked for the current password. You can then enter a new password and your plain journal will replaced by the encrypted file. Conversely,
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --decrypt
|
||||
|
||||
|
|
@ -28,11 +32,15 @@ If you don't initially store the password in the keychain but decide to do so at
|
|||
A note on security
|
||||
------------------
|
||||
|
||||
While jrnl follows best practises, true security is an illusion. Specifically, jrnl will leave traces in your memory and your shell history -- it's meant to keep journals secure in transit, for example when storing it on an `untrusted <http://techcrunch.com/2014/04/09/condoleezza-rice-joins-dropboxs-board/>`_ services such as Dropbox. If you're concerned about security, disable history logging for journal in your ``.bashrc`` ::
|
||||
While jrnl follows best practises, true security is an illusion. Specifically, jrnl will leave traces in your memory and your shell history -- it's meant to keep journals secure in transit, for example when storing it on an `untrusted <http://techcrunch.com/2014/04/09/condoleezza-rice-joins-dropboxs-board/>`_ services such as Dropbox. If you're concerned about security, disable history logging for journal in your ``.bashrc``
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
HISTIGNORE="$HISTIGNORE:jrnl *"
|
||||
|
||||
If you are using zsh instead of bash, you can get the same behaviour adding this to your ``zshrc`` ::
|
||||
If you are using zsh instead of bash, you can get the same behaviour adding this to your ``zshrc``
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
setopt HIST_IGNORE_SPACE
|
||||
alias jrnl=" jrnl"
|
||||
|
|
@ -40,7 +48,9 @@ If you are using zsh instead of bash, you can get the same behaviour adding this
|
|||
Manual decryption
|
||||
-----------------
|
||||
|
||||
Should you ever want to decrypt your journal manually, you can do so with any program that supports the AES algorithm in CBC. The key used for encryption is the SHA-256-hash of your password, the IV (initialisation vector) is stored in the first 16 bytes of the encrypted file. The plain text is encoded in UTF-8 and padded according to PKCS#7 before being encrypted. Here's a Python script that you can use to decrypt your journal::
|
||||
Should you ever want to decrypt your journal manually, you can do so with any program that supports the AES algorithm in CBC. The key used for encryption is the SHA-256-hash of your password, the IV (initialisation vector) is stored in the first 16 bytes of the encrypted file. The plain text is encoded in UTF-8 and padded according to PKCS#7 before being encrypted. Here's a Python script that you can use to decrypt your journal
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python3
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,9 @@ Import and Export
|
|||
Tag export
|
||||
----------
|
||||
|
||||
With::
|
||||
With
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --tags
|
||||
|
||||
|
|
@ -15,7 +17,7 @@ you'll get a list of all tags you used in your journal, sorted by most frequent.
|
|||
List of all entries
|
||||
-------------------
|
||||
|
||||
::
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --short
|
||||
|
||||
|
|
@ -24,7 +26,9 @@ Will only display the date and title of each entry.
|
|||
JSON export
|
||||
-----------
|
||||
|
||||
Can do::
|
||||
Can do
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --export json
|
||||
|
||||
|
|
@ -33,7 +37,9 @@ Why not create a `beautiful timeline <http://timeline.verite.co/>`_ of your jour
|
|||
Markdown export
|
||||
---------------
|
||||
|
||||
Use::
|
||||
Use
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --export markdown
|
||||
|
||||
|
|
@ -42,7 +48,7 @@ Markdown is a simple markup language that is human readable and can be used to b
|
|||
Text export
|
||||
-----------
|
||||
|
||||
::
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --export text
|
||||
|
||||
|
|
@ -51,11 +57,15 @@ Pretty-prints your entire journal.
|
|||
Export to files
|
||||
---------------
|
||||
|
||||
You can specify the output file of your exported journal using the `-o` argument::
|
||||
You can specify the output file of your exported journal using the `-o` argument
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --export md -o journal.md
|
||||
|
||||
The above command will generate a file named `journal.md`. If the `-o` argument is a directory, jrnl will export each entry into an individual file::
|
||||
The above command will generate a file named `journal.md`. If the `-o` argument is a directory, jrnl will export each entry into an individual file
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl --export json -o my_entries/
|
||||
|
||||
|
|
|
|||
|
|
@ -6,15 +6,21 @@ Getting started
|
|||
Installation
|
||||
------------
|
||||
|
||||
On OS X, the easiest way to install *jrnl* is using `Homebrew <http://brew.sh/>`_ ::
|
||||
On OS X, the easiest way to install *jrnl* is using `Homebrew <http://brew.sh/>`_
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
brew install jrnl
|
||||
|
||||
On other platforms, install *jrnl* using pip ::
|
||||
On other platforms, install *jrnl* using pip
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip install jrnl
|
||||
|
||||
Or, if you want the option to encrypt your journal, ::
|
||||
Or, if you want the option to encrypt your journal,
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip install jrnl[encrypted]
|
||||
|
||||
|
|
@ -32,7 +38,9 @@ The first time you run ``jrnl`` you will be asked where your journal file should
|
|||
Quickstart
|
||||
----------
|
||||
|
||||
to make a new entry, just type::
|
||||
to make a new entry, just type
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl yesterday: Called in sick. Used the time to clean the house and spent 4h on writing my book.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,9 @@ Recipes
|
|||
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 ::
|
||||
If I want to find out how often I mentioned my flatmates Alberto and Melo in the same entry, I run
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl @alberto --tags | grep @melo
|
||||
|
||||
|
|
@ -18,7 +20,9 @@ And will get something like ``@melo: 9``, meaning there are 9 entries where both
|
|||
Combining filters
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can do things like ::
|
||||
You can do things like
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl @fixed -starred -n 10 -until "jan 2013" --short
|
||||
|
||||
|
|
@ -27,11 +31,15 @@ To get a short summary of the 10 most recent, favourited entries before January
|
|||
Statistics
|
||||
~~~~~~~~~~
|
||||
|
||||
How much did I write last year? ::
|
||||
How much did I write last year?
|
||||
|
||||
.. code-block:: 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? ::
|
||||
Will give you the number of words you wrote in 2013. How long is my average entry?
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
expr $(jrnl --export text | wc -w) / $(jrnl --short | wc -l)
|
||||
|
||||
|
|
@ -40,7 +48,9 @@ This will first get the total number of words in the journal and divide it by th
|
|||
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 ::
|
||||
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
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
echo `stat -f %Sm -t '%d %b %Y at %H:%M: ' entry.txt` `cat entry.txt` | jrnl
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,9 @@ We intentionally break a convention on command line arguments: all arguments sta
|
|||
Listing Journals
|
||||
----------------
|
||||
|
||||
You can list the journals accessible by jrnl::
|
||||
You can list the journals accessible by jrnl
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl -ls
|
||||
|
||||
|
|
@ -19,7 +21,9 @@ The journals displayed correspond to those specified in the jrnl configuration f
|
|||
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
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny.
|
||||
|
||||
|
|
@ -28,7 +32,9 @@ Composing mode is entered by either starting ``jrnl`` without any arguments -- w
|
|||
|
||||
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, :doc:`use an external editor <advanced>`).
|
||||
|
||||
You can also import an entry directly from a file::
|
||||
You can also import an entry directly from a file
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl < my_entry.txt
|
||||
|
||||
|
|
@ -48,7 +54,9 @@ Timestamps that work:
|
|||
Starring entries
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
To mark an entry as a favourite, simply "star" it::
|
||||
To mark an entry as a favourite, simply "star" it
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl last sunday *: Best day of my life.
|
||||
|
||||
|
|
@ -65,30 +73,42 @@ If you don't want to add a date (ie. your entry will be dated as now), The follo
|
|||
Viewing
|
||||
-------
|
||||
|
||||
::
|
||||
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl -n 10
|
||||
|
||||
will list you the ten latest entries (if you're lazy, ``jrnl -10`` will do the same), ::
|
||||
will list you the ten latest entries (if you're lazy, ``jrnl -10`` will do the same),
|
||||
|
||||
.. code-block:: 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 ::
|
||||
everything that happened from the start of last year to the start of last march. To only see your favourite entries, use
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl -starred
|
||||
|
||||
Using Tags
|
||||
----------
|
||||
|
||||
Keep track of people, projects or locations, by tagging them with an ``@`` in your entries ::
|
||||
Keep track of people, projects or locations, by tagging them with an ``@`` in your entries
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl Had a wonderful day on the @beach with @Tom and @Anna.
|
||||
|
||||
You can filter your journal entries just like this: ::
|
||||
You can filter your journal entries just like this:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl @pinkie @WorldDomination
|
||||
|
||||
Will print all entries in which either ``@pinkie`` or ``@WorldDomination`` occurred. ::
|
||||
Will print all entries in which either ``@pinkie`` or ``@WorldDomination`` occurred.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl -n 5 -and @pineapple @lubricant
|
||||
|
||||
|
|
@ -101,7 +121,9 @@ the last five entries containing both ``@pineapple`` **and** ``@lubricant``. You
|
|||
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 :doc:`advanced usage <advanced>`)::
|
||||
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 :doc:`advanced usage <advanced>`)
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl -until 1950 @texas -and @history --edit
|
||||
|
||||
|
|
@ -109,7 +131,9 @@ Will open your editor with all entries tagged with ``@texas`` and ``@history`` b
|
|||
|
||||
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.
|
||||
|
||||
You can also use this feature for deleting entries from your journal::
|
||||
You can also use this feature for deleting entries from your journal
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
jrnl @girlfriend -until 'june 2012' --edit
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue