Skip to content

Commit

Permalink
Try to make naming of components, properties etc more consistent
Browse files Browse the repository at this point in the history
  • Loading branch information
douglm committed Jul 29, 2024
1 parent 1d26502 commit bebca35
Show file tree
Hide file tree
Showing 6 changed files with 36 additions and 16 deletions.
17 changes: 13 additions & 4 deletions ical-tasks/sources/sections/06-architecture-foundations.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,18 @@

== Architecture Foundations

The key standards that enable interoperability between the logical elements of the
architecture are the Internet Calendaring and Scheduling Core Object Specification (iCalendar) <<RFC5545>>
and associated protocols. Task and task status are represented by the iCalendar "VTODO" calendar component. Protocols include, in particular, the iCalendar Transport-Independent Interoperability Protocol (iTIP) <<RFC5546>> for task assignment and scheduling, and Calendaring Extensions to WebDAV (CalDAV) <<RFC4791>> for client server communication.
The key standards that enable interoperability between the logical
elements of the architecture are the Internet Calendaring and
Scheduling Core Object Specification (iCalendar) <<RFC5545>>
and associated protocols. Task and task status are represented by the
"VTODO" calendar component. Protocols include, in particular, the
iCalendar Transport-Independent Interoperability Protocol
(iTIP) <<RFC5546>> for task assignment and scheduling, and
Calendaring Extensions to WebDAV (CalDAV) <<RFC4791>> for client
server communication.

Additionally, this specification uses definitions from
Support for iCalendar Relationships <<RFC9253>>. The LINK, REFID, RELATED-TO and CONCEPT properties enable context and a rich set of relationships between tasks and other iCalendar components to be specified.
Support for iCalendar Relationships <<RFC9253>>. The "LINK", "REFID",
"RELATED-TO" and "CONCEPT" properties enable context and a rich set
of relationships between tasks and other calendar components to be
specified.
22 changes: 15 additions & 7 deletions ical-tasks/sources/sections/08-task-specification.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@

== Task Specification

The specification of tasks must be semantically explicit in order for them to be managed within the context of a business process or project, and be understood by both humans and IT systems. The current VTODO component only provides for simple ad-hoc tasks or 'to do' lists, and is therefore extended by this specification as follows:
The specification of tasks must be semantically explicit in order for
them to be managed within the context of a business process or project,
and be understood by both humans and IT systems. The current
"VTODO" calendar component only provides for simple ad-hoc tasks or
'to do' lists, and is therefore extended by this specification as follows:

Task type:: explicitly what type of task is to be performed is identified.

Expand All @@ -15,7 +19,7 @@ Organizer and attendee:: recognizes that a task "Organizer" or "Attendee" can be

=== Task type

The <<RFC9253>> CONCEPT property is used to identify the type of task, for example;
The <<RFC9253>> "CONCEPT" property is used to identify the type of task, for example;

[source]
----
Expand All @@ -24,7 +28,7 @@ CONCEPT:http://example.com/task/delivery

=== Task Context and Relationships

The <<RFC9253>> LINK property specifies a link to external information, which may be context to the task. For example:
The <<RFC9253>> "LINK" property specifies a link to external information, which may be context to the task. For example:

[source]
----
Expand All @@ -35,7 +39,7 @@ LINK;LINKREL=describedby:mid:[email protected]

The external information may be data to be manipulated in performing the task. See <<task-specific-data>>.

The <<RFC9253>> REFID property is used to identify a key
The <<RFC9253>> "REFID" property is used to identify a key
used to group tasks by that key.

[source]
Expand All @@ -45,20 +49,24 @@ REFID:Manhattan
REFID:1234567890
----

Extensions to the RELATED-TO property defined in <<RFC9253>> allow temporal relationships between tasks as found in project management to be specified as well as parent/child relationships and dependencies (DEPENDS-ON). Tasks (VTODOs) may also be related to other calendar components; for example to a VEVENT to block time to perform a task.
Extensions to the "RELATED-TO" property defined in <<RFC9253>> allow temporal relationships
between tasks as found in project management to be specified as well as parent/child
relationships and dependencies (DEPENDS-ON). Tasks (VTODO calendar components) may also be related to other
calendar components; for example to a "VEVENT" calendar component to block time to perform a task.

[[task-specific-data]]
=== Task Specific Data

The LINK property can be used to relate a domain specific service to the task. For example, it might be a URI pointing to a web page where the status of the task can be directly manipulated.
The "LINK" property can be used to relate a domain specific service to the task. For example, it might be a URI pointing to a web page where the status of the task can be directly manipulated.

[source]
----
LINK;LINKREL="vacation-system";VALUE=URI:
http://example.com/vacation-approval?id=1234
----

Additionally, it might be used to link data specific to the task, for example an electronic copy of a signature taken to confirm delivery of a package.
Additionally, it might be used to link data specific to the task, for example an electronic copy
of a signature taken to confirm delivery of a package.

[source]
----
Expand Down
5 changes: 4 additions & 1 deletion ical-tasks/sources/sections/09-deadlines.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,7 @@ visualize when tasks should be performed and allocate
time to them.

=== Milestones
A task that has intermediary deadlines (i.e., milestones) SHOULD be expressed by child VTODO components (i.e., sub-tasks associated with each of the milestones) in conjunction with the RELATED-TO property to relate the parent and child tasks.
A task that has intermediary deadlines (i.e., milestones) SHOULD be
expressed by child "VTODO" calendar component (i.e., sub-tasks
associated with each of the milestones) in conjunction with the
"RELATED-TO" property to relate the parent and child tasks.
2 changes: 1 addition & 1 deletion ical-tasks/sources/sections/51-new-parameter-values.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

Participant status parameter type values are defined in
<<RFC5545,section=3.2.12>>. This specification redefines that type
to include the new value FAILED for "VTODO" iCalendar components.
to include the new value FAILED for "VTODO" calendar components.

Format Definition:: This property parameter is extended by the following notation:

Expand Down
4 changes: 2 additions & 2 deletions ical-tasks/sources/sections/53-property-extensions.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ is replaced by
; MUST NOT occur in the same 'todoprop'.
----

This allows a VTODO to only have a DURATION property.
This allows a "VTODO" calendar component to only have a "DURATION" property.

Furthermore, the following text:

Expand All @@ -53,7 +53,7 @@ is replaced by

The Status property is defined in <<RFC5545, section=3.8.1.11>>. This
specification extends that property to include new values
associated with VTODO iCalendar components (See Appendix A for
associated with "VTODO" calendar components (See Appendix A for
examples of the task state lifecycle).

Format Definition:: The "STATUS" property parameter list is augmented
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Example of status changes in assigning and performing a task with two attendees

|===

NOTE: The logic for determining the status change to the VTODO calendar component
NOTE: The logic for determining the status change to the "VTODO" calendar component
is determined by the task organizer based on the "ATTENDEE" property status and other business logic.

=== Example of Failure
Expand Down

0 comments on commit bebca35

Please sign in to comment.