fyb/calcurse-edge
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Convert man page to AsciiDoc.

Browse Source 
Signed-off-by: Lukas Fleischer <calcurse@cryptocrack.de>
This commit is contained in:
Lukas Fleischer 2011-03-03 18:46:15 +01:00
parent 91c9cac898
commit aaa000cd5a
5 changed files with 302 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Makefile.am
View File

@ -4,9 +4,6 @@ ACLOCAL_AMFLAGS = -I m4
SUBDIRS = doc po src
man_MANS= src/calcurse.1
EXTRA_DIST = \
$(man_MANS) \
INSTALL \
ABOUT-NLS
INSTALL \
ABOUT-NLS

13
configure.ac
View File

@ -81,17 +81,30 @@ if test x"$use_asciidoc" = x"auto"; then
else
have_asciidoc=yes
fi
AC_PATH_PROG([A2X], [a2x])
if test -z "$A2X"; then
have_a2x=no
AC_MSG_WARN([a2x not found - man pages will be skipped!])
else
have_a2x=yes
fi
elif test x"$use_asciidoc" = x"yes"; then
AC_PATH_PROG([ASCIIDOC], [asciidoc])
if test -z "$ASCIIDOC"; then
AC_MSG_ERROR([AsciiDoc not found and "--with-asciidoc" specified!])
fi
AC_PATH_PROG([A2X], [a2x])
if test -z "$A2X"; then
AC_MSG_ERROR([a2x not found and "--with-asciidoc" specified!])
fi
have_asciidoc=yes
elif test x"$use_asciidoc" = x"no"; then
AC_MSG_WARN(["--without-asciidoc" specified - documentation will be skipped!])
have_asciidoc=no
have_a2x=no
fi
AM_CONDITIONAL(HAVE_ASCIIDOC, test $have_asciidoc = yes)
AM_CONDITIONAL(HAVE_A2X, test $have_a2x = yes)
#-------------------------------------------------------------------------------
# Compilation options
#-------------------------------------------------------------------------------

12
doc/Makefile.am
View File

@ -5,12 +5,24 @@ ASCIIDOC_ARGS = \
-a toc \
-a icons
A2X_ARGS = \
-d manpage \
-f manpage
doc_DATA = \
manual.html
man_MANS = \
calcurse.1
docdir = $(datadir)/doc/$(PACKAGE)
.txt.html:
if HAVE_ASCIIDOC
$(AM_V_GEN) $(ASCIIDOC) $(ASCIIDOC_ARGS) $<
endif
calcurse.1: calcurse.1.txt
if HAVE_A2X
$(AM_V_GEN) $(A2X) $(A2X_ARGS) $<
endif

275
doc/calcurse.1.txt Normal file
View File

@ -0,0 +1,275 @@
////
/*
* Copyright (c) 2004-2010 Frederic Culot <frederic@culot.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(1)
===========
Name
----
calcurse - text-based organizer
Synopsis
--------
[verse]
*calcurse* [*-h*|*-v*] [*-N*] [*-an*] [*-t*[num]] [*-c*<file> | *-D*<dir>]
[*-i*<file>] [*-x*[format]] [*-d* <date>|<num>]
[*-s*[date]] [*-r*[range]] [*-S* <regex>] [*--status*]
Description
-----------
Calcurse is a text-based calendar and scheduling application. It helps keeping
track of events, appointments and everyday tasks. A configurable notification
system reminds user of upcoming deadlines, and the curses based interface can
be customized to suit user needs. All of the commands are documented within an
online help system.
Options
-------
The following options are supported:
*-a*, *--appointment*::
Print the appointments and events for the current day and exit. 'Note:' The calendar
from which to read the appointments can be specified using the *-c* flag.
*-c* <file>, *--calendar* <file>::
Specify the calendar file to use. The default calendar is
*~/.calcurse/apts* (see section 'FILES' below). This option is incompatible
with -*D*.
*-d* <date|num>, *--day* <date|num>::
Print the appointments for the given date or for the given number of
upcoming days, depending on the argument format. Two possible formats are
supported:
+
--
* a date (possible formats described below).
* a number *n*.
--
+
In the first case, the appointment list for the specified date will be
returned, while in the second case the appointment list for the *n* upcoming
days will be returned.
+
As an example, typing *calcurse -d 3* will display your appointments for
today, tomorrow, and the day after tomorrow.
+
The date format used is the one specified in the ``General options''
menu. Four formats are available:
+
--
1. mm/dd/yyyy
2. dd/mm/yyyy
3. yyyy/mm/dd
4. yyyy-mm-dd
--
+
'Note:' as for the *-a* flag, the calendar from which to read the
appointments can be specified using the *-c* flag.
*-D* <dir>, *--directory* <dir>::
Specify the data directory to use. This option is incompatible with -c.
If not specified, the default directory is *~/.calcurse/*.
*-h*, *--help*::
Print a short help text describing the supported command-line options,
and exit.
*-i* <file>, *--import* <file>::
Import the icalendar data contained in 'file'.
*-n*, *--next*::
Print the next appointment within upcoming 24 hours and exit. The indicated
time is the number of hours and minutes left before this appointment.
+
'Note:' the calendar from which to read the appointments can be specified using
the *-c* flag.
*-N*, *--note*::
When used with the *-a* or *-t* flag, also print note content if one is
associated with the displayed item.
*-r*[num], *--range*[=num]::
Print events and appointments for the 'num' number of days and exit. If no
'num' is given, a range of 1 day is considered.
*-s*[date], *--startday*[=date]::
Print events and appointments from 'date' and exit. If no 'date' is given,
the current day is considered.
*-S*<regex>, *--search*=<regex>::
When used with the *-a*, *-d*, *-r*, *-s*, or *-t* flag, print only the items
having a description that matches the given regular expression.
*--status*::
Display the status of running instances of calcurse. If calcurse is
running, this will tell if the interactive mode was launched or if
calcurse is running in background. The process pid will also be indicated.
*-t*[num], *--todo*[=num]::
Print the *todo* list and exit. If the optional number 'num' is given, then
only todos having a priority equal to 'num' will be returned. The priority
number must be between 1 (highest) and 9 (lowest). It is also possible to
specify *0* for the priority, in which case only completed tasks will be
shown.
*-v*, *--version*::
Display *calcurse* version and exit.
*-x*[format], *--export*[=format]::
Export user data to specified format. Events, appointments and todos are
converted and echoed to stdout. Two possible formats are available: 'ical'
and 'pcal'. If the optional argument 'format' is not given, ical format is
selected by default.
+
'Note:' redirect standard output to export data to a file, by issuing a command
such as:
+
----
$ calcurse --export > my_data.dat
----
Notes
-----
Calcurse interface contains three different panels (calendar, appointment list,
and todo list) on which you can perform different actions. All the possible
actions, together with their associated keystrokes, are listed on the status
bar. This status bar takes place at the bottom of the screen.
At any time, the built-in help system can be invoked by pressing the '?' key.
Once viewing the help screens, informations on a specific command can be
accessed by pressing the keystroke corresponding to that command.
Configuration
-------------
The calcurse options can be changed from the configuration menu (shown when 'C'
is hit). Five possible categories are to be chosen from : the color scheme, the
layout (the location of the three panels on the screen), notification options,
key bindings configuration menu, and more general options (such as automatic
save before quitting). All of these options are detailed in the configuration
menu.
Files
-----
The following structure is created in your $HOME directory (or in the directory
you specified with the *-D* option), the first time calcurse is run:
----
$HOME/.calcurse/
|___notes/
|___conf
|___keys
|___apts
|___todo
----
The 'notes' subdirectory contains descriptions of the notes which are attached
to appointments, events or todos. One text file is created per note, whose name
is built using mkstemp(3) and should be unique, but with no relation with the
corresponding item's description.
The 'conf' file contains the user configuration. The 'keys' file contains the
user-defined key bindings. The 'apts' file contains all of the user's
appointments and events, and the 'todo' file contains the todo list.
'Note:' if the logging of calcurse daemon activity was set in the notification
configuration menu, the extra file 'daemon.log' will appear in calcurse data
directory. This file contains logs about calcurse activity when running in
background.
Environment
-----------
This section describes the environment variables that affect how calcurse
operates.
*VISUAL*::
Specifies the external editor to use for writing notes.
*EDITOR*::
If the 'VISUAL' environment variable is not set, then 'EDITOR' will be used
as the default external editor. If none of those variables are set, then
'/usr/bin/vi' is used instead.
*PAGER*::
Specifies the default viewer to be used for reading notes. If this variable
is not set, then '/usr/bin/less' is used.
Bugs
----
Incorrect highlighting of items appear when using calcurse black and white
theme together with a *$TERM* variable set to 'xterm-color'. To fix this bug,
and as advised by Thomas E. Dickey (xterm maintainer), 'xterm-xfree86' should
be used instead of 'xterm-color' to set the *$TERM* variable:
"The xterm-color value for $TERM is a bad choice for
XFree86 xterm because it is commonly used for a
terminfo entry which happens to not support bce.
Use the xterm-xfree86 entry which is distributed
with XFree86 xterm (or the similar one distributed
with ncurses)."
If you find other bugs, please send a report to calcurse@culot.org or to the
author, below.
See also
--------
vi(1), less(1), ncurses(3), mkstemp(3)
The ical specification (rfc2445) can be found at:
http://tools.ietf.org/html/rfc2445
The pcal project page: http://pcal.sourceforge.net/
Calcurse home page: http://culot.org/calcurse/
Calcurse complete manual, translated in many languages and maintained in
html format, can be found in the doc/ directory of the source package,
or at: http://culot.org/calcurse/manual.html
Authors
-------
* *Frederic Culot* <frederic@culot.org>
* *Lukas Fleischer* <calcurse@cryptocrack.de>
Copyright
---------
Copyright (c) 2004-2010 by Frederic Culot.
This software is released under the BSD License.

269
src/calcurse.1
View File

@ -1,269 +0,0 @@
.\" Copyright (c) 2004-2010 Frederic Culot <frederic@culot.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.
.\"
.\" Send your feedback or comments to : calcurse@culot.org
.\" Calcurse home page : http://culot.org/calcurse
.\"
.fam C
.TH CALCURSE 1 "May 26, 2010" "Version 2.8" "Calcurse Manual"
.SH NAME
Calcurse \- text-based organizer
.SH SYNOPSIS
.B "calcurse "
[\fB-h\fP|\fB-v\fP] [\fB-N\fP] [\fB-an\fP] [\fB-t\fP[\fInum\fP]]
[\fB-c\fP<\fIfile\fP> | \fB-D\fP<\fIdir\fP>]
.br
[\fB-i\fP<\fIfile\fP>] [\fB-x\fP[\fIformat\fP]]
[\fB-d\fP <\fIdate\fP>|<\fInum\fP>]
.br
[\fB-s\fP[\fIdate\fP]] [\fB-r\fP[\fIrange\fP]]
[\fB-S\fP <\fIregex\fP>] [\fB--status\fP]
.br
.SH DESCRIPTION
Calcurse is a text-based calendar and scheduling application. It helps
keeping track of events, appointments and everyday tasks.
A configurable notification system reminds user of upcoming deadlines,
and the curses based interface can be customized to suit user needs.
All of the commands are documented within an online help system.
.SH OPTIONS
The following options are supported:
.TP
\fB-a\fP, \fB--appointment\fP
Print the appointments and events for the current day and exit.
.br
\fINote:\fP the calendar from which to read the appointments can be specified using
the '\-c' flag.
.TP
\fB-c\fP <file>, \fB--calendar\fP <file>
Specify the calendar file to use. The default calendar is
.B "'~/.calcurse/apts'"
(see section \fIFILES\fP below). This option is incompatible with \fB-D\fP.
.TP
\fB-d\fP <date|num>, \fB--day\fP <date|num>
Print the appointments and events for the given date or for
the given number of upcoming days, depending on the argument format.
Two possible formats are supported:
.RS 9
.TP 2
\(bu a date (see below for possible formats).
.TP 2
\(bu a number 'n'.
.RE
.RS 7
.LP
In the first case, the appointments and events list for the specified
date will be returned, while in the second case the appointments and events
list for the 'n' upcoming days will be returned.
.br
As an example, typing 'calcurse -d 3' will display your appointments
and events for today, tomorrow, and the day after tomorrow.
.br
The date format used is the one specified in the 'General options' menu.
Four formats are available:
.RS 9
.TP 2
\fB1.\fP mm/dd/yyyy
.TP 2
\fB2.\fP dd/mm/yyyy
.TP 2
\fB3.\fP yyyy/mm/dd
.TP 2
\fB4.\fP yyyy-mm-dd
.RE
.RS 7
.LP
.br
\fINote:\fP as for the '-a' flag, the calendar from which to read the
appointments can be specified using the '\-c' flag.
.RE
.TP
\fB-D\fP <dir>, \fB--directory\fP <dir>
Specify the data directory to use. This option is incompatible with \fB-c\fP.
If not specified, the default directory is
.B "'~/.calcurse/'"
.TP
\fB-h\fP, \fB--help\fP
Print a short help text describing the supported command-line options,
and then exit.
.TP
\fB-i\fP <file>, \fB--import\fP <file>
Import the icalendar data contained in \fIfile\fP.
.TP
\fB-n\fP, \fB--next\fP
Print the next appointment within upcoming 24 hours and exit.
The indicated time is the number of hours and minutes left before this
appointment.
.br
\fINote:\fP the calendar from which to read the appointments can be specified using
the '\-c' flag.
.TP
\fB-N\fP, \fB--note\fP
When used with the '-a' or '-t' flag, also print note content
if one is associated with the displayed item.
.TP
\fB-r\fP[num], \fB--range\fP[=num]
Print events and appointments for the \fInum\fP number of days
and exit. If no \fInum\fP is given, a range of 1 day is considered.
.TP
\fB-s\fP[date], \fB--startday\fP[=date]
Print events and appointments from \fIdate\fP and exit.
If no \fIdate\fP is given, the current day is considered.
.TP
\fB-S\fP<regex>, \fB--search\fP=<regex>
When used with the '-a', '-d', '-r', '-s', or '-t' flag,
print only the items having a description that matches the given
regular expression.
.TP
\fB--status\fP
Display the status of running instances of calcurse. If calcurse is running,
this will tell if the interactive mode was launched or if calcurse is running
in background. The process pid will also be indicated.
.TP
\fB-t\fP[num], \fB--todo\fP[=num]
Print the 'todo' list and exit. If the optional number \fInum\fP is given,
then only todos having a priority equal to \fInum\fP will be returned.
The priority number must be between 1 (highest) and 9 (lowest). It is also
possible to specify '0' for the priority, in which case only completed
tasks will be shown.
.TP
\fB-v\fP, \fB--version\fP
Display calcurse version and exit.
.TP
\fB-x\fP[format], \fB--export\fP[=format]
Export user data to the specified format. Events, appointments and
todos are converted and echoed to stdout. Two possible formats are
available: \fIical\fP and \fIpcal\fP.
If the optional argument format is not given, ical format is
selected by default.
.br
\fINote:\fP redirect standard output to export data to a file,
by issuing a command such as:
.br
.B $ calcurse --export > calcurse.dat
.SH NOTES
Calcurse interface contains three different panels (calendar,
appointment list, and todo list) on which you can perform different
actions. All the possible actions, together with their associated
keystrokes, are listed on the status bar. This status bar
takes place at the bottom of the screen.
.PP
At any time, the built-in help system can be invoked by pressing the '?'
key. Once viewing the help screens, informations on a specific command
can be accessed by pressing the keystroke corresponding to that command.
.SH CONFIGURATION
The calcurse options can be changed from the configuration menu (shown
when 'C' is hit). Five possible categories are to be chosen from : the
color scheme, the layout (the location of the three panels on the
screen), notification options, key bindings configuration menu,
and more general options (such as automatic save before quitting).
All of these options are detailed in the configuration menu.
.SH FILES
The following structure is created in your $HOME directory
(or in the directory you specified with the \fB-D\fP option),
the first time calcurse is run:
.PP
.HP 10
$HOME/.calcurse/
.br
|___notes/
.br
|___conf
.br
|___keys
.br
|___apts
.br
|___todo
.PP
The \fInotes\fP subdirectory contains descriptions of the notes
which are attached to appointments, events or todos. One text file is
created per note, whose name is built using mkstemp(3) and should be
unique, but with no relation with the corresponding item's description.
.br
The \fIconf\fP file contains the user configuration. The \fIkeys\fP
file contains the user-defined key bindings. The \fIapts\fP
file contains all of the user's appointments and events, and the
\fItodo\fP file contains the todo list.
.PP
\fINote:\fP if the logging of calcurse daemon activity was set
in the notification configuration menu, the extra file \fIdaemon.log\fP will
appear in calcurse data directory. This file contains logs about calcurse
activity when running in background.
.SH ENVIRONMENT
This section describes the environment variables that affect how
calcurse operates.
.TP 4
\fBVISUAL\fP
Specifies the external editor to use for writing notes.
.TP 4
\fBEDITOR\fP
If the \fIVISUAL\fP environment variable is not set, then \fIEDITOR\fP
will be used as the default external editor. If none of those variables
are set, then \fI/usr/bin/vi\fP is used instead.
.TP 4
\fBPAGER\fP
Specifies the default viewer to be used for reading notes. If this variable
is not set, then \fI/usr/bin/less\fP is used.
.SH BUGS
Incorrect highlighting of items appear when using calcurse black and
white theme together with a \fB$TERM\fP variable set to
\fIxterm-color\fP.
To fix this bug, and as advised by Thomas E. Dickey (xterm maintainer),
\fIxterm-xfree86\fP should be used instead of \fIxterm-color\fP to set
the \fB$TERM\fP variable:
"The xterm-color value for $TERM is a bad choice for
XFree86 xterm because it is commonly used for a
terminfo entry which happens to not support bce.
Use the xterm-xfree86 entry which is distributed
with XFree86 xterm (or the similar one distributed
with ncurses)."
.PP
If you find other bugs, please send a report to calcurse@culot.org or to the
author, below.
.SH SEE ALSO
vi(1), less(1), ncurses(3), mkstemp(3)
.br
The ical specification (rfc2445) can be found at:
http://tools.ietf.org/html/rfc2445
.br
The pcal project page: http://pcal.sourceforge.net/
.br
Calcurse home page: http://culot.org/calcurse/
.br
Calcurse complete manual, translated in many languages and maintained in
html format, can be found in the doc/ directory of the source package,
or at: http://culot.org/calcurse/manual.html
.SH AUTHORS
\fBFrederic Culot\fP <frederic@culot.org>
.br
\fBLukas Fleischer\fP <calcurse@cryptocrack.de>
.SH COPYRIGHT
Copyright (c) 2004-2010 by Frederic Culot.
.br
This software is released under the BSD License.