Create and manage notes.
Michał Góral 63cc4f014c For `notes ls` display a list of all files. 1 year ago
tests First test 1 year ago
LICENSE Added license 1 year ago
_notes Automatically manage git repository. 1 year ago
notes Missing executable 1 year ago
notes.py For `notes ls` display a list of all files. 1 year ago
readme.adoc Automatically manage git repository. 1 year ago
tox.ini Updated pytest version 1 year ago

readme.adoc

= Notes User Manual
:author: Michał Góral
:revnumber: 1.0
:toc: left
:toclevels: 3
:doctype: book
:sectnums:
:sectnumlevels: 2
:icons: font
:docinfo1:
:experimental:

notes - create, edit, read and manage your personal notes as simple (or complex)
text files.

== Architecture

_notes_ manages text files grouped in projects, which are stored somewhere in
your filesystem. By default all notes' files are stored in `~/notes`.
directory. You can change the root directory of notes by setting `$NOTES_PATH`
environment variable.

Each project can have arbitrarily complex file/directory structure inside.
Default project is simply named *default*.

For example

.Projects structure example
----
~/notes/
archetypes/
default.md
wiki.adoc

projects/
default/
index.md
foo.md
bar.md
project-without-archetype/
foo.txt
bar.adoc
wiki/
images/
cats.png
dogs.jpg
foo.adoc
bar.adoc
some important note.adoc
----

== Creating notes

To create a new note, simply edit it:

$ notes edit note

This will create a new note in a default project and open it in a default
editor. If you want to create a note in a different project, type it before a
note name:

$ notes edit foo/note

NOTE: Notes are edited in a default editor configured via `$EDITOR` environment
variable. If it isn't set, _vi_ is used by default.

=== Archetypes

Notes are created from so called archetypes. Archetypes are per-project files
placed in _archetypes_ directory (a sibling to _projects_ one). Each note
inherits archetype's content and file extension. So for example, if archetype is
a markdown file (_foo.md_), then creating a new note via `$ notes edit foo/note`
will create a new file named *note.md*. this note can be accessed later either
by editing _note_ or _note.md_.

Archetype can have several markers, which are automatically replaced by some
content.

.Archetype's markers
[.center, cols="^1m,^3", options="header"]
|===
| Marker | Description

| {title}
| replaced by a note title (file name)

| {user}
| replaced by current user name
|===

.Example archetype
----
# archetypes/foo.md

+++++
author: {user}
+++++
# {title}

Excerpt
----

== Displaying notes

`notes show <note>` displays notes. If project is not specified, a note from a
default project is displayed.

NOTE: Notes are displayed in a configured pager (`$PAGER` environment variable).
If `$PAGER` isn'te set, _less_ is used.
variable. If it isn't set, vi is used by default.

Notes can be compiled by setting *-c,--compile* option and a compilation command
can be set with *-C,--compile-cmd* option. When compiled, notes are opened
either by a web browser or an external program supplied with *-e,--external*
option.

Compilation command accepts the following markers, which are replaced with
correct values for a current note:

.Compilation markers
[.center, cols="^1m,^3", options="header"]
|===
| Marker | Description

| {note}
| note's absolute path

| {html}
| absolute path to the result of compilation (html file)
|===

For example:

----
$ notes show foo/bar.adoc

$ notes show -c -C 'asciidoctor {note} -o -' foo/bar.adoc | lynx -stdin

$ notes show -e x-www-browser -c -C 'asciidoctor {note} -o {html}' foo/bar.adoc
----

If you don't want to open a note after compilation (for example you already have
it opened and will simply refresh the view after few edits), you can pass
*--only-compile* switch to `notes show` command.

== Browsing notes

There are two simple commands which allow you to browse your projects and notes:
`notes projects`, which displays all projects, and `notes ls <project name>`,
which displays notes in a given project. `notes ls` additionally accepts *-a*
switch, which will display absolute paths to notes in a given project:

.notes ls examples
----
$ notes projects
default
foo

$ notes ls foo
note1.adoc
note2.adoc
subdir/bar.adoc

$ notes ls -a foo
/home/user/notes/projects/foo/note1.adoc
/home/user/notes/projects/foo/note2.adoc
/home/user/notes/projects/foo/subdir/bar.adoc

$ notes ls -a
/home/user/notes/projects/default/index.md
/home/user/notes/projects/default/page-1.md
----

== Removing notes

To remove a note, use `$notes rm <note>`.

== Integration with Git

If project is inside a Git repository, adding, editing and removing will be
automatically tracked by Git. You can later call `$ notes sync` to synchronize
(git pull and git push) it with a remote Git server.

You can also run any Git command inside a project's directory by using `notes
git <project> <command>`:

----
$ notes git foo status
----

notes will assist you when initializing a new Git repository. If you initialize
a new Git repository via `notes git <project> init`, notes will automatically
add and commit all notes in a selected project. This doesn't take effect when
reinitializing existing Git repositories.

[appendix]
== License

Copyright (C) 2017 {author}.

Notes is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

Notes is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
Notes. If not, see http://www.gnu.org/licenses/.