Git commit b17eabf70021e281657b5d7e741b382bd56ba634 by Burkhard Lück. Committed on 04/12/2016 at 14:33. Pushed by lueck into branch 'master'.
Update konsolekalendar docbook to kf5 remove entities kappname + package, no longer used bump date + releaseinfo remove &kde; update options remove appendix installation BUG:346221 REVIEW:129558 M +105 -96 doc/konsolekalendar/index.docbook https://commits.kde.org/akonadi-calendar-tools/b17eabf70021e281657b5d7e741b382bd56ba634 diff --git a/doc/konsolekalendar/index.docbook b/doc/konsolekalendar/index.docbook index 56d7734..4155c91 100644 --- a/doc/konsolekalendar/index.docbook +++ b/doc/konsolekalendar/index.docbook @@ -3,8 +3,6 @@ "dtd/kdedbx45.dtd" [ <!ENTITY konsolekalendar "<application>KonsoleKalendar</application>"> - <!ENTITY kappname "KonsoleKalendar"> - <!ENTITY package "kdepim"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> ]> @@ -50,8 +48,8 @@ <!-- Don't change format of date and version of the documentation --> -<date>2004-04-15</date> -<releaseinfo>1.1.1</releaseinfo> +<date>2016-11-23</date> +<releaseinfo>5.1.3 (Applications 16.12)</releaseinfo> <abstract> <para>&konsolekalendar; is a command line interface to &kde; calendars.</para> @@ -70,12 +68,12 @@ <chapter id="introduction"> <title>Introduction</title> -<para>&konsolekalendar; is a command line interface to &kde; calendars. +<para>&konsolekalendar; is a command line interface to calendars. It lets you view, insert, remove, or modify calendar events by way of the command line or from a scripting language. -Additionally, &konsolekalendar; can create a new &kde; calendar, -export a &kde; calendar to a variety of other formats, and -import another &kde; calendar.</para> +Additionally, &konsolekalendar; can create a new calendar, +export a calendar to a variety of other formats, and +import another calendar.</para> <para>In its basic mode, &konsolekalendar; displays the list of events in your default calendar for the current day (from 7:00 to 17:00).</para> @@ -88,7 +86,7 @@ events in your default calendar for the current day (from 7:00 to 17:00).</para> <listitem><para>Modify (change) calendar entries</para></listitem> <listitem><para>Create a new calendar</para></listitem> <listitem><para>Export calendar entries to other file formats</para></listitem> -<listitem><para>Import an existing &kde; calendar</para></listitem> +<listitem><para>Import an existing calendar</para></listitem> </itemizedlist></para> <para>&konsolekalendar; is <emphasis>not</emphasis> another graphical @@ -115,7 +113,7 @@ it is a command line program only).</para> <para> You'll learn about inserting, deleting, and changing calendar events, and how to export events to other file formats. -The creation and importation of &kde; calendars will also be covered +The creation and importation of calendars will also be covered in this chapter. </para> @@ -143,7 +141,7 @@ date/time.</para> <para> <screen> -<prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--view</option> <option>--date <replaceable>2003-08-18</replaceable> </option> <option>--end-date <replaceable>2003-08-22</replaceable></option> +<prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--view</option> <option>--date <replaceable>2016-08-18</replaceable> </option> <option>--end-date <replaceable>2016-08-22</replaceable></option> </userinput> </screen> </para> @@ -180,19 +178,24 @@ date/time.</para> <sect1 id="inserting"> <title>Inserting Events</title> -<para>&konsolekalendar; can insert events into a &kde; calendar or calendar +<para>&konsolekalendar; can insert events into a calendar or calendar resource using the <parameter>--add</parameter> command line argument. Events successfully inserted will be immediately shown by &kde; calendar applications (like &korganizer;).</para> +<para>You get a list of all calendars and their id's using: +</para> + +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--list-calendars</option></userinput></screen> + <para> -<informalexample><para>In the following example, an event starting on 2003-06-04 (June 4, 2003) -at 1000 and ending at 1200 with summary "Doctor Visit" will be -inserted into the user's default calendar resource:</para> +<informalexample><para>In the following example, an event starting on 2016-12-01 (December 4, 2016) +at 10:00 and ending at 12:00 with summary "Doctor Visit" will be +inserted into the user's calendar resource with the id 8:</para> <para> -<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--date <replaceable>2003-06-04</replaceable></option> <option>--time <replaceable>10:00</replaceable></option> \ +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--calendar 8</option> <option>--date <replaceable>2016-12-03</replaceable></option> <option>--time <replaceable>10:00</replaceable></option> \ <option>--end-time <replaceable>12:00</replaceable></option> <option>--summary <replaceable>"Doctor Visit"</replaceable></option></userinput></screen> </para> </informalexample> @@ -200,21 +203,21 @@ inserted into the user's default calendar resource:</para> <para> <informalexample><para>In this example, a birthday event is added into the -user's default calendar resource:</para> +user's calendar resource with the id 8:</para> <para> -<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--date <replaceable>2003-06-06</replaceable></option> <option>--summary <replaceable>"My Birthday"</replaceable></option> \ +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--calendar 8</option> <option>--date <replaceable>2016-12-06</replaceable></option> <option>--summary <replaceable>"My Birthday"</replaceable></option> \ <option>--description <replaceable>"Party Time"</replaceable></option></userinput></screen> </para> </informalexample> </para> <para> -<informalexample><para> Here a one week vacation is inserted into a shared <replaceable>vacation</replaceable> calendar:</para> +<informalexample><para> Here a one week vacation is inserted into a calendar with the id 8:</para> <para> -<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--file <replaceable>vacation.ics</replaceable></option> <option>--date <replaceable>2003-08-01</replaceable></option> \ -<option>--end-date <replaceable>2003-08-07</replaceable></option> <option>--summary <replaceable>"Vacation"</replaceable></option> <option>--description <replaceable>"Nobody will ever find me!"</replaceable></option></userinput></screen> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--calendar <replaceable>12</replaceable></option> <option>--date <replaceable>2017-08-01</replaceable></option> \ +<option>--end-date <replaceable>2017-08-07</replaceable></option> <option>--summary <replaceable>"Vacation"</replaceable></option> <option>--description <replaceable>"Nobody will ever find me!"</replaceable></option></userinput></screen> </para> </informalexample> </para> @@ -229,7 +232,8 @@ resource using the <parameter>--delete</parameter> command line argument. Calendar entries to be removed are specified exactly by their Unique-string identifier (<acronym>UID</acronym>) using the <parameter>--uid</parameter> option. <acronym>UIDs</acronym> are found by first viewing the event, -using the <parameter>--view</parameter> option.</para> +using the <parameter>--view</parameter>, <parameter>--next</parameter> +or <parameter>--show-next</parameter> options.</para> <para>Events successfully deleted will be immediately removed from within &kde; calendar applications (&korganizer; for example).</para> @@ -257,7 +261,8 @@ file or resource using the <parameter>--change</parameter> command line argument Calendar entries to be modified are specified exactly by their Unique-string identifier (<acronym>UID</acronym>) using the <parameter>--uid</parameter> option. <acronym>UIDs</acronym> are found by first viewing the event, -using the <parameter>--view</parameter> option.</para> +using the <parameter>--view</parameter>, <parameter>--next</parameter> +or <parameter>--show-next</parameter> options.</para> <para> Changing behaves in the same way as inserting: you can change an event's start date @@ -285,27 +290,41 @@ of a calendar entry with <acronym>UID</acronym> <replaceable>&konsolekalendar;-1 <sect1 id="creating"> <title>Creating a New Calendar File</title> -<para>&konsolekalendar; can be used to create a new &kde; calendar file. -Since you cannot insert an entry into a calendar that does not exist, -you must create the file first using the <parameter>--create</parameter> -and <parameter>--file</parameter> command line arguments.</para> +<para>&konsolekalendar; can be used to create new calendars from existing files. +You can create the calendar using the option <option>--create</option> +with the filename as argument. +The file must be a valid <acronym>iCal</acronym> or <acronym>vCal</acronym> file.</para> +<para>Note: You can not use the option <option>--dry-run</option> to test if +the resource can be created.</para> -<para> -<informalexample><para>Create a calendar file named -<filename><replaceable>/data/share/calendars/vacation.ics</replaceable></filename>:</para> +<para>Note: &konsolekalendar; needs the file to work, so never delete the file by hand. +</para> + +<para>Technical sidenote: &konsolekalendar; creates with this command a new <acronym>Akonadi</acronym> resource pointing to this file. +It does not prevent you to create multiple resources pointing to the same file. +</para> <para> -<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--create</option> <option>--file <replaceable>/data/share/calendars/vacation.ics</replaceable></option></userinput></screen> +<informalexample><para>Create a new calendar from an existing file named +<filename><replaceable>vacation.ics</replaceable></filename>:</para> +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--create</option> <option><replaceable>vacation.ics</replaceable></option></userinput></screen> </para> </informalexample> </para> +<para>The resource will be named <quote>vacation</quote> using <option>--list-calendars</option></para> + +<para>It is not possible to delete an <acronym>Akonadi</acronym> resource with &konsolekalendar;, you +have to use &korganizer; or <application>akonadiconsole</application>. +</para> + </sect1> <sect1 id="exporting"> <title>Exporting to Other Formats</title> -<para>&konsolekalendar; can export a &kde; calendar to other well known formats. +<para>&konsolekalendar; can export a calendar to other well known formats. Exporting is a special form of viewing. By default, events are viewed in <quote>&konsolekalendar; text</quote> format. To change the viewing format use the <parameter>--export-type</parameter> command line argument.</para> @@ -354,10 +373,10 @@ UID: </informalexample> </para> -<para>For example: +<para>Output of <userinput> <command>konsolekalendar</command> <option>--next</option> <option>--export-type</option> <option>Text</option></userinput>: <informalexample> <screen> -Date: Tuesday 2003-11-01 +Date: Tuesday 2016-11-29 08:00 - 09:00 Summary: Staff Meeting @@ -366,7 +385,7 @@ Location: Description: Meet with the entire staff to discuss the project. UID: - &konsolekalendar;-1128954167.1013 + &konsolekalendar;-1924621834.134 -------------------------------------------------- </screen> </informalexample> @@ -392,11 +411,11 @@ UID: </informalexample> </para> -<para>For example: +<para>Output of <userinput> <command>konsolekalendar</command> <option>--next</option> <option>--export-type</option> <option>Short</option></userinput>: <informalexample> <screen> -------------------------------------------------- -Tuesday 2003-11-01 +Tuesday 2016-11-29 08:00 - 09:00 Staff Meeting, Conference Room Meet with the entire staff to discuss the project. </screen> @@ -412,23 +431,23 @@ Tuesday 2003-11-01 as &konsolekalendar; Text format. The only difference is that all the information is on the same row with each field separated by a comma. The resulting exported files can be imported directly into spreadsheet programs -like &kspread;, <application>OpenOffice.org Calc</application>, +like &calligrasheets;, <application>OpenOffice.org Calc</application>, and <application>&Microsoft; Excel</application>. Also, <acronym>CSV</acronym> format is easy to parse with follow-on scripts.</para> <para>The Comma-Separated Value (<acronym>CSV</acronym>) format is: <informalexample> <screen> -YYYY-MM-DD,HH:MM,YYYY-MM-DD,HH:MM,Summary,Location,Description,UID +"Weekday, Month Day, Year","HH:MM","Weekday, Month Day, Year","HH:MM","Summary","Location","Description","UID" </screen> </informalexample> </para> -<para>For example: +<para>Output of <userinput> <command>konsolekalendar</command> <option>--next</option> <option>--export-type</option> <option>CSV</option></userinput>: <informalexample> <screen> -2003-11-01,08:00,2003-11-01,09:00,Staff Meeting,Conference Room,Meet in the big conference \ -room with the entire staff.,&konsolekalendar;-1128954167.1013 +"Tuesday, November 29, 2016","08:00","Tuesday, November 29, 2016","09:00","Staff Meeting","Conference Room","Meet in the big conference \ +room with the entire staff.","&konsolekalendar;-1924621834.134" </screen> </informalexample> </para> @@ -442,9 +461,10 @@ room with the entire staff.,&konsolekalendar;-1128954167.1013 &HTML; file that can be published to the <acronym>WWW</acronym>. This export format is not suitable for follow-on script parsing, but is very nice for publishing calendars for easy public viewing.</para> - +<!--FIXME +exports only the template without any incidence data <para><emphasis>TODO:</emphasis> Insert screenshot here</para> - +--> </sect2> <sect2 id="html-month-format"> @@ -454,9 +474,10 @@ very nice for publishing calendars for easy public viewing.</para> all appointments in the months specified by the date range. This export format is not suitable for follow-on script parsing, but is very nice for publishing calendars for easy public viewing.</para> - +<!--FIXME +exports only the template without any incidence data <para><emphasis>TODO:</emphasis> Insert screenshot here</para> - +--> </sect2> </sect1> @@ -464,18 +485,17 @@ very nice for publishing calendars for easy public viewing.</para> <sect1 id="importing"> <title>Importing Calendars</title> -<para>&konsolekalendar; can import an iCal or vCal calendar file into a &kde; +<para>&konsolekalendar; can import an iCal or vCal calendar file into calendar. All events from the calendar being imported from will be inserted, -including identical events. In the next &konsolekalendar; release identical -events will not be inserted.</para> +skipping identical events, that are already part of the calendar.</para> <para> <informalexample><para> To import calendar file -<filename><replaceable>another.ics</replaceable></filename> into calendar -<filename><replaceable>current.ics</replaceable></filename> run:</para> +<replaceable>vacation.ics</replaceable> into calendar +with the id <replaceable>8</replaceable> run:</para> <para> -<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--import <replaceable>another.ics</replaceable></option> <option>--file <replaceable>current.ics</replaceable></option></userinput></screen> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--import <replaceable>vacation.ics</replaceable></option> <option>--calendar <replaceable>8</replaceable></option></userinput></screen> </para> </informalexample> </para> @@ -499,6 +519,9 @@ events will not be inserted.</para> </thead> <tbody> <row> + <entry><emphasis>Generic options:</emphasis></entry> +</row> +<row> <entry><option>--help, --help-all</option></entry> <entry>Shows help about the program options.</entry> </row> @@ -515,6 +538,9 @@ events will not be inserted.</para> <entry>Shows the program license information.</entry> </row> <row> + <entry><emphasis>Options:</emphasis></entry> +</row> +<row> <entry><option>--verbose</option></entry> <entry>Print helpful runtime messages.</entry> </row> @@ -527,10 +553,19 @@ events will not be inserted.</para> <entry>Permit resources which might need an interactive user interface. In normal operation, only resources which never will require a user interface are used (like file-based calendars).</entry> </row> <row> - <entry><option>--file</option> - <replaceable> calendar-file</replaceable></entry> - <entry>Specify a calendar file to use. - <para>If not specified then your default &korganizer; resource is used.</para></entry> + <entry><emphasis>Incidence types (these options can be combined):</emphasis></entry> +</row> +<row> + <entry><option>--event</option></entry> + <entry>Operate for Events only (Default).</entry> +</row> +<row> + <entry><option>--todo</option></entry> + <entry>Operate for Todos only. (Not implemented)</entry> +</row> +<row> + <entry><option>--journal</option></entry> + <entry>Operate for Journals only. (Not implemented)</entry> </row> <row> <entry><emphasis>Major Operation Modes:</emphasis></entry> @@ -552,8 +587,10 @@ events will not be inserted.</para> <entry>Remove an existing calendar event.</entry> </row> <row> - <entry><option>--create</option></entry> - <entry>Create a new calendar file if one does not exist.</entry> + <entry><option>--create</option> + <replaceable> filename</replaceable> + </entry> + <entry>Create a new calendar from existing file.</entry> </row> <row> <entry><option>--import</option> @@ -561,6 +598,10 @@ events will not be inserted.</para> <entry>Import this calendar to the main calendar.</entry> </row> <row> + <entry><option>--list-calendars</option></entry> + <entry>List available calendars.</entry> +</row> +<row> <entry><emphasis>Operation modifiers:</emphasis></entry> </row> <row> @@ -631,6 +672,12 @@ events will not be inserted.</para> <entry>Add location to event (works with add and change).</entry> </row> <row> + <entry><option>--calendar</option> + <replaceable> id</replaceable></entry> + <entry>Specify a calendar to use. + <para>If not specified then your default &korganizer; resource is used.</para></entry> +</row> +<row> <entry><emphasis>Export options:</emphasis></entry> </row> <row> @@ -657,9 +704,6 @@ events will not be inserted.</para> <chapter id="faq"> <title>Questions and Answers</title> -&reporting.bugs; -&updating.documentation; - <qandaset id="faqlist"> <qandaentry> <question> @@ -792,41 +836,6 @@ If you do not want to see event <acronym>UIDs</acronym> then use the </chapter> -<appendix id="installation"> -<title>Installation</title> - -<sect1 id="obtaining-application"> -<title>How to obtain &konsolekalendar;</title> - -&install.intro.documentation; - -<para>&konsolekalendar; comes included with &kde;4 and is not available separately. -</para> - -</sect1> - -<sect1 id="requirements"> -<title>Requirements</title> - -<para>&konsolekalendar; requires the standard &kde; libraries to be installed -(the <filename>kdelibs</filename> package and <filename>kdepimlibs</filename>). -To compile from source, you also need the &Qt;, <filename>kdelibs</filename> and -<filename>kdepimlibs</filename> development packages.</para> - -<para>You can find a list of changes in the -<filename>ChangeLog</filename> file.</para> -</sect1> - -<sect1 id="configuration"> -<title>Configuration</title> - -<para>No special configuration is required to set up &konsolekalendar; to run -on the &kde; desktop.</para> - -</sect1> - -</appendix> - &documentation.index; </book> <!--
