Document Calendar imports

Summary:
Ref T10747.

  - Adds import documentation.
  - Adds import/export docs to the help menu.
  - Removes some weird/old/out-of-date information from the general user guide, which I'll rewrite later.

Test Plan: Read documentation somewhat thoroughly.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T10747

Differential Revision: https://secure.phabricator.com/D16766

src/applications/calendar/application/PhabricatorCalendarApplication.php

@@ -104,6 +104,16 @@ final class PhabricatorCalendarApplication extends PhabricatorApplication {
         'name' => pht('Calendar User Guide'),
         'href' => PhabricatorEnv::getDoclink('Calendar User Guide'),
       ),
+      array(
+        'name' => pht('Importing Events'),
+        'href' => PhabricatorEnv::getDoclink(
+          'Calendar User Guide: Importing Events'),
+      ),
+      array(
+        'name' => pht('Exporting Events'),
+        'href' => PhabricatorEnv::getDoclink(
+          'Calendar User Guide: Exporting Events'),
+      ),
     );
   }
 

src/docs/user/userguide/calendar.diviner

@@ -9,75 +9,11 @@ Overview
 IMPORTANT: Calendar is a prototype application. See
 @{article:User Guide: Prototype Applications}.
 
-The Calendar application is a tool that allows users to schedule group events
-and share personal plans.
 
-There are several kinds of events you can create:
+Next Steps
+==========
 
-- Regular events such as a one-time meeting or a personal appointment.
+Continue by:
-- All day events such as a company-wide holiday or a vacation.
-- Recurring events, which can be regular or all day, such as a weekly 1-1 or
-  a birthday.
 
-
+  - importing events with @{article:Calendar User Guide: Importing Events}; or
-Editing Events
+  - exporting events with @{article:Calendar User Guide: Exporting Events}.
-==============
-
-All fields of basic and all day events can be edited after the event has been
-created.
-
-Every instance of a recurring event has an index that maintains its place in
-the sequence order. Before an instance of a recurring event is edited, it is
-considered a ghost event, or a placeholder. This means that there is no
-database entry for that instance. Rather, when querying for events, if a
-recurring series of events overlaps with the query range, instance
-placeholders of that recurring event are generated and are displayed for
-that range. If a placeholder instance of a recurring event is edited, a real
-entry in the database is created and all changes are saved. When that
-instance falls within a query range, the real instance event replaces the
-old placeholder instance.
-
-To prevent disordering of the recurring sequence of events, parent recurring
-events do not allow editing of date-related fields like recurrence frequency
-and recurrence start and end dates. If all instances of the recurring event
-need to be rescheduled, users are encouraged to cancel a recurring event and
-create a new recurring event with the revised date and time.
-
-
-Cancelling Events
-=================
-
-Cancelling basic events will hide that event from most of the builtin Calendar
-queries, unless the query specifies to display cancelled events.
-
-There are two ways to cancel an instance of a recurring event.
-
-- Cancel an instance of a recurring event.
-- Cancel the entire series of a recurring event.
-
-Cancelling a placeholder instance of a recurring event will create a real
-cancelled event that will replace the placeholder instance. Consequently,
-the cancellation status of that instance of the recurring event will
-persist if the parent event is cancelled and subsequently reinstated.
-
-When an entire series of a recurring event is cancelled, all the placeholder
-and real instances are also cancelled. An entire series can similarly be
-reinstated, but it is currently not possible to reinstate an instance of a
-cancelled recurring event series. To reinstate that instance, the entire
-series must be reinstated. If an instance of a recurring event has been
-cancelled, then the entire recurring event series is also cancelled,
-reinstating the series will not reinstate the previously cancelled instances
-of that event.
-
-
-Commenting On Recurring Events
-==============================
-
-If a placeholder instance of a recurring event has not been converted to a
-real instance of the series as a result of editing or cancelling, commenting on
-that placeholder instance does not currently save a draft for that instance
-only. The draft is saved for the recurring event parent, so the parent
-recurring event and all placeholder instances will show that draft. When a
-comment is actually added to a placeholder instance, the instance is converted
-to a recurrence exception, and the comment will only appear on that instance
-of the recurring event.

src/docs/user/userguide/calendar_imports.diviner

@@ -0,0 +1,132 @@
+@title Calendar User Guide: Importing Events
+@group userguide
+
+Importing events from other calendars.
+
+Overview
+========
+
+IMPORTANT: Calendar is a prototype application. See
+@{article:User Guide: Prototype Applications}.
+
+You can import events into Phabricator to other calendar applications or from
+`.ics` files. This document will guide you through how to importe event data
+into Phabricator.
+
+When you import events from another application, they can not be edited in
+Phabricator. Importing events allows you to share events or keep track of
+events from different sources, but does not let you edit events from other
+applications in Phabricator.
+
+
+Import Policies
+===============
+
+When you import events, you select a visibility policy for the import. By
+default, imported events are only visible to you (the user importing them).
+
+To share imported events with other users, make the import **Visible To**
+a wider set of users, like "All Users".
+
+
+Importing `.ics` Files
+======================
+
+`.ics` files contain information about events, usually either about a single
+event or an entire event calendar.
+
+If you have an event or calendar in `.ics` format, you can import it into
+Phabricator in two ways:
+
+  - Navigate to {nav Calendar > Imports > Import Events > Import .ics File}.
+  - Drag and drop the file onto a Calendar.
+
+This will create a copy of the event in Phabricator.
+
+If you want to update an imported event later, just repeat this process. The
+event will be updated with the latest information.
+
+Many applications send `.ics` files as email attachments. You can import these
+into Phabricator.
+
+
+.ics Files: Google Calendar
+===========================
+
+In **Google Calendar**, you can generate a `.ics` file for a calendar by
+clicking the dropdown menu next to the calendar and selecting
+{nav Calendar Settings > Export Calendar > Export this calendar}.
+
+
+.ics Files: Calendar.app
+========================
+
+In **Calendar.app**, you can generate an `.ics` file for a calendar by
+selecting the calendar, then selecting {nav File > Export > Export...} and
+saving the calendar as a `.ics` file.
+
+You can also convert an individual event into an `.ics` file by dragging it
+from the calendar to your desktop (or any other folder).
+
+When you import an event using an `.ics` file, Phabricator can not
+automatically keep the event up to date. You'll need to repeat the process if
+there are changes to the event or calendar later, so Phabricator can learn
+about the updates.
+
+
+Importing .ics URIs
+=====================
+
+If you have a calendar in another application that supports publishing a
+`.ics` URI, you can subscribe to it in Phabricator. This will import the entire
+calendar, and can be configured to automatically keep it up to date and in sync
+with the external calendar.
+
+First, find the subscription URI for the calendar you want to import (see
+below for some guidance on popular calendar applications). Then, browse to
+{nav Calendar > Imports > Import Events > Import .ics URI}.
+
+When you import a URI, you can choose to enable automatic updates. If you do,
+Phabricator will periodically update the events it imports from this source.
+You can stop this later by turning off the automatic updates or disabling
+the import.
+
+{icon lock} **Privacy Note**: When you import via URI, the URI often contains
+sensitive information (like a username, password, or secret key) which allows
+anyone who knows it to access private details about events. Anyone who can edit
+the import will also be able to view and edit the URI, so make sure you don't
+grant edit access to users who should not have access to the event details.
+
+
+.ics URIs: Google Calendar
+==========================
+
+In **Google Calendar**, you can get the subscription URI for a calendar
+by selecting {nav Calendar Settings} from the dropdown next to the calendar,
+then copying the URL from the {nav ICAL} link under **Private Address**. This
+URI provides access to all event details, including private information.
+
+You may need to adjust the sharing and visibility settings for the calendar
+before this option is available.
+
+Alternatively, you can use the URI from the {nav ICAL} link under
+**Calendar Address** to access a more limited set of event details. You can
+configure which details are available by configuring how the calendar is
+shared.
+
+
+.ics URIs: Calendar.app
+=======================
+
+**Calendar.app** does not support subscriptions via `.ics` URIs.
+
+You can export a calendar as an `.ics` file by following the steps above, but
+Phabricator can not automatically keep events imported in this way up to date.
+
+
+Next Steps
+==========
+
+Continue by:
+
+  - returning to the @{article:Calendar User Guide}.