path: root/calendar/doc/C/gnomecal.sgml

<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
]>

<book id="gnomecal">
  <bookinfo>
    <title>GNOME calendar user's manual</title>
    <authorgroup>
      <author>
    <firstname>Dave</firstname> <surname>Mason</surname>
    <affiliation>
      <address>
        <email>dcm@redhat.com</email>
      </address>
    </affiliation>
      </author>
      <author>
    <firstname>Miguel</firstname> <surname>de Icaza
      Amozurrutia</surname>
    <affiliation>
      <address>
        <email>miguel@gnu.org</email>
      </address>
    </affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>1998, 1999</year> <holder>Miguel de Icaza, Dave Mason</holder>
    </copyright>
    <legalnotice>
      <para>This documentation is free software; you can redistribute
    it and/or modify it under the terms of the GNU General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later
    version.</para>
      
      <para>This program is distributed in the hope that it will be
    useful, but WITHOUT ANY WARRANTY; without even the implied
    warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    See the GNU General Public License for more details.</para>
      
      <para>You should have received a copy of the GNU General Public
    License along with this program; if not, write to the Free
    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
    MA 02111-1307 USA</para>
      
      <para>For more details see the file COPYING in the source
    distribution of GNOME.</para>
    </legalnotice>
  </bookinfo>

  <toc></toc>

  <chapter id="cmdline">
    <title>Command line options</title>

    <para>
      The following command line options are recognized by the
      <filename>gnomecal</filename> program.  You can use these
      options to alter the behaviour of the program or to quickly
      query the program for appointments, and to do items from the
      command line without requiring an X display.  These are useful
      for example to include in scripts.
    </para>

    <para>
      <itemizedlist>

        <listitem>
          <para>
            <emphasis>--events</emphasis>.  Displays the events for the
        date specified (or today, if no date is specified).
      </para>
        </listitem>

        <listitem>
          <para>
            <emphasis>--from DATE</emphasis>.  Define the beginning of
        the range for the event display, or the startup day on the
        calenday views.  By default, the event will span the whole
        day specified in DATE.
          </para>
        </listitem>

    <listitem>
          <para>
            <emphasis>--to DATE</emphasis>.  Define the range end for
        the event display.  If this is not specified, it will
        default to the end of the day specified by the
        <emphasis>--from</emphasis> option.
          </para>
        </listitem>

    <listitem>
          <para>
            <emphasis>--file FILE</emphasis>.  Set the calendar to the
        <emphasis>FILE</emphasis> specified on the command line.
          </para>
        </listitem>

    <listitem>
          <para>
            <emphasis>--todo</emphasis>.  Dumps the to-do values to
        standard output.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis>--userfile</emphasis>.  Use this if you want to
            force the file to be loaded to be the default user's
            calendar (this is the default, only used to override the
            --file if you have some sort of macro.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis>--geometry</emphasis>.  Used to specity the
            startup geometry of the application (location and size).
          </para>
        </listitem>
        
        <listitem>
          <para>
            <emphasis>--view VIEWMODE</emphasis>.  Use this to specify
            the startup view that should be used.
            <emphasis>VIEWMODE</emphasis> is one of: dayview,
            weekview, monthview, yearview.
          </para>
        </listitem>
     
      </itemizedlist>
    </para>

    <para>
      <emphasis>DATE</emphasis> is interpreted as being in the local
      time-zone, unless a specific timezone is specified.  Examples
      of valid date specifications include: "1 month ago", "2 hours
      ago", "400000 seconds ago", "last year", "last Monday",
      "yesterday", "a fortnight ago", "3/31/92 10:00:07 PST", "January
      23, 1987 10:05pm", "22:00 GMT".  
    </para>
  </chapter>

  <chapter id="tech.html">
    <title>Technical information about the GNOME calendar</title>

    <para>
      Currently, the GNOME calendar uses the vCal file format standard 
      for storing and loading its appointment and todo database.  This
      standard is widely used in various other calendar applications,
      so it provides a good mechanism for exchanging appointments.
    </para>
    <para>
      In the future the GNOME calendar will support the upcoming
      iCalendar specification as well.
    </para>
    <para>
      If you want to know more about the vCal specification, you can
      check the <ulink url="http://www.imc.org" type=http>Internet
      Mail Consortium (http://www.imc.org)</ulink> for the details.
    </para>
  </chapter>

 <chapter id="gcal">
  <title>The GNOME Calendar</title>
  <sect1>
   <title>Introduction</title>
   <para>
   <indexterm>
    <primary>
     GNOME Calendar
    </primary>
   </indexterm>
   <indexterm>
    <primary>
     Calendar
    </primary>
   </indexterm>
    The GNOME Calendar is a  simple calendar applications which can be quite 
    useful in your daily work. The Calendar, like much of GNOME, is in its 
    infancy and while it is a very useful application, there is some very 
    impressive functionality still to come like network shared calendar usage, 
    and syncing capability with Palm Pilots and other hand held PDAs. The
    Calendar can be launched from the <guimenu>Applications</guimenu> submenu of
    the Main Menu.
   </para>
   <para>
    The Calendar is broken up into four main tabs: Day, Week, Month,
    and Year. Each view allows you to view the respective time period
    but will also allow you to schedule appointments from any one of
    the tabs.
   </para>
   <figure>
     <title>The GNOME Calendar</title>
    <screenshot>
     <screeninfo>The GNOME Calendar</screeninfo>
      <Graphic Format="gif" Fileref="images/calday" srccredit="dcm">
      </graphic>
    </screenshot>
    </figure>
  </sect1>
  <sect1 id="calsetup" <title>Setting Up the GNOME Calendar</title>
   <para>
     The GNOME Calendar can be used in the state which it is shipped but there 
     are tools available to make sure it is setup the way you would like it to 
     be. The first place you should go is the GNOME Calendar Preferences. You 
     can find the Preferences dialog by selecting the 
     <guimenuitem>Preferences</guimenuitem> menu item from the <guimenu> 
     Settings</guimenu> menu.
   <figure>
    <title>The GNOME Calendar Preferences</title>
   <screenshot>
    <screeninfo>The GNOME Calendar Preferences.</screeninfo>
    <Graphic Format="gif" Fileref="images/cal-props" srccredit="dcm">
    </graphic>
   </screenshot>
   </figure>
   </para>
   <para>
    The Calendar Preferences dialog is broken up into three tabs, Time display,
    Colors, and Todo list.
   </para> 
   <para>
   Time - This tab is broken up into three main sections: Time format, Weeks 
   start on, and Day range.
   </para>  
   <para>
      Time format - This allows you to choose between a 12 or 24 hour format 
      clock.
   </para>
   <para>
      Weeks start on - This allows you to define what day your week will start 
      on, Sunday or Monday. This will affect how the calendar is laid out in the 
      Day and Week views.
   </para>
   <para>
      Day range - This section lets you choose what time your days will start 
      and end. Any hours outside the range selected will be shaded on your Day 
      view.
   </para>
   <para>
    Colors - This tab allows you to change the default colors used in the 
    Calendar. There are seven color choices you can customize: Outline, 
    Headings, Empty days, Appointments, Highlighted day, Day numbers, and 
    Current day's number. Each choice has a small color selector box next to 
    it. When you press this box you will be given a color selector dialog in 
    which you can choose the color you want. Once you have selected a color the 
    small sample calendar on the right side of the tab will preview your choice.
   </para>
   <para>
    Todo List - This tab allows you to define which columns will be shown in the
    Todo List in the Day View. You can set the Summary, Due Date, and Priority
    columns.
   </para>    
   <para>
    Once you have made the changes to the Calendar Preferences you may press the 
    <guibutton>Apply</guibutton> button to apply them.
   </para>
  </sect1>
  <sect1 id="caluse">
   <title>Using the GNOME Calendar</title>
   <para>
    Using the GNOME Calendar is quite simple and most tasks can be performed 
    from any of the major views, Day, Week, Month or Year. Probably one of the 
    most important features to remember is that at any time you may right mouse 
    click on a particular day and add a new appointment. There are many other 
    features which will be described below in each of the major views.
   </para>
     <sect2 id="calday">
    <title>The Day View</title>
    <para>
     The Day tab is probably the most useful view in the GNOME Calendar as it 
     acts just as a day timer would. On the left of the tab is the hour listing 
     for the current day. The light grey coloring in the hour list separates the 
     work hours from the non-work hours. If you would like to change the work 
     hours displayed in light grey you can do so in <xref 
     LinkEnd="calsetup">.
    </para>
    <figure>
     <title>The Day View</title>
      <screenshot>
       <screeninfo>The Day View</screeninfo>
       <Graphic Format="gif" Fileref="images/calday" srccredit="dcm">
       </graphic>
      </screenshot>
    </figure>
    <tip>
     <title>TIP</title>
     <para>
      One tip for adding a new appointment in the Day View is to select a few 
      hours in the hours list by clicking and dragging your mouse down the hours 
      list. Once the correct range of time has been selected you may press Enter
      and type in the appointment. This will allow you to skip the Create New
      Appointment dialog.
     </para>
    </tip> 
    <para>
     Next to the hours listing in the top right hand corner is a small full 
     month calendar. You may change the month or year of the small month 
     calendar by pressing the forward and backward arrows on the top. You may 
     use the small month calendar to navigate the days as well. Double clicking 
     on any day in the small month calendar will move the current day view to 
     that particular day.
    </para>
    <para>
     Below the small month calendar is your Todo list. The Todo list is a 
     simple list where you can keep all your tasks on hand. To add an item to 
     the Todo list press the <guibutton>Add</guibutton> button. This will 
     launch a small editing box where you can type in the item. Once you have 
     entered an item in the Todo list you may use the
     <guibutton>Edit</guibutton> and <guibutton>Delete</guibutton> to manage 
     your items. The Todo items are available no matter which days are displayed 
     in the Day View and can only be deleted with the 
     <guibutton>Delete</guibutton> button.
    </para>
   </sect2>
   <sect2 id="calweek">
    <title>The Week View</title>
    <para>
     The Week View shows the current week with detailed descriptions of your 
     appointments. If you would like to add an appointment for any of the days 
     in the week view you may right mouse click on the day and select the
     <guimenuitem>New appointment</guimenuitem> menu item from the 
     <guimenu>pop-up</guimenu> menu. You may also use the week view to navigate 
     to particular days in the Day View. Double-click on any day in the Week
     View and you will go to that day in the Day View.
    </para>
    <figure>
     <title>The Week View</title>
      <screenshot>
       <screeninfo>The Week View</screeninfo>
       <Graphic Format="gif" Fileref="images/calweek" srccredit="dcm">
       </graphic>
      </screenshot>
    </figure>
    <para>
     In the lower left corner of the Week View there is a small month calendar.
     You may change the month or year of the small month calendar by pressing 
     the forward and backward arrows on the top. You may use the small month 
     calendar to navigate the days as well. Double clicking on any day in the 
     small month calendar will move the current week view to that particular 
     week.
    </para>
   </sect2>
   <sect2 id="calmonth">
    <title>The Month View</title>
    <para>
     The Month View shows the entire month with brief detailed descriptions of
     your appointments. The Month View makes use of the customized colors 
     available in the Calendar. You may read about how to set these colors in
     <xref Linkend="calsetup">. For any day with a brief description of an 
     appointment you may click on the day to display a detailed description of 
     the appointment in a pop-up window. If you would like to add an appointment
     to a day in the Month View you may right mouse click on any day and select 
     the <guimenuitem>New Appointment in this day</guimenuitem> item from the
     <guimenu>pop-up</guimenu> menu. You may use the items in the
     <guimenu>pop-up</guimenu> menu to navigate in the Day, Week, and Year views
     by selecting either <guimenuitem>Jump to this day</guimenuitem>, 
     <guimenuitem>Jump to this week</guimenuitem>, or<guimenuitem>Jump to this 
     Year</guimenuitem>.
    </para>
    <figure>
     <title>The Month View</title>
      <screenshot>
       <screeninfo>The Month View</screeninfo>
       <Graphic Format="gif" Fileref="images/calmonth" srccredit="dcm">
       </graphic>
      </screenshot>
    </figure>
   </sect2>
   <sect2 id="calyear">
    <title>The Year View</title>
    <para>
     The Year View shows you the entire year with no descriptions of 
     appointments. Like the Month View, the Year View makes use of the 
     customized colors available in the Calendar. You may read about how to set
     these colors in <xref Linkend="calsetup">. If you have an appointment on a
     day you may click on that day and a description of the appointment will be
     displayed in the pop-up window. If you would like to add an appointment to
     a day in the Year View you may right mouse click on any day and  select the
     <guimenuitem>New Appointment in this day</guimenuitem> item from the 
     <guimenu>pop-up</guimenu> menu. You may use the items in the 
     <guimenu>pop-up</guimenu> menu to navigate in the Day, Week, and Month 
     views by selecting either <guimenuitem>Jump to this day</guimenuitem>, 
     <guimenuitem>Jump to this week</guimenuitem>, or <guimenuitem>Jump to this 
     Month</guimenuitem>.
    </para>
    <figure>
     <title>The Year View</title>
      <screenshot>
       <screeninfo>The Year View</screeninfo>
       <Graphic Format="gif" Fileref="images/calyear" srccredit="dcm">
       </graphic>
      </screenshot>
    </figure>
   </sect2>
  </sect1>
  <sect1 id="calappoint">
    <title>Making a New Appointment</title>
    <para>
     There are many methods for making a new appointment in the GNOME Calendar,
     the easiest is by pressing the <guibutton>New</guibutton> button on the 
     button bar. Whenever you make a new appointment you will launch the Create
     New Appointment dialog that allows you to set the properties of that
     appointment. The Create New Appointment dialog is broken into two 
     different tabs, the General and the Recurrence tabs.
    </para>
    <para>
     General - The General tab is the area in which you specify the time of the
     appointment and set reminders for yourself. There are four different areas
     on the General tab: Summary, Time, Alarms, and Classification.
     <ITEMIZEDLIST MARK="bullet">
      <listitem>
       <para>
        Summary - The Summary box allows you to type a description of the 
    appointment. Keep in mind that only a portion of this description will
    be available in the Week and Month Views.
       </para>
      </listitem>
      <listitem>
       <para>
        Time - The Time area allows you to set the time range for the
        appointment by selecting the date and hours. To the right of the start
        and end days there is a small selection box named Calendar. This will
    bring up a small Calendar when pressed. You may select the start and end
    date in the small calendar. To the right of the  start en end hours 
    there is a small button which will display the hours of the day when
        pressed. Each hour in the list will have a sub menu displaying each 
    quarter hour so you may select them. The hours are restricted to those
    included in the Day Range.
       </para>
      </listitem>
      <listitem>
       <para>
        Alarms - The Alarms area allows you to set up an alarm to remind you of
    an appointment. There are four different types of alarms you may use to
    remind yourself of appointments: Display, Audio, Program, and Mail. The
    Display alarm will display a message on your screen in the time you
    set. The Audio alarm will play an audio file at the time you set. The 
    Program alarm will run a program you specify at the time you set. The
    Mail alarm will send email to the user specified at the time you set.
       </para>
      </listitem>
     <!-- <listitem>
       <para>
        Classification - TO BE DONE
       </para>
      </listitem> -->
     </itemizedlist>
    </para>
    <para>
     Recurrence - The Recurrence tab allows you to specify how often an 
     appointment should recur, if at all. The first property you should set if 
     you want a recurring appointment is the Recurrence rule. You may choose 
     among None, Daily, Weekly, Monthly, and Yearly. For each selection you may
     adjust the recurrence properties for your selection. In the Ending date 
     area you may set a rule which will stop the recurrence of your appointment
     or allow it to repeat forever. In the Exceptions area you may make
     exceptions to the recurring appointment by double-clicking the date and
     pressing the <guibutton>Add</guibutton> button.
    </para>
   </sect1>
 </chapter>
</book>