[akonadi-calendar-tools] doc/konsolekalendar: Update konsolekalendar docbook to kf5
Burkhard Lück
lueck at hube-lueck.de
Sun Dec 4 14:33:45 UTC 2016
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>
<!--
More information about the kde-doc-english
mailing list