aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am5
-rw-r--r--doc/calcurse.1.txt3
-rw-r--r--doc/manual.txt13
-rw-r--r--doc/submitting-patches.txt192
4 files changed, 210 insertions, 3 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index caa90d2..5888b18 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -14,17 +14,20 @@ A2X_ARGS = \
endif
dist_doc_DATA = \
- manual.html
+ manual.html \
+ submitting-patches.html
dist_man_MANS = \
calcurse.1
EXTRA_DIST = \
manual.txt \
+ submitting-patches.txt \
calcurse.1.txt
CLEANFILES = \
manual.html \
+ submitting-patches.html \
calcurse.1
docdir = $(datadir)/doc/$(PACKAGE)
diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt
index 884aa34..f611079 100644
--- a/doc/calcurse.1.txt
+++ b/doc/calcurse.1.txt
@@ -103,6 +103,9 @@ appointments can be specified using the *-c* flag.
Specify the data directory to use. This option is incompatible with -c.
If not specified, the default directory is *~/.calcurse/*.
+*-g*, *--gc*::
+ Run the garbage collector for note files and exit.
+
*-h*, *--help*::
Print a short help text describing the supported command-line options,
and exit.
diff --git a/doc/manual.txt b/doc/manual.txt
index c0a992d..4964a21 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -113,8 +113,7 @@ library already installed on your computer, but if not, you can find it at the
following url: http://ftp.gnu.org/pub/gnu/ncurses/
NOTE: It is also possible to link `calcurse` against the `ncursesw` library
- (ncurses with support for unicode). However, UTF-8 is not yet supported
- by `calcurse`.
+ (ncurses with support for unicode).
[[install_requirements_gettext]]
gettext library
@@ -210,6 +209,9 @@ can be specified using the `-c` flag.
Specify the data directory to use. This option is incompatible with -c.
If not specified, the default directory is `~/.calcurse/`.
+`-g, --gc`::
+ Run the garbage collector for note files and exit.
+
`-h, --help`::
Print a short help text describing the supported command-line options,
and exit.
@@ -624,6 +626,9 @@ These options control `calcurse` general behavior, as described below:
will be automatically saved if `auto_save` is set to *no*. This means the
user must press `S` (for saving) in order to retrieve its modifications.
+`auto_gc` (default: *no*)::
+ Automatically run the garbage collector for note files when quitting.
+
`periodic_save` (default: *0*)::
If different from `0`, user's data will be automatically saved every
*periodic_save* minutes. When an automatic save is performed, two asterisks
@@ -805,6 +810,10 @@ $ calcurse --next | mail -s "[calcurse] upcoming appointment!" user@host.com
----
====
+`notify-all` (default: *no*)::
+ Invert the sense of flagging an appointment as `important`. If this is
+ enabled, all appointments will be notified - except for flagged ones.
+
`notify-daemon_enable` (default: *no*)::
If set to yes, daemon mode will be enabled, meaning `calcurse` will run into
background when the user's interface is exited. This will allow the
diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt
new file mode 100644
index 0000000..6fbb5cd
--- /dev/null
+++ b/doc/submitting-patches.txt
@@ -0,0 +1,192 @@
+////
+/*
+ * Copyright (c) 2004-2011 calcurse Development Team <misc@calcurse.org>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * - Redistributions of source code must retain the above
+ * copyright notice, this list of conditions and the
+ * following disclaimer.
+ *
+ * - Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the
+ * following disclaimer in the documentation and/or other
+ * materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+////
+
+CALCURSE - Submitting Patches
+=============================
+
+This is a short summary of guidelines you should try to follow when submitting
+patches to calcurse.
+
+Fetching the most recent source
+-------------------------------
+
+The whole source code currently is under version control using Git as VCS. You
+can retrieve a local copy of the development tree using:
+
+----
+$ git clone git://git.calcurse.org/calcurse.git
+----
+
+This will create a new directory `calcurse` that contains the cloned
+repository.
+
+If you want to follow the maintenance branch (`maint`) as well (e.g. to create
+a bug fix), setting up a tracking branch is recommended:
+
+----
+$ git branch -t maint origin/maint
+----
+
+Creating a working branch
+-------------------------
+
+Whenever you want to work on a new feature, do it in a separate branch. Having
+diverging commits in the `master` branch might cause conflicts when pulling in
+new changes. Thus, creating a new development branch *before* doing any changes
+is good practice. And even before doing that, you should update the master
+branch of your working copy:
+
+----
+$ git checkout master
+$ git pull origin master
+$ git checkout -b wip
+----
+
+You can replace `wip` by any name you like.
+
+Maintenance patches such as bug fixes and stability improvements should be
+based on the `maint` branch instead:
+
+----
+$ git checkout maint
+$ git pull origin maint
+$ git checkout -b wip-maint
+----
+
+Committing the changes
+----------------------
+
+Edit files in the source tree and test your changes. When everything seems to
+be fine, you're ready to commit to your local working tree:
+
+----
+$ git commit -as
+----
+
+If you added or removed files, you probably need to run `git add` or `git rm`
+before committing so that Git is aware of them.
+
+If you work on more than a small bug fix, you should split your work into
+several commits. Try to keep your commits small and focused. Smaller patches
+are way easier to review and have a better chance of being included in mainline
+development.
+
+Also try to make your commit messages brief and descriptive. The first line of
+the commit message should be a short description (not more than 50 characters)
+and should use imperative, present tense. If there are details that cannot be
+expressed in these size constraints, put them in separate text paragraphs
+separated by blank lines and wrapped to 72 columns. If you use Vim,
+`gitcommit.vim` will do most of the job for you.
+
+Here's a sample commit message:
+
+----
+Invoke vars_init() before importing data with "-i"
+
+We forgot to call vars_init() when importing an item using the "-i"
+command line argument, which led to the pager configuration variable
+being unset and hence the pager invocation (triggered to show the log in
+case there are any errors during import) failing.
+
+Fix this by calling vars_init() before io_import_data().
+
+Reported-by: Andraž 'ruskie' Levstik <ruskie@codemages.net>
+Signed-off-by: Lukas Fleischer <calcurse@cryptocrack.de>
+----
+
+The `-s` in the `git commit` invocation makes Git add a "Signed-off-by" line to
+credit yourself and to confirm that your contribution was created in whole or
+in part by you and you have the right to submit it under the BSD license.
+Please do not remove that line when editing the commit message.
+
+Creating a patch series
+-----------------------
+
+As soon as you finished all your work, test everything again and create a patch
+series:
+
+----
+$ git format-patch master
+----
+
+Replace `master` by `maint` if your development branch is based on the
+maintenance branch:
+
+----
+$ git format-patch maint
+----
+
+Submitting patches
+------------------
+
+Send your patch series to one of the mailing lists:
+
+----
+$ git send-email *.patch
+----
+
+The `bugs` mailing list should be used for bug fixes, `misc` should be used for
+everything else.
+
+You can also add a cover letter and/or add annotations to patches:
+
+----
+$ git send-email --cover-letter --annotate *.patch
+----
+
+Additional information on the particular patches, which shouldn't appear in the
+commit message itself, can be added immediately after the `---`.
+
+Importing patches
+-----------------
+
+Git also provides a tool for importing a patch series submitted via `git
+send-email`. Just save all mails that contain patches into mbox files and use
+`git am` to apply them to your working branch:
+
+----
+$ git am <mbox>...
+----
+
+If you use mutt, you can also add following macro to apply the patch contained
+in the current mail to your local Git repository by pressing `A`:
+
+----
+set mbox_type=mbox
+set my_git_repo_path=$HOME/src/calcurse
+
+macro index,pager A "<pipe-message>(cd $my_git_repo_path && git am)<enter>"
+----
+
+To setup different Git repositories per mailing list (in case you follow several
+different development lists), simply bind the macro to a `folder-hook` or to a
+`message-hook` and use different repository paths per hook.