Updated docs from master

_sources/advanced.txt

@@ -0,0 +1,113 @@
+.. _advanced:
+
+Advanced Usage
+==============
+
+Configuration File
+-------------------
+
+You can configure the way jrnl behaves in a configuration file. By default, this is ``~/.jrnl_config``. If you have the ``XDG_CONFIG_HOME`` variable set, the configuration file will be saved under ``$XDG_CONFIG_HOME/jrnl``.
+
+.. note::
+
+    On Windows, The configuration file is typically found at ``C:\Users\[Your Username]\.jrnl_config``.
+
+
+The configuration file is a simple JSON file with the following options and can be edited with any plain text editor.
+
+- ``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 :doc:`FAQ <recipes>` 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.
+
+.. 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
+
+      .. code-block:: note
+
+          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:
+
+      .. code-block:: note
+
+          jrnl "Implemented endless scrolling on the #frontend of our website."
+
+      Or use the built-in prompt or an external editor to compose your entries.
+
+DayOne Integration
+------------------
+
+Using your DayOne journal instead of a flat text file is dead simple -- instead of pointing to a text file, change your ``.jrnl_config`` to point to your DayOne journal. This is a folder ending with ``.dayone``, and it's located at
+
+* ``~/Library/Application Support/Day One/`` by default
+* ``~/Dropbox/Apps/Day One/`` if you're syncing with Dropbox and
+* ``~/Library/Mobile Documents/5U8NS4GX82~com~dayoneapp~dayone/Documents/`` if you're syncing with iCloud.
+
+Instead of all entries being in a single file, each entry will live in a separate `plist` file.
+
+Multiple journal files
+----------------------
+
+You can configure _jrnl_ to use with multiple journals (eg. ``private`` and ``work``) by defining more journals in your ``.jrnl_config``, for example:
+
+.. code-block:: javascript
+
+    {
+    ...
+      "journals": {
+        "default": "~/journal.txt",
+        "work":    "~/work.txt"
+      }
+    }
+
+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. ::
+
+    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``).
+
+You can also override the default options for each individual journal. If you ``.jrnl_config`` looks like this:
+
+.. code-block:: javascript
+
+    {
+      ...
+      "encrypt": false
+      "journals": {
+        "default": "~/journal.txt",
+        "work": {
+          "journal": "~/work.txt",
+          "encrypt": true
+        },
+        "food": "~/my_recipes.txt",
+    }
+
+Your ``default`` and your ``food`` journals won't be encrypted, however your ``work`` journal will! You can override all options that are present at the top level of ``.jrnl_config``, just make sure that at the very least you specify a ``"journal": ...`` key that points to the journal file of that journal.
+
+.. 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.
+
+Known Issues
+~~~~~~~~~~~~
+
+- The Windows shell prior to Windows 7 has issues with unicode encoding. If you want to use non-ascii characters, change the codepage with ``chcp 1252`` before using `jrnl` (Thanks to Yves Pouplard for solving this!)
+- _jrnl_ relies on the `PyCrypto` package to encrypt journals, which has some known problems with installing on Windows and within virtual environments.

_sources/encryption.txt

@@ -0,0 +1,39 @@
+.. _encryption:
+
+Encryption
+==========
+
+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 ::
+
+    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, ::
+
+    jrnl --decrypt
+
+will replace your encrypted journal file by a Journal in plain text. You can also specify a filename, ie. ``jrnl --decrypt plain_text_copy.txt``, to leave your original file untouched.
+
+
+Storing passwords in your keychain
+----------------------------------
+
+Whenever you encrypt your journal, you are asked whether you want to store the encryption password in your keychain. If you do this, you won't have to enter your password every time you want to write or read your journal.
+
+If you don't initially store the password in the keychain but decide to do so at a later point -- or maybe want to store it on one computer but not on another -- you can simply run ``jrnl --encrypt`` on an encrypted journal and use the same password again.
+
+
+Manual decryption
+-----------------
+
+Should you ever want to decrypt your journal manually, you can do so with any program that supports the AES algorithm. The key used for encryption is the SHA-256-hash of your password, and the IV (initialisation vector) is stored in the first 16 bytes of the encrypted file. So, to decrypt a journal file in python, run::
+
+    import hashlib, Crypto.Cipher
+    key = hashlib.sha256(my_password).digest()
+    with open("my_journal.txt") as f:
+        cipher = f.read()
+        crypto = AES.new(key, AES.MODE_CBC, iv = cipher[:16])
+        plain = crypto.decrypt(cipher[16:])

_sources/export.txt

@@ -0,0 +1,69 @@
+.. _export:
+
+Import and Export
+=================
+
+Tag export
+----------
+
+With::
+
+    jrnl --tags
+
+you'll get a list of all tags you used in your journal, sorted by most frequent. Tags occurring several times in the same entry are only counted as one.
+
+List of all entries
+-------------------
+
+::
+
+    jrnl --short
+
+Will only display the date and title of each entry.
+
+JSON export
+-----------
+
+Can do::
+
+    jrnl --export json
+
+Why not create a `beautiful timeline <http://timeline.verite.co/>`_ of your journal?
+
+Markdown export
+---------------
+
+Use::
+
+    jrnl --export markdown
+
+Markdown is a simple markup language that is human readable and can be used to be rendered to other formats (html, pdf). This README for example is formatted in markdown and github makes it look nice.
+
+Text export
+-----------
+
+::
+
+    jrnl --export text
+
+Pretty-prints your entire journal.
+
+Export to files
+---------------
+
+You can specify the output file of your exported journal using the `-o` argument::
+
+    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::
+
+    jrnl --export json -o my_entries/
+
+The contents of `my_entries/` will then look like this:
+
+.. code-block:: output
+
+    my_entries/
+    |- 2013_06_03_a-beautiful-day.json
+    |- 2013_06_07_dinner-with-gabriel.json
+    |- ...

_sources/index.txt

@@ -0,0 +1,20 @@
+.. jrnl documentation master file, created by
+   sphinx-quickstart on Wed Aug  7 13:22:51 2013.
+
+jrnl: The command-line journal
+==============================
+
+Release v\ |version|.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   overview
+   installation
+   usage
+   encryption
+   export
+   advanced
+   recipes

_sources/installation.txt

@@ -0,0 +1,41 @@
+.. _download:
+
+Getting started
+===============
+
+Installation
+------------
+
+Install *jrnl* using pip ::
+
+    pip install jrnl
+
+Or, if you want the option to encrypt your journal, ::
+
+    pip install jrnl[encrypted]
+
+to install the dependencies for encrypting journals as well.
+
+.. note::
+
+   Installing the encryption library, `pycrypto`, requires a `gcc` compiler. For this reason, jrnl will not install `pycrypto` unless explicitly told so like this. You can `install PyCyrypto manually <https://www.dlitz.net/software/pycrypto/>`_ first or install it with ``pip install pycrypto`` if you have a `gcc` compiler.
+
+The first time you run ``jrnl`` you will be asked where your journal file should be created and whether you wish to encrypt it.
+
+
+Quickstart
+----------
+
+to make a new entry, just type::
+
+    jrnl yesterday: Called in sick. Used the time to clean the house and spent 4h on writing my book.
+
+and hit return. ``yesterday:`` will be interpreted as a time stamp. Everything until the first sentence mark (``.?!:``) will be interpreted as the title, the rest as the body. In your journal file, the result will look like this:
+
+.. code-block:: output
+
+   2012-03-29 09:00 Called in sick.
+   Used the time to clean the house and spent 4h on writing my book.
+
+If you just call ``jrnl``, you will be prompted to compose your entry - but you can also configure *jrnl* to use your external editor.
+

_sources/overview.txt

@@ -0,0 +1,23 @@
+.. _overview:
+
+Overview
+===============
+
+What is jrnl?
+-------------
+
+`jrnl` is a simple journal application for your command line. Journals are stored as human readable plain text files - you can put them into a Dropbox folder for instant syncing and you can be assured that your journal will still be readable in 2050, when all your fancy iPad journal applications will long be forgotten.
+
+`jrnl` also plays nice with the fabulous `DayOne <http://dayoneapp.com>`_ and can read and write directly from and to DayOne Journals.
+
+Optionally, your journal can be encrypted using the `256-bit AES <http://en.wikipedia.org/wiki/Advanced_Encryption_Standard>`_.
+
+Why keep a journal?
+-------------------
+
+Journals aren't only for 13-year old girls and people who have too much time on their summer vacation. A journal helps you to keep track of the things you get done and how you did them. Your imagination may be limitless, but your memory isn't.
+
+For personal use, make it a good habit to write at least 20 words a day. Just to reflect what made this day special, why you haven't wasted it.
+
+For professional use, consider a text-based journal to be the perfect complement to your GTD todo list - a documentation of what and how you've done it. Or use it as a quick way to keep a change log. Or use it to keep a lab book.
+

_sources/recipes.txt

@@ -0,0 +1,74 @@
+.. _recipes:
+
+FAQ
+===
+
+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 ::
+
+    jrnl @alberto --tags | grep @melo
+
+And will get something like ``@melo: 9``, meaning there are 9 entries where both ``@alberto`` and ``@melo`` are tagged. How does this work? First, ``jrnl @alberto`` will filter the journal to only entries containing the 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
+~~~~~~~~~~~~~~~~~
+
+You can do things like ::
+
+    jrnl @fixed -starred -n 10 -until "jan 2013" --short
+
+To get a short summary of the 10 most recent, favourited entries before January 1, 2013 that are tagged with ``@fixed``.
+
+External editors
+----------------
+
+To use external editors for writing and editing journal entries,  set them up in your ``.jrnl_config`` (see :doc:`advanced usage <advanced>` for details). Generally, after writing an entry, you will have to save and close the file to save the changes to jrnl.
+
+Sublime Text
+~~~~~~~~~~~~
+
+To use Sublime Text, install the command line tools for Sublime Text and configure your ``.jrnl_config`` like this:
+
+.. code-block:: javascript
+
+    "editor": "subl -w"
+
+Note the ``-w`` flag to make sure jrnl waits for Sublime Text to close the file before writing into the journal.
+
+
+MacVim
+~~~~~~
+
+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``:
+
+.. code-block:: javascript
+
+    "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_config`` like this:
+
+.. code-block:: javascript
+
+    "editor": "open -b jp.informationarchitects.WriterForMacOSX -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.
+
+
+Notepad++ on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To set `Notepad++ <http://notepad-plus-plus.org/>`_ as your editor, edit the jrnl config file (``.jrnl_config``) like this:
+
+.. code-block:: javascript
+
+      "editor": "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst",
+
+The double backslashes are needed so jrnl can read the file path correctly. The ``-multiInst`` option will cause jrnl to open its own Notepad++ window.

_sources/usage.txt

@@ -0,0 +1,121 @@
+.. _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.
+
+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).
+
+
+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::
+
+    jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny.
+
+You can also import an entry directly from a file::
+
+    jrnl < my_entry.txt
+
+Smart timestamps
+~~~~~~~~~~~~~~~~
+
+Timestamps that work:
+
+* at 6am
+* yesterday
+* last monday
+* sunday at noon
+* 2 march 2012
+* 7 apr
+* 5/20/1998 at 23:42
+
+Starring entries
+~~~~~~~~~~~~~~~~
+
+To mark an entry as a favourite, simply "star" it::
+
+    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:
+
+* ``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).
+
+Viewing
+-------
+
+::
+
+    jrnl -n 10
+
+will list you the ten latest entries, ::
+
+    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 ::
+
+    jrnl -starred
+
+Using Tags
+----------
+
+Keep track of people, projects or locations, by tagging them with an ``@`` in your entries ::
+
+    jrnl Had a wonderful day on the @beach with @Tom and @Anna.
+
+You can filter your journal entries just like this: ::
+
+    jrnl @pinkie @WorldDomination
+
+Will print all entries in which either ``@pinkie`` or ``@WorldDomination`` occurred. ::
+
+    jrnl -n 5 -and @pineapple @lubricant
+
+the last five entries containing both ``@pineapple`` **and** ``@lubricant``. 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.
+
+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>`)::
+
+    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.
+
+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::
+
+    jrnl @girlfriend -until 'june 2012' --edit
+
+Just select all text, press delete, and everything is gone...
+
+Editing DayOne Journals
+~~~~~~~~~~~~~~~~~~~~~~~
+
+DayOne journals can be edited exactly the same way, however the output looks a little bit different because of the way DayOne stores its entries:
+
+.. code-block:: output
+
+    # af8dbd0d43fb55458f11aad586ea2abf
+    2013-05-02 15:30 I told everyone I built my @robot wife for sex.
+    But late at night when we're alone we mostly play Battleship.
+
+    # 2391048fe24111e1983ed49a20be6f9e
+    2013-08-10 03:22 I had all kinds of plans in case of a @zombie attack.
+    I just figured I'd be on the other side.
+
+The long strings starting with hash symbol are the so-called UUIDs, unique identifiers for each entry. Don't touch them. If you do, then the old entry would get deleted and a new one written, which means that you could DayOne loose data that jrnl can't handle (such as as the entry's geolocation).
+