From aaa000cd5aeeba7f1862d46f777df29cca8e8fd3 Mon Sep 17 00:00:00 2001 From: Lukas Fleischer Date: Thu, 3 Mar 2011 18:46:15 +0100 Subject: Convert man page to AsciiDoc. Signed-off-by: Lukas Fleischer --- Makefile.am | 7 +- configure.ac | 13 +++ doc/Makefile.am | 12 +++ doc/calcurse.1.txt | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++++ src/calcurse.1 | 269 --------------------------------------------------- 5 files changed, 302 insertions(+), 274 deletions(-) create mode 100644 doc/calcurse.1.txt delete mode 100644 src/calcurse.1 diff --git a/Makefile.am b/Makefile.am index 8a0d22f..b37844b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 diff --git a/configure.ac b/configure.ac index 6bfbc94..0b50478 100644 --- a/configure.ac +++ b/configure.ac @@ -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 #------------------------------------------------------------------------------- diff --git a/doc/Makefile.am b/doc/Makefile.am index 28bbb55..2f5edb4 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt new file mode 100644 index 0000000..ed3ab3d --- /dev/null +++ b/doc/calcurse.1.txt @@ -0,0 +1,275 @@ +//// +/* + * Copyright (c) 2004-2010 Frederic Culot + * 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* | *-D*] + [*-i*] [*-x*[format]] [*-d* |] + [*-s*[date]] [*-r*[range]] [*-S* ] [*--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* , *--calendar* :: + Specify the calendar file to use. The default calendar is + *~/.calcurse/apts* (see section 'FILES' below). This option is incompatible + with -*D*. + +*-d* , *--day* :: + 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* , *--directory* :: + 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* , *--import* :: + 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*, *--search*=:: + 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* +* *Lukas Fleischer* + +Copyright +--------- + +Copyright (c) 2004-2010 by Frederic Culot. +This software is released under the BSD License. diff --git a/src/calcurse.1 b/src/calcurse.1 deleted file mode 100644 index 6fe9eed..0000000 --- a/src/calcurse.1 +++ /dev/null @@ -1,269 +0,0 @@ -.\" Copyright (c) 2004-2010 Frederic Culot -.\" 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 , \fB--calendar\fP -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 , \fB--day\fP -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 , \fB--directory\fP -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 , \fB--import\fP -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, \fB--search\fP= -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 -.br -\fBLukas Fleischer\fP -.SH COPYRIGHT -Copyright (c) 2004-2010 by Frederic Culot. -.br -This software is released under the BSD License. -- cgit v1.2.3-70-g09d2