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</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 and Colors, and Todo list
   </para>
   <para>
   Time - This tab is broken up into three main sections: Time format, Weeks
   start on, and Time 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 To-do 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 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 and 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 at 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>