diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 5 | ||||
| -rw-r--r-- | doc/calcurse.1.txt | 134 | ||||
| -rw-r--r-- | doc/manual.txt | 260 | ||||
| -rw-r--r-- | doc/submitting-patches.txt | 192 |
4 files changed, 520 insertions, 71 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..6768088 100644 --- a/doc/calcurse.1.txt +++ b/doc/calcurse.1.txt @@ -1,6 +1,6 @@ //// /* - * Copyright (c) 2004-2011 calcurse Development Team <misc@calcurse.org> + * Copyright (c) 2004-2012 calcurse Development Team <misc@calcurse.org> * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -42,7 +42,7 @@ Synopsis -------- [verse] -*calcurse* [*-h*|*-v*] [*-N*] [*-an*] [*-t*[num]] [*-c*<file> | *-D*<dir>] +*calcurse* [*-h*|*-v*] [*-an*] [*-t*[num]] [*-c*<file> | *-D*<dir>] [*-i*<file>] [*-x*[format]] [*-d* <date>|<num>] [*-s*[date]] [*-r*[range]] [*-S* <regex>] [*--status*] @@ -103,6 +103,32 @@ 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/*. +*--format-apt* <format>:: + Specify a format to control the output of appointments in non-interactive + mode. See the 'FORMAT STRINGS' section for detailed information on format + strings. + +*--format-recur-apt* <format>:: + Specify a format to control the output of recurrent appointments in + non-interactive mode. See the 'FORMAT STRINGS' section for detailed + information on format strings. + +*--format-event* <format>:: + Specify a format to control the output of events in non-interactive mode. See + the 'FORMAT STRINGS' section for detailed information on format strings. + +*--format-recur-event* <format>:: + Specify a format to control the output of recurrent events in non-interactive + mode. See the 'FORMAT STRINGS' section for detailed information on format + strings. + +*--format-todo* <format>:: + Specify a format to control the output of todo items in non-interactive mode. + See the 'FORMAT STRINGS' section for detailed information on format strings. + +*-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. @@ -117,14 +143,16 @@ appointments can be specified using the *-c* flag. '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. +*--read-only*:: + Don't save configuration nor appointments/todos. ++ +'Warning:' Use this this with care! If you run an interactive calcurse instance +in read-only mode, all changes from this session will be lost without warning! + *-s*[date], *--startday*[=date]:: Print events and appointments from 'date' and exit. If no 'date' is given, the current day is considered. @@ -161,6 +189,98 @@ such as: $ calcurse --export > my_data.dat ---- +'Note:' The *-N* option has been removed in calcurse 3.0.0. See the 'FORMAT +STRINGS' section on how to print note along with appointments and events. + +Format strings +-------------- + +Format strings are composed of printf()-style format specifiers -- ordinary +characters are copied to stdout without modification. Each specifier is +introduced by a *%* and is followed by a character which specifies the field to +print. The set of available fields depends on the item type. + +Format specifiers for appointments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*s*:: + Print the start time of the appointment as UNIX time stamp +*S*:: + Print the start time of the appointment using the *hh:mm* format +*d*:: + Print the duration of the appointment in seconds +*e*:: + Print the end time of the appointment as UNIX time stamp +*E*:: + Print the end time of the appointment using the *hh:mm* format +*m*:: + Print the description of the item +*n*:: + Print the name of the note file belonging to the item +*N*:: + Print the note belonging to the item + +Format specifiers for events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*m*:: + Print the description of the item +*n*:: + Print the name of the note file belonging to the item +*N*:: + Print the note belonging to the item + +Format specifiers for todo items +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*p*:: + Print the priority of the item +*m*:: + Print the description of the item +*n*:: + Print the name of the note file belonging to the item +*N*:: + Print the note belonging to the item + +Examples +~~~~~~~~ + +*`calcurse -r7 --format-apt='- %S -> %E\n\t%m\n%N'`*:: + Print appointments and events for the next seven days. Also, print the notes + attached to each regular appointment (simulates *-N* for appointments). + +*`calcurse -r7 --format-apt=' - %m (%S to %E)\n' --format-recur-apt=' - %m (%S to %E)\n'`*:: + Print appointments and events for the next seven days and use a custom format + for (recurrent) appointments: * - Some appointment (18:30 to 21:30)*. + +*`calcurse -t --format-todo '(%p) %m\n'`*:: + List all todo items and put parentheses around the priority specifiers. + +Extended format specifiers +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extended format specifiers can be used if you want to specify advanced +formatting options. Extended specifiers are introduced by *%(* and are +terminated by a closing parenthesis (*)*). The following list includes all +short specifiers and corresponding long options: + +* *s*: *(start)* +* *S*: *(start:epoch)* +* *d*: *(duration)* +* *e*: *(end)* +* *E*: *(end:epoch)* +* *m*: *(message)* +* *n*: *(noteid)* +* *N*: *(note)* +* *p*: *(priority)* + +The *(start)* and *(end)* specifiers support strftime()-style extended +formatting options that can be used for fine-grained formatting. Additionally, +the special formats *epoch* (which is equivalent to *(start:%s)* or *(end:%s)*) +and *default* (which is mostly equivalent to *(start:%H:%M)* or *(end:%H:%M)* +but displays *..:..* if the item doesn't start/end at the current day) are +supported. + Notes ----- @@ -271,5 +391,5 @@ Authors Copyright --------- -Copyright (c) 2004-2011 calcurse Development Team. +Copyright (c) 2004-2012 calcurse Development Team. This software is released under the BSD License. diff --git a/doc/manual.txt b/doc/manual.txt index c0a992d..80993cf 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -1,6 +1,6 @@ //// /* - * Copyright (c) 2004-2011 calcurse Development Team <misc@calcurse.org> + * Copyright (c) 2004-2012 calcurse Development Team <misc@calcurse.org> * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -36,7 +36,7 @@ CALCURSE - text-based organizer Abstract -------- -This manual describes `calcurse` functionnalities, and how to use them. The +This manual describes `calcurse` functionalities, and how to use them. The installation from source is first described, together with the available command line arguments. The user interface is then presented, with all of the customizable options that change `calcurse` behavior. Last, bug reporting @@ -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 @@ -201,7 +200,7 @@ days will be returned. As an example, typing `calcurse -d 3` will display your appointments for today, tomorrow, and the day after tomorrow. Possible formats for specifying the date are defined inside the general configuration menu (see <<options_general,General options>>), using the -`input_datefmt` variable. +`format.inputdate` variable. + Note: as for the `-a` flag, the calendar from which to read the appointments can be specified using the `-c` flag. @@ -210,6 +209,34 @@ 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/`. +`--format-apt <format>`:: + Specify a format to control the output of appointments in non-interactive + mode. See the <<basics_format_strings,Format strings>> section for detailed + information on format strings. + +`--format-recur-apt <format>`:: + Specify a format to control the output of recurrent appointments in + non-interactive mode. See the <<basics_format_strings,Format strings>> + section for detailed information on format strings. + +`--format-event <format>`:: + Specify a format to control the output of events in non-interactive mode. See + the <<basics_format_strings,Format strings>> section for detailed information + on format strings. + +`--format-recur-event <format>`:: + Specify a format to control the output of recurrent events in non-interactive + mode. See the <<basics_format_strings,Format strings>> section for detailed + information on format strings. + +`--format-todo <format>`:: + Specify a format to control the output of todo items in non-interactive mode. + See the <<basics_format_strings,Format strings>> section for detailed + information on format strings. + +`-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. @@ -224,14 +251,16 @@ can be specified using the `-c` flag. 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. +`--read-only`:: + Don't save configuration nor appointments/todos. ++ +WARNING: Use this this with care! If you run an interactive calcurse instance +in read-only mode, all changes from this session will be lost without warning! + `-s[date], --startday[=date]`:: Print events and appointments from date and exit. If no date is given, the current day is considered. @@ -268,6 +297,100 @@ such as: $ calcurse --export > my_data.dat ---- +NOTE: The `-N` option has been removed in calcurse 3.0.0. See the +<<basics_format_strings,Format strings>> section on how to print note along +with appointments and events. + +[[basics_format_strings]] +Format strings +^^^^^^^^^^^^^^ + +Format strings are composed of printf()-style format specifiers -- ordinary +characters are copied to stdout without modification. Each specifier is +introduced by a `%` and is followed by a character which specifies the field to +print. The set of available fields depends on the item type. + +Format specifiers for appointments +++++++++++++++++++++++++++++++++++ + +`s`:: + Print the start time of the appointment as UNIX time stamp +`S`:: + Print the start time of the appointment using the `hh:mm` format +`d`:: + Print the duration of the appointment in seconds +`e`:: + Print the end time of the appointment as UNIX time stamp +`E`:: + Print the end time of the appointment using the `hh:mm` format +`m`:: + Print the description of the item +`n`:: + Print the name of the note file belonging to the item +`N`:: + Print the note belonging to the item + +Format specifiers for events +++++++++++++++++++++++++++++ + +`m`:: + Print the description of the item +`n`:: + Print the name of the note file belonging to the item +`N`:: + Print the note belonging to the item + +Format specifiers for todo items +++++++++++++++++++++++++++++++++ + +`p`:: + Print the priority of the item +`m`:: + Print the description of the item +`n`:: + Print the name of the note file belonging to the item +`N`:: + Print the note belonging to the item + +Examples +++++++++ + +`calcurse -r7 --format-apt='- %S -> %E\n\t%m\n%N'`:: + Print appointments and events for the next seven days. Also, print the notes + attached to each regular appointment (simulates `-N` for appointments). + +`calcurse -r7 --format-apt=' - %m (%S to %E)\n' --format-recur-apt=' - %m (%S to %E)\n'`:: + Print appointments and events for the next seven days and use a custom format + for (recurrent) appointments: ` - Some appointment (18:30 to 21:30)`. + +`calcurse -t --format-todo '(%p) %m\n'`:: + List all todo items and put parentheses around the priority specifiers. + +Extended format specifiers +++++++++++++++++++++++++++ + +Extended format specifiers can be used if you want to specify advanced +formatting options. Extended specifiers are introduced by `%(` and are +terminated by a closing parenthesis (`)`). The following list includes all +short specifiers and corresponding long options: + +* `s`: `(start)` +* `S`: `(start:epoch)` +* `d`: `(duration)` +* `e`: `(end)` +* `E`: `(end:epoch)` +* `m`: `(message)` +* `n`: `(noteid)` +* `N`: `(note)` +* `p`: `(priority)` + +The `(start)` and `(end)` specifiers support strftime()-style extended +formatting options that can be used for fine-grained formatting. Additionally, +the special formats `epoch` (which is equivalent to `(start:%s)` or `(end:%s)`) +and `default` (which is mostly equivalent to `(start:%H:%M)` or `(end:%H:%M)` +but displays `..:..` if the item doesn't start/end at the current day) are +supported. + [[basics_invocation_variable]] Environment variable for i18n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -492,11 +615,11 @@ for upcoming appointments and runs the user-defined notification command when necessary. When the user interface is started again, the daemon automatically stops. -`calcurse` background activity can be logged (set the `notify-daemon_log` -variable in the notification configuration <<options_notify,menu>>), -and in that case, information about the daemon start and stop time, reminders' -command launch time, signals received... will be written in the `daemon.log` -file (see section <<basics_files,files>>). +`calcurse` background activity can be logged (set the `daemon.log` variable in +the notification configuration <<options_notify,menu>>), and in that case, +information about the daemon start and stop time, reminders' command launch +time, signals received... will be written in the `daemon.log` file (see section +<<basics_files,files>>). Using the `--status` command line option (see section <<basics_invocation_commandline,Command line arguments>>), one can know if @@ -530,9 +653,10 @@ $HOME/.calcurse/ ---- `notes/`:: this 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. + appointments, events or todos. Since the file name of each note file is a + SHA1 hash of the note itself, multiple items can share the same note file. + calcurse provides a garbage collector (see the `-g` command line parameter) + that can be used to remove note files which are no longer linked to any item. `conf`:: this file contains the user configuration `keys`:: @@ -618,55 +742,57 @@ General options These options control `calcurse` general behavior, as described below: -`auto_save` (default: *yes*):: +`general.autosave` (default: *yes*):: This option allows to automatically save the user's data (if set to *yes*) when quitting. <p class="rq"><span class="valorise">warning:</span> No data - 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. + will be automatically saved if `general.autosave` is set to *no*. This means + the user must press `S` (for saving) in order to retrieve its modifications. -`periodic_save` (default: *0*):: +`general.autogc` (default: *no*):: + Automatically run the garbage collector for note files when quitting. + +`general.periodicsave` (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 - (i.e. `**`) will appear on the top right-hand side of the screen). + *general.periodicsave* minutes. When an automatic save is performed, two + asterisks (i.e. `**`) will appear on the top right-hand side of the screen). -`confirm_quit` (default: *yes*):: +`general.confirmquit` (default: *yes*):: If set to *yes*, confirmation is required before quitting, otherwise pressing `Q` will cause `calcurse` to quit without prompting for user confirmation. -`confirm_delete` (default: *yes*):: +`general.confirmdelete` (default: *yes*):: If this option is set to *yes*, pressing `D` for deleting an item (either a *todo*, *appointment*, or *event*), will lead to a prompt asking for user confirmation before removing the selected item from the list. Otherwise, no confirmation will be needed before deleting the item. -`skip_system_dialogs` (default: *no*):: - Setting this option to *yes* will result in skipping the system dialogs +`general.systemdialogs` (default: *yes*):: + Setting this option to *no* will result in skipping the system dialogs related to the saving and loading of data. This can be useful to speed up the input/output processes. -`skip_progress_bar` (default: *no*):: - If set to *yes*, this will cause the disappearing of the progress bar which - is usually shown when saving data to file. If set to *no*, this bar will be +`general.progressbar` (default: *yes*):: + If set to *no*, this will cause the disappearing of the progress bar which is + usually shown when saving data to file. If set to *yes*, this bar will be displayed, together with the name of the file being saved (see section <<basics_files,calcurse files>>). -`calendar_default_view` (default: *0*):: +`appearance.calendarview` (default: *0*):: If set to `0`, the monthly calendar view will be displayed by default otherwise it is the weekly view that will be displayed. -`week_begins_on_monday` (default: *yes*):: - One can choose between Monday and Sunday as the first day of the week. If the - option `week_begins_on_monday` is set to *yes*, Monday will be first in the - calendar view. Else if the option is set to *no*, then Sunday will be the - first day of the week. +`general.firstdayofweek` (default: *monday*):: + One can choose between Monday and Sunday as the first day of the week. If + `general.firstdayofweek` is set to *monday*, Monday will be first in the + calendar view. Otherwise, Sunday will be the first day of the week. -`output_datefmt` (default: *%D*):: +`format.outputdate` (default: *%D*):: This option indicates the format to be used when displaying dates in non-interactive mode. Using the default values, dates are displayed the following way: *mm/dd/aa*. You can see all of the possible formats by typing `man 3 strftime` inside a terminal. -`input_datefmt` (default: *1*):: +`format.inputdate` (default: *1*):: This option indicates the format that will be used to enter dates in *calcurse*. Four choices are available: + @@ -679,12 +805,12 @@ These options control `calcurse` general behavior, as described below: Key bindings ~~~~~~~~~~~~ -One can define it's own keybindings within the `Keys` configuration menu. The +One can define ones own key bindings within the `Keys` configuration menu. The default keys look like the one used by the `vim` editor, especially the displacement keys. Anyway, within this configuration menu, users can redefine all of the keys available from within calcurse's user interface. -To define new keybindings, first highlight the action to which it will apply. +To define new key bindings, first highlight the action to which it will apply. Then, delete the actual key binding if necessary, and add a new one. You will then be asked to press the key corresponding to the new binding. It is possible to define more than one key binding for a single action. @@ -710,6 +836,10 @@ While inside the key configuration menu, an online help is available for each one of the available actions. This help briefly describes what the highlighted action is used for. +NOTE: As of calcurse 3.0.0, displacement commands can be preceded by an + optional number to repeat the command. For example, `10k` will move the + cursor ten weeks forwards if you use default key bindings. + Color themes ~~~~~~~~~~~~ @@ -726,7 +856,7 @@ bar. A black and white theme is also available, in order to support non-color terminals. NOTE: Depending on your terminal type and on the value of the `$TERM` - environnement variable, color could or could not be supported. An error + environment variable, color could or could not be supported. An error message will appear if you try to change colors whereas your terminal does not support this feature. If you do know your terminal supports colors but could not get `calcurse` to display them, try to set your @@ -740,13 +870,13 @@ The default layout makes the calendar panel to be displayed on the top-right corner of the terminal, the todo panel on the bottom-right corner, while the appointment panel is displayed on the left hand-side of the screen (see the figure in section <<basics_interface_interactive,Interactive mode>> for an -exemple of the default layout). By choosing another layout in the -configuration screen, user can customize `calcurse` appearence to best suit his +example of the default layout). By choosing another layout in the +configuration screen, user can customize `calcurse` appearance to best suit his needs by placing the different panels where needed. The following option is used to modify the layout configuration: -`layout` (default: *0*):: +`appearance.layout` (default: *0*):: Eight different layouts are to be chosen from (see layout configuration screen for the description of the available layouts). @@ -759,7 +889,7 @@ list. The following option is used to change the width of the sidebar: -`side-bar_width` (default: *0*):: +`appearance.sidebarwidth` (default: *0*):: Width (in percentage, 0 being the minimum width) of the side bar. [[options_notify]] @@ -768,27 +898,27 @@ Notify-bar settings The following options are used to modify the notify-bar behavior: -`notify-bar_show` (default: *yes*):: +`appearance.notifybar` (default: *yes*):: This option indicates if you want the notify-bar to be displayed or not. -`notify-bar_date` (default: *%a %F*):: +`format.notifydate` (default: *%a %F*):: With this option, you can specify the format to be used to display the current date inside the notification bar. You can see all of the possible formats by typing `man 3 strftime` inside a terminal. -`notify-bar_time` (default: *%T*):: +`format.notifytime` (default: *%T*):: With this option, you can specify the format to be used to display the current time inside the notification bar. You can see all of the possible formats by typing `man 3 strftime` inside a terminal. -`notify-bar_warning` (default: *300*):: +`notification.warning` (default: *300*):: When there is an appointment which is flagged as `important` within the next - `notify-bar_warning` seconds, the display of that appointment inside the - notify-bar starts to blink. Moreover, the command defined by the - `notify-bar_command` option will be launched. That way, the user is warned + `notification.warning` seconds, the display of that appointment inside the + notify-bar starts to blink. Moreover, the command defined by the + `notification.command` option will be launched. That way, the user is warned and knows there will be soon an upcoming appointment. -`notify-bar_command` (default: *printf '\a'*):: +`notification.command` (default: *printf '\a'*):: This option indicates which command is to be launched when there is an upcoming appointment flagged as `important`. This command will be passed to the user's shell which will interpret it. To know what shell must be used, @@ -805,13 +935,17 @@ $ calcurse --next | mail -s "[calcurse] upcoming appointment!" user@host.com ---- ==== -`notify-daemon_enable` (default: *no*):: +`notification.notifyall` (default: *no*):: + Invert the sense of flagging an appointment as `important`. If this is + enabled, all appointments will be notified - except for flagged ones. + +`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 notifications to be launched even when the interface is not running. More details can be found in section <<basics_daemon,Background mode>>. -`notify-daemon_log` (default: *no*):: +`daemon.log` (default: *no*):: If set to yes, `calcurse` daemon activity will be logged (see section <<basics_files,files>>). @@ -825,9 +959,9 @@ 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)." +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)." ____ [[bugs]] @@ -878,7 +1012,7 @@ http://www.gnu.org/software/gettext/manual/ IMPORTANT: Since we switched to Transifex, editing *po* files is not necessary anymore as Transifex provides a user-friendly, intuitive web - interface for translators. Knowlegde of `gettext` and the *po* + interface for translators. Knowledge of `gettext` and the *po* format is still useful for those of you who prefer the command line and local editing. If you want to use the web UI to edit the translation strings, you can skip over to <<transifex_webui,Using @@ -906,12 +1040,12 @@ translation. So, translatable strings are first marked by the coders within the `C` source files, then gathered in a template file (*calcurse.pot* - the *pot* extension meaning *portable object template*). The content of this template file is then -merged with the translation files for each language (*fr.po* for french, for +merged with the translation files for each language (*fr.po* for French, for instance - with *po* standing for *portable object*, ie meant to be read and edited by humans). A given translation team will take this file, translate its strings, and send it back to the developers. At compilation time, a binary version of this file (for efficiency reasons) will be produced (*fr.mo* - *mo* -stands for *machine object*, ie meant to be read by programs), and then +stands for *machine object*, i.e. meant to be read by programs), and then installed. Then `calcurse` will use this file at runtime, translating the strings according to the locale settings of the user. @@ -1050,7 +1184,7 @@ Using transifex-client You can also use a command line client to submit translations instead of having to use the web interface every time you want to submit an updated version. If -you have a recent version of setuptools installed, you can get the CLI client +you have a recent version of `setuptools` installed, you can get the CLI client by issuing the following command: ---- @@ -1074,7 +1208,7 @@ To submit changes back to the server, use: $ tx push -r calcurse.calcursepot -t -l <locale> ---- -For more details, read up on transifex-client usage at the +For more details, read up on `transifex-client` usage at the http://help.transifex.net/user-guide/client/[The Transifex Command-line Client v0.4] section of the http://help.transifex.net/[Transifex documentation]. diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt new file mode 100644 index 0000000..0b20fad --- /dev/null +++ b/doc/submitting-patches.txt @@ -0,0 +1,192 @@ +//// +/* + * Copyright (c) 2004-2012 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. |