Improve the documentation

lisp/org-taskjuggler.el

@@ -28,11 +28,18 @@
 
 ;; Commentary:
 ;;
-;; This library implements a TaskJuggler exporter for org-mode. It is
-;; a bit different from other exporters, such as the HTML and LaTeX
-;; exporters for example, in that it does not export all the nodes of
-;; a document or strictly follow the order of the nodes in the
-;; document.
+;; This library implements a TaskJuggler exporter for org-mode.
+;; TaskJuggler uses a text format to define projects, tasks and
+;; resources, so it is a natural fit for org-mode. It can produce all
+;; sorts of reports for tasks or resources in either HTML, CSV or PDF.
+;; The current version of TaskJuggler requires KDE but the next
+;; version is implemented in Ruby and should therefore run on any
+;; platform.
+;;
+;; The exporter is a bit different from other exporters, such as the
+;; HTML and LaTeX exporters for example, in that it does not export
+;; all the nodes of a document or strictly follow the order of the
+;; nodes in the document.
 ;;
 ;; Instead the TaskJuggler exporter looks for a tree that defines the
 ;; tasks and a optionally tree that defines the resources for this
@@ -54,21 +61,21 @@
 ;;
 ;; * Tasks
 ;;
-;; Let's illustrate this with a small example. Create your tasks as
-;; you usually do. Assign efforts to each task using properties (it's
-;; easiest to do this in the column view). You should end up with
-;; something similar to the example by Peter Jones in
+;; Let's illustrate the usage with a small example. Create your tasks
+;; as you usually do with org-mode. Assign efforts to each task using
+;; properties (it's easiest to do this in the column view). You should
+;; end up with something similar to the example by Peter Jones in
 ;; http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.
 ;; Now mark the top node of your tasks with a tag named
 ;; "taskjuggler_project" (or whatever you customized
 ;; `org-export-taskjuggler-project-tag' to). You are now ready to
 ;; export the project plan with `org-export-as-taskjuggler-and-open'
 ;; which will export the project plan and open a gant chart in
-;; TaskJugglerUI. 
+;; TaskJugglerUI.
 ;;
 ;; * Resources
 ;; 
-;; Next you can define resources and assign these to work on specific
+;; Next you can define resources and assign those to work on specific
 ;; tasks. You can group your resources hierarchically. Tag the top
 ;; node of the resources with "taskjuggler_resource" (or whatever you
 ;; customized `org-export-taskjuggler-resource-tag' to). You can
@@ -90,14 +97,14 @@
 ;;
 ;; The exporter also takes TODO state information into consideration,
 ;; i.e. if a task is marked as done it will have the corresponding
-;; attribute in TaskJuggler (complete 100). Also it will export any
+;; attribute in TaskJuggler ("complete 100"). Also it will export any
 ;; property on a task resource or resource node which is known to
 ;; TaskJuggler, such as limits, vacation, shift, booking, efficiency,
 ;; journalentry, rate for resources or account, start, note, duration,
 ;; end, journalentry, milestone, reference, responsible, scheduling,
 ;; etc for tasks.
 ;;
-;; * Dependecies
+;; * Dependencies
 ;; 
 ;; The exporter will handle dependencies that are defined in the tasks
 ;; either with the ORDERED attribute (see TODO dependencies in the Org
@@ -107,11 +114,15 @@
 ;; to an ID which is defined for another task in the project.
 ;;
 ;; * TODO
-;;   - Look at org-file-properties, org-global-properties and org-global-properties-fixed
+;;   - Look at org-file-properties, org-global-properties and
+;;     org-global-properties-fixed
 ;;   - What about property inheritance and org-property-inherit-p?
 ;;   - Use TYPE_TODO as an way to assign resources
 ;;   - Make sure multiple dependency definitions (i.e. BLOCKER on
-;;     previous-sibling and on a specific ID) in multiple attributes are properly exported.
+;;     previous-sibling and on a specific ID) in multiple attributes
+;;     are properly exported.
+;;   - Fix compiler warnings about reference and assignment to free
+;;     variable `old-level' in org-taskjuggler-close-maybe
 ;;
 ;;; Code: