taskjuggler 0.0.2

data/manual/Installation

@@ -0,0 +1,68 @@
+== Installation ==
+
+TaskJuggler III is written in [http://www.ruby-lang.org Ruby]. It
+should run on any platform that Ruby is available on. It uses the
+standard Ruby mechanism for distribution. The package format is called
+[http://docs.rubygems.org Ruby Gems]. Alternatively, you can install
+from a the source code using ''''setup.rb''''.
+
+This is a prototype. Consider it being alpha quality at best!
+
+=== Requirements ===
+
+Ruby applications are platform independent. There is no need to
+compile anything. But TaskJuggler has a very small set of
+dependencies that you have to take care of first. Please make sure you
+have the minimum required version installed.
+
+* ''Ruby'' TaskJuggler III is written in Ruby.  You need a Ruby
+runtime environment to run it. This can be downloaded from
+[http://www.ruby-lang.org/en/downloads/ here].  Most Linux
+distributions usually have Ruby already included. So does MacOS X
+Leopard. For Windows, there is a one-click installer available.
+TaskJuggler currently needs at least Ruby version 1.8.5.
+
+* ''RubyGems'' If it did not come with your OS or Ruby package, see
+[http://docs.rubygems.org here] how to get and install it.
+
+* ''TaskJuggler'' Get TaskJuggler III from the
+[http://www.taskjuggler.org/download.php Download Page].
+
+=== Installation Process ===
+
+If you have downloaded the gem package, you can skip to the next
+paragraph.  If you have checked-out the git repository, you need to
+build the Gem package first. Make sure, you have removed all other
+instances of TaskJuggler from you system before doing so. It is a
+common mistake to have an old version of the TaskJuggler installed and
+then use parts of the old and new version together.
+
+In addition to the above listed dependencies, you need to have the
+following packages installed:
+
+* [http://rake.rubyforge.org Rake] The Ruby build tool.
+
+* [http://eigenclass.org/hiki.rb?rcov rcov] The rcov code
+coverage analysis tool.
+
+The following command will create an archive file called a gem
+package.
+
+ cd taskjuggler3; rake gem
+ 
+A gem package is an operating system and architecture independent
+archive file for Ruby programs. You can install it on any system that
+has Ruby and ruby-gems installed.  Normally, you should be logged-in
+as root or administrator to run the following installation command.
+
+ gem install pkg/taskjuggler-X.X.X.gem 
+
+It will install all components of the Gem in the appropriate place.
+
+=== Update from previous versions ===
+
+Updates work just like the installation.
+
+ gem update pkg/taskjuggler-X.X.X.gem
+
+

data/manual/Intro

@@ -0,0 +1,102 @@
+== Introduction ==
+
+=== About TaskJuggler ===
+
+TaskJuggler is a modern and powerful project management tool. Its new
+approach to project planning and tracking is far superior to the
+commonly used Gantt chart editing tools. It has already been
+successfully used in many projects and scales easily to projects with
+hundreds of resources and thousands of tasks.
+
+TaskJuggler is an Open Source tool for serious project managers. It
+covers the complete spectrum of project management tasks from the
+first idea to the completion of the project. It assists you during
+project scoping, resource assignment, cost and revenue planning, risk
+and communication management.
+
+TaskJuggler provides an optimizing scheduler that computes your
+project time lines and resource assignments based on the project
+outline and the constrains that you have provided. The built-in
+resource balancer and consistency checker offload you from having to
+worry about irrelevant details and ring the alarm if the project gets
+out of hand. Its flexible "as many details as necessary"-approach
+allows you to still plan your project as you go, making it also ideal
+for new management strategies such as Extreme Programming and Agile
+Project Management.
+
+If you are about to build a skyscraper or just want to put together
+your colleague's shift plan for the next month, TaskJuggler is the
+right tool for you. If you just want to draw nice looking Gantt
+charts to impress your boss or your investors, TaskJuggler might not
+be right for you. It takes some effort to master its power, but it
+will become a companion you don't want to miss anymore.
+
+=== About TaskJuggler III ===
+
+TaskJuggler III is the completely re-implemented version of the TaskJuggler
+2.x series. It is currently still in the development stage. It
+already is mostly stable and feature complete, but not yet recommended
+for any serious work. The code base is still in active development
+and the quality and reliability may change daily. You are welcome to try
+it and play with it, but expect it to fail.
+
+TaskJuggler is a commandline tool that you use from a
+[http://en.wikipedia.org/wiki/Shell_(computing) shell]. This does not
+mean that you don't get fancy looking Gantt-charts. It just means
+that for entering your project data you will use one of the most
+versatile and powerful tools there is: your favorite
+[http://en.wikipedia.org/wiki/Text_editor text editor]. To get a
+first impression, you can look at this
+[http://www.taskjuggler.org/tj3/examples/tutorial.tjp project file]. The
+project description is fairly intuitive, but very powerful as well.
+The [[Tutorial]] will explain this file line by line. Please look at
+the [http://www.taskjuggler.org/tj3/examples/ProjectPlanOverview.html
+resulting reports] that visualize the project.
+
+
+=== License and Copyright ===
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of
+[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html version 2 of
+the GNU General Public License] as published by the Free Software
+Foundation. You accept the terms of this license by distributing or
+using this software.
+
+This manual is Copyright (C) 2006, 2007, 2008, 2009 Chris Schlaeger.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation; with
+no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+=== Features and Highlights ===
+
+* Manages tasks, resources and costs in one package
+* Automatic resource leveling and tasks conflict resolution
+* Flexible working hours and vacation handling
+* Multiple timezone support
+* Support for shift working
+* Project tracking and status reporting
+* Unlimited number of scenarios (baselines) of same project for what-if
+analysis
+* CSV data export for exchange with popular office software
+* Project breakdown and management team support
+* Powerful and flexible filtering functions to provide the right
+amount of detail to the right audience
+* Tasks may have initial costs, finishing costs and run rates
+* Resources may have running costs
+* Support for profit/loss analysis
+* Powerful project description syntax with macro support
+
+=== TaskJuggler on the Web ===
+
+The official TaskJuggler web site can be found at
+[http://www.taskjuggler.org].
+
+Since the developers are mostly busy project managers themselves, we
+have created a [http://www.taskjuggler.org/FUDforum2 forum] for users
+to help each other.
+

data/manual/Reporting_Bugs

@@ -0,0 +1,26 @@
+=== Reporting Bugs and Sending Feedback ===
+
+All official releases of TaskJuggler are meant to be stable releases
+unless explicitly noted differently. But our test suite is still very
+small and some features are not tested at all. So it's very likely
+that your current version of TaskJuggler contains some bugs. If you
+find a bug, please follow this procedure:
+
+* Read this manual to make sure that it is actually a bug and not a
+feature.
+
+* Check the [http://www.taskjuggler.org TaskJuggler web page] and the
+[http://www.taskjuggler.org/FUDforum2 Discussion Forum].
+
+* Possibly the bug was already found
+and a patch or workaround exists.
+
+* Try to create a test project that is as small as possible but still
+reproduces the bug.
+
+* Send the test project and a detailed description of the problem to
+the [http://www.taskjuggler.org/FUDforum2 TaskJuggler Developer
+Forum].  Not sending a test project is the most common mistake when
+reporting bugs. This usually triggers requests or leads to bug reports
+being ignored.
+

data/manual/Rich_Text_Attributes

@@ -0,0 +1,90 @@
+=== Rich Text Attributes ===
+
+TaskJuggler supports Rich Text data for some STRING attributes that
+are marked accordingly in the syntax reference. Rich Text means, that
+you can use certain markup symbols to structure the text into
+sections, include headlines, bullet lists and the like. The following
+sections describe the supported markup elements and how to use them.
+
+The markup syntax is mostly compatible to the syntax used by the
+popular [http://www.mediawiki.org MediaWiki].
+
+==== Block Markups ====
+
+All block markups are delimited by an empty line. The markup must
+always start at the beginning of the first line of the block. Block
+markups cannot be nested.
+
+The simplest form of a block is a paragraph. It's a block of text
+that is separated by empty lines from other blocks. There is no
+markup needed to start a text block.
+
+Headlines can be inserted by using ''''='''' characters to start a
+line. There are 3 level of headlines.
+
+ == Headline Level 1 ==
+ === Headline Level 2 ===
+ ==== Headline Level 3 ====
+
+A line that starts with four dashes creates a horizontal line.
+
+ ----
+
+Items of a bullet list start with a star. The number of stars
+determines the bullet list level of the item. Three levels are
+supported. Bullet items may span multiple lines but cannot contain
+paragraphs.
+
+ * Bullet 1
+ ** Bullet 2
+ *** Bullet 3
+
+Enumerated lists are formed by using a ''''#'''' instead of ''''*''''.
+
+ # Enumeration Level 1
+ ## Enumeration Level 2
+ ### Enumeration Level 3
+
+Sections of lines that start with a space character are interpreted
+as pre-formatted text. The formatting will be preserved by using a
+fixed-width font and by not interpreting any markup characters within
+the text.
+
+  Preformatted text start with
+  a single space at the start of 
+  each line.
+
+==== In-Line Markups ====
+
+In-line markups may occur within a text block. They don't have to
+start at the start of the line.
+
+ This is an ''italic'' word.
+ This is a '''bold''' word.
+ This is a ''''monospaced'''' word.
+ This is a '''''italic and bold''''' word.
+
+The monospace format is not part of the original MediaWiki markup, but
+we found it useful to have for this manual.
+
+Links to external documents are possible as well. In the first form,
+the URL will appear in the readable text as well. In the second form,
+the text after the URL will be visible but the link will be available
+if the output format supports it.
+
+ [http://www.taskjuggler.org]
+ [http://www.taskjuggler.org The TaskJuggler Web Site]
+
+For local references, the second form is available as well. In this
+form, ''''.html'''' is appended to the first word in the reference to
+create the URL.
+
+ [[item]]
+ [[item An item]]
+
+In some situations, it is desirable to not interpret certain markup
+sequences and reproduce the text verbatim. Such text must be enclosed
+in nowiki tags.
+
+ <nowiki> This is not '''bold''' text. </nowiki>
+

data/manual/TaskJuggler_2x_Migration

@@ -0,0 +1,40 @@
+=== TaskJuggler 2.x Migration ===
+
+This section will cover changes between TaskJuggler 2.x and 3.x.
+
+* The ''''shift'''' attribute for tasks and resources has been
+renamed to ''''shifts'''' to allow support for multiple shifts.
+
+* The global ''''limits'''' attribute has been removed. Since both
+tasks and resources have a ''''limits'''' attribute, a global
+attribute was inconsistent as only resources inherited this
+attribute. Use a parent resource to emulate the old behaviour.
+
+* The ''''startbuffer'''' and ''''endbuffer'''' attributes have been
+deprecated. They have not been widely used and had no impact on
+scheduling.
+
+* The ''''barlabels'''' attribute for reports is no longer needed.
+HTML reports have always empty Gantt-chart bars and the calendar
+reports always have values.
+
+* The project attribute ''''allowredifinitions'''' has been dropped.
+It was an ugly workaround for a rare corner case. Using [[supplement]] is
+the clean way to do this.
+
+* Camel case names for function names in logical expressions have
+been deprecated. Function names need to be all lower case now.
+
+* Top-level accounts no longer need a ''''cost'''' or ''''revenue''''
+attribute. Any two top level accounts can now be balanced against
+each other using the [[balance]] attribute in the report.
+
+* The sorting modes have been extended to include the scenario. Also,
+the sorting direction is no longer mangled with the attribute name.
+What used to be ''''startup'''' is now ''''plan.start.up''''. See
+[[sorttasks]] or [[sortresources]] for details.
+
+* The attribute ''''properties'''' for ''''export'''' reports is no
+longer supported. The naming was inconsistent with TaskJuggler lingo
+and did not handle tasks and resources separately. It has been
+replaced with [[taskattributes]] and [[resourceattributes]].

data/manual/Tutorial

@@ -0,0 +1,579 @@
+== The Tutorial: Your first Project ==
+
+We have mentioned already that TaskJuggler uses plain text files that
+describe the project to schedule it. As you will see now, the syntax
+of these files is easy to understand and very intuitive. This chapter
+will walk you step by step through your first project. You create the
+project plan for a made-up accounting software project. This project
+demonstrates some of the commonly used features of TaskJuggler. The
+complete example can be downloaded
+[http://www.taskjuggler.org/tj3/examples/tutorial.tjp here]. The
+resulting reports can be found
+[http://www.taskjuggler.org/tj3/examples/ProjectPlanOverview.html
+here].
+
+=== Starting the project ===
+
+To start a TaskJuggler project file you need to use the [[project]]
+property. It tells TaskJuggler the default project ID, a short name
+for your project, a version number and a start and end date. The start
+and end dates don't need to be exact, but must fit all tasks of the
+project.  It is the time interval the TaskJuggler scheduler will use
+to fit the tasks in. So, make it large enough for all your tasks to
+fit in. But don't make it too large, because this will result in
+longer scheduling times and higher memory consumption.
+
+[[example:tutorial header1]]
+
+All TaskJuggler properties have a certain number of fixed attributes
+and a set of optional attributes. Optional attributes are always
+enclosed in curly braces. If no optional attributes are specified,
+the braces can be omitted as well. In this example we will introduce
+a number of there attributes that may or may not matter to you. If
+you don't see an immediate need for a specific attribute, feel free
+to ignore it for now. You can always come back to them later. A full
+list of the supported attributes can be found in the ''attributes''
+section of the [[project]] property documentation.
+
+Attributes always start with a keyword that is unique in the context.
+A context is delimited by a set of curly braces that enclose optional
+attributes of a property. The area between properties is called the
+global scope.  Usually, attributes have one or more arguments. These
+arguments can be dates, character strings, numbers or symbols. Strings
+must be enclosed in single or double quotes. The argument types and
+meaning is explained for each keyword in the syntax reference section
+of this manual.
+
+The [[currency]] attribute specifies the unit of currency values.
+
+[[example:tutorial currency]]
+
+Because each culture has its own way of specifying dates and numbers,
+the format for these are configurable.  Use the [[timeformat]]
+attribute to specify the default format for dates. This format is used
+for reports, it does not affect the way you specify dates in the
+project files. Here you always need to use the [[date ISO standardized
+notation]].
+
+[[example:tutorial formats]]
+
+We also can specify the way numbers or currency values are shown in
+the reports. Use the [[numberformat]] and [[currencyformat]]
+attributes for this.
+
+The optional attribute [[now]] is used to set the current day for the
+scheduler to another value than to the moment your invoke TaskJuggler.
+When this attribute is not present, TaskJuggler will use the current
+moment of time to determine where you are with your tasks. To get a
+defined result for the reports in this example we've picked a specific
+date that fits our purpose here. In your projects, you would use
+[[now]] to generate status reports for the date you specify.
+
+[[example:tutorial now]]
+
+In this tutorial we would like to compare two scenarios of the
+project. The first scenario is the one that we have planned. The
+second scenario is how it really happened. The two scenarios have the
+same task structure, but the start and end dates of the task may vary.
+In reality we assume that the project got delayed, so we call the
+second scenario "Delayed". The scenario property is used to specify
+the scenarios. The delayed scenario is nested into the plan scenario.
+This tells TaskJuggler to use all values from the plan scenario also
+for the second scenario unless the second scenario has it's own
+values. This is a very easy but also powerful way to analyze the
+impact of certain changes to the plan of record.  We'll see further
+below, how to specify values for a scenario and how to compare the
+results.
+
+[[example:tutorial scenario]]
+
+To summarize the above, let's look at the complete header again.
+Don't get scared by the wealth of attributes here. They are all
+optional and mostly used to illustrate the flexibility of TaskJuggler.
+
+[[example:tutorial header2]]
+
+=== Global Attributes ===
+
+For this tutorial, we also like to do a simple profit and loss
+analysis of the project. We will track labor cost versus customer
+payments. To calculate the labor costs we have to specify the default
+daily costs of an employee. This can be changed for certain employees
+later, but it illustrates an important concept of TaskJuggler –
+inheritance of attributes. In order to reduce the size of the
+TaskJuggler project file to a readable minimum, properties inherit
+many optional attributes from their enclosing scopes. We'll see
+further below, what this actually means. Right after the project
+property we are at top-level scope, so this is the default for all
+following properties.
+
+[[example:tutorial rate]]
+
+The [[rate]] attribute can be used to specify the daily costs of
+resources. All subsequent resources will get this rate. But it can be
+changed to a different rate at group or individual resource level.
+
+You may also want to tell TaskJuggler about holidays that affect
+all resources. Global vacations are time periods where TaskJuggler
+does not do any resource assignments to tasks.
+
+[[example:tutorial vacation]]
+
+Use the [[vacation]] attribute to define a global vacation. Global
+vacations must have a name and a date or date range. This is slightly
+different from vacations of individual resources. They are defined
+with the [[vacation.resource vacation attribute for resources]] where
+the name is optional. The vacation name is purely for documentation
+purposes.
+
+=== Macros ===
+
+Macros are another TaskJuggler feature to keep project files small.
+Macros are text patterns that can be defined once and inserted
+multiple times in the project file. A [[macro]] always has a name and the
+text pattern is enclosed by square brackets. 
+
+[[example:tutorial macro]]
+
+To use the macro you simply have to write
+''''${allocate_developers}'''' and TaskJuggler will replace the term
+''''${allocate_developers}'''' with the pattern. We will use this
+macro further below in the example and then explain the meaning of the
+pattern.
+
+=== Declaring Flags ===
+
+A TaskJuggler feature that you will probably make heavy use of is
+flags. Once declared you can attach them to many properties. When you
+generate reports of the TaskJuggler results, you can use the flags to
+filter out information and limit the report to exactly those details
+that you want to have included.
+
+[[example:tutorial flags]]
+
+This is flag declaration. All [[flags]] need to be declared, before they
+can be used to avoid hard to find errors due to misspelled flag
+names. The flags should be declared shortly below the project header.
+We will see further down, how we can make use of these flags.
+
+=== Declaring Accounts ===
+
+The use of our resources will create costs. For a profit and loss
+analysis, we need to balance the costs against the customer payments.
+In order not to get lost with all the various amounts, we declare 3
+[[account accounts]] to credit the amounts to. We create one account
+for the development costs, one for the documentation costs, and one
+for the customer payments.
+
+[[example:tutorial accounts]]
+
+Like all TaskJuggler properties, the account needs an ID and a name.
+IDs may only consist of ASCII characters, numbers and the underline
+character. All global TaskJuggler properties have IDs. The ID is
+necessary so that we can reference the property again later without
+having to write the potentially much longer name. The name may
+contain space characters and therefore has to be enclosed with single
+or double quotes.
+
+Accounts can be grouped by nesting them. You can use this feature to
+create sets of accounts. Such sets can then be balanced against each
+other to create a profit and loss analysis. When you have specified
+accounts in your project, you must at least define one default
+[[balance]].
+
+[[example:tutorial balance]]
+
+=== Declaring Resources ===
+
+While the above introduced account property is only needed if you
+want to do a P&L analysis, resources are usually found in almost any
+project.
+
+[[example:tutorial resources]]
+
+This snippet of the example shows the use of the [[resource
+resource property]]. Just like accounts, resources always have an ID
+and a Name. These IDs also need to be unique within their property
+class.  Names are strings and as such enclosed in double quotes. As
+you can see, resource properties can be nested: ''''dev'''' is a group
+or container resource, a team that consists of three other resources.
+
+''''dev1'''', alias Paul Smith, costs more than the normal employee.
+So the declaration of ''''dev1'''' overwrites the inherited default
+rate with a higher value.
+
+The default value has been inherited from the enclosing scope,
+resource ''''dev'''', which in turn has inherited it from the global
+scope.  The declaration of the resource Klaus Müller uses another
+optional attribute. With vacation you can specify a certain time
+interval where the resource is not available. Vacations are list
+attributes. They accumulate the declarations. If you want to get rid
+of inherited values, you can use the [[purge]] attribute to clear the
+list.
+
+It is important that you understand how TaskJuggler handles time
+intervals.  Internally, TaskJuggler uses the number of seconds after
+January 1st, 1970 to store any date.  So all dates are actually stored
+with an accuracy of 1 second in UTC time. ''''2002-02-01'''' specifies
+midnight February 1st, 2002. Following the TaskJuggler concept of
+requiring as little information as necessary and extending the rest
+with sensible defaults, TaskJuggler adds the time 0:00:00 if nothing
+else has been specified. So the vacation ends on midnight February
+5th, 2002. Well, almost. Every time you specify a time interval, the
+end date is not included in the interval. So Klaus Müller's vacation
+ends exactly at 0:00:00 on February 4th, 2002.
+
+Peter Murphy only works 6.4 hours a day. So we use the
+[[limits.resource limits]] attribute to limit his daily working hours.
+We could also define exact working hours using the [[shift shift
+property]], but we ignore this for now.
+
+Note that we have attached the flag team after the declaration of the
+sub-resources to the team resources.  This way, these flags don't get
+passed down to the sub-resources. If we would have declared the flags
+before the sub-resources, then they would have the flags attached as
+well.
+
+=== Specifying the Tasks ===
+
+Let's focus on the real work now. The project should solve a problem:
+the creation of an accounting software. Because the job is quite
+complicated, we break it down into several subtasks. We need to do a
+specification, develop the software, test the software, and write a
+manual. Using the [[task task property]], thiis would look as follows:
+
+[[example:tutorial task1]]
+
+Similar to resources, tasks are declared by using the task keyword
+followed by an ID and a name string. All TaskJuggler properties have
+their own namespaces. This means, that it is quite OK to have a
+resource and a task with the same ID. Tasks may have optional
+attributes which can be tasks again, so tasks can be nested. In
+contrast to all other TaskJuggler properties, task IDs inherit the ID
+of the enclosing task as a prefix to the ID. The full ID of the spec
+task is AcSo.spec. You need to use this absolute ID when you want to
+reference the task later on. This hierarchical name space for tasks
+was chosen to support large projects where multiple project managers
+may use the same ID in different sub tasks.
+
+To track important milestones of the project, we also added a task
+called Milestones. This task, like most of the other tasks will get
+some subtasks later on.
+
+We consider the specification task simple enough, so we don't have to
+break it into further subtasks. So let's add some more details to it.
+
+[[example:tutorial spec]]
+
+The [[effort]] to complete the task is specified with 20 man-days.
+Alternatively we could have used the [[length]] attribute or
+the [[duration]] attribute. ''''length'''' specifies the
+duration of the task in working days while ''''duration'''' specifies
+the duration in calendar days.  Contrary to ''''effort'''', these two don't
+have to have a specification of the involved resources. Since
+''''effort'''' specifies the duration in man-days, we need to say who
+should be allocated to the task. The task won't finish before the
+resources could be allocated long enough to reach the specified
+effort. Tasks with ''''length'''' or ''''duration'''' criteria and
+allocated resources will last exactly as long as requested. Resources
+will be allocated only if available. It's possible that such a tasks
+ends up with no allocations at all since the resources are always
+assigned to other tasks for that period. Each task can only have one
+of the three duration criteria. Container tasks may never have a
+duration specification. They are automatically adjusted to fit all
+sub tasks.
+
+Here we use the allocate_developers macro mentioned above. The
+expression ''''${allocate_developers}'''' is simply expanded to 
+
+[[example:tutorial expandedmacro]]
+
+If you need to [[allocate]] the same bunch of people to several tasks,
+the macro saves you some typing. You could have written the allocate
+attributes directly instead of using the macro. Since the allocation
+of multiple resources to a task is a very common place for macro
+usage, we found it a good idea to use it in this example as well.
+
+One more interesting thing to note is the fact that we like the
+resource ''''dev2'''' only to work 4 hours each day on this task, so
+we use the optional attribute [[limits.resource]] to specify this.
+
+For TaskJuggler to schedule a task, it needs to know either the start
+and end criteria of a task, or one of them and a duration
+specification. The start and end criteria can either be fixed dates or
+relative dates. Relative dates are specifications of the type ''task B
+starts after task A has finished''. Or in other words, task B depends
+on task A. In this example the spec task depends on a subtasks of the
+deliveries task. We have not specified it yet, but it has the local ID
+start.
+
+To specify the dependency between the two tasks, we use the
+[[depends]] attribute. This attribute must be followed by one or more
+task IDs. If more than one ID is specified, each ID has to be
+separated with a comma from the previous one. Task IDs can be either
+absolute IDs or relative IDs. An absolute ID of a task is the ID of
+this task prepended by the IDs of all enclosing tasks. The task IDs
+are separated by a dot from each other. The absolute ID of the
+specification task would be ''''AcSo.spec''''.
+
+Relative IDs always start with one or more exclamation marks. Each
+exclamation mark moves the scope to the next enclosing task. So
+''''!deliveries.start'''' is expanded to ''''AcSo.deliveries.start''''
+since ''''AcSo'''' is the enclosing task of deliveries. Relative task
+IDs are a little bit confusing at first, but have a real advantage
+over absolute IDs.  Sooner or later you want to move tasks around in
+your project and then it's a lot less likely that you have to fix
+dependency specifications of relative IDs.
+
+The software development task is still too complex to specify it
+directly. So we split it further into subtasks.
+
+[[example:tutorial software]]
+
+We use the [[priority]] attribute to mark the importance of
+the tasks. 500 is the default priority of top-level tasks. Setting the
+priority to 1000 marks the task as most important task, since the
+possible range is 1 (not important at all) to 1000 (ultimately
+important). priority is an attribute that is passed down to subtasks
+if specified before the subtasks' declaration. So all subtasks of
+software have a priority of 1000 as well, unless they have their own
+priority definition.
+
+[[example:tutorial database]]
+
+The work on the database coupling should not start before the
+specification has been finished. So we again use the [[depends]]
+attribute to let TaskJuggler know about this. This time we use two
+exclamation marks for the relative ID. The first one puts us in the
+scope of the enclosing software task. The second one is to get into
+the AcSo scope that contains the spec tasks. For a change, we
+[[allocate]] resources directly without using a macro.
+
+[[example:tutorial gui]]
+
+TaskJuggler can schedule your project for two different [[scenario
+scenarios]]. We have called the first scenario ''''plan'''' scenario
+and the second ''''delayed'''' scenario. Many of the reports allow you
+to put the values of both scenarios side by side to each other, so you
+can compare the scenarios. All scenario-specific values that are
+not explicitly stated for the ''''delayed'''' scenario are taken from
+the ''''plan'''' scenario. So the user only has to specify the values
+that differ in the delayed scenario.  The two scenarios must have the
+same task structure and the same dependencies. But the start and end
+dates of tasks as well as the duration may vary. In the example we
+have planned the work on the graphical user interface to be 35
+man-days. It turned out that we actually needed 40 man-days. By
+prefixing the [[effort]] attribute with ''''delayed:'''', the
+effort value for the ''''delayed'''' scenario can be specified.
+
+[[example:tutorial backend]]
+
+By default, TaskJuggler assumes that all tasks are on schedule.
+Sometimes you want to generate reports that show how much of a task
+actually has been completed. TaskJuggler uses the current date for
+this, unless you have specified another date using the now attribute.
+If a task is ahead of schedule or late, this can be specified using
+the [[complete]] attribute. This specifies how many percent
+of the task have been completed up to the current date. In our case
+the back-end implementation is slightly ahead of schedule as we will
+see from the report.
+
+[[example:tutorial test]]
+
+The software testing task has been split up into an alpha and
+a beta test task. The interesting thing here is, that efforts can not
+only be specified as man-days, but also man-weeks, man-hours, etc. By
+default, TaskJuggler assumes a man-day is 8 hours, man-week is 40
+man-hours or 5 man-days. The conversion factor can be changed using the
+[[dailyworkinghours]] attribute.
+
+Let's go back to the outermost task again. At the beginning of the
+example we stated that we want to credit all development work to one
+account with ID dev and all documentation work to the account doc. To
+achieve this, we use the attribute [[chargeset]] to credit
+all tasks to the ''''dev'''' account.
+
+For the duration of the ''''AcSo'''' task we also have running costs
+for the lease on the building and the equipment. To compensate this,
+we charge a daily rate of USD 170 per day using the [[charge]]
+attribute.
+
+[[example:tutorial charge]]
+
+Since we specify the attribute for the top-level task before we
+declare any subtasks, this attribute will be inherited by all subtasks
+and their subtasks and so on. The only exception is the writing of the
+manual. We need to change the chargeset for this task again, as it is
+also a subtask of AcSo and we want to use a different account for it.
+
+[[example:tutorial manual]]
+
+=== Specifying Milestones ===
+
+All tasks that have been discussed so far, had a certain duration. We
+did not always specify the duration explicitly, but we expect them to
+last for a certain period of time. Sometimes you just want to capture
+a certain moment in your project plan. These moments are usually
+called milestones, since they have some level of importance for the
+progress of the project.
+
+TaskJuggler has support for milestones as well. Milestones are leaf
+tasks that don't have a duration specification.
+
+[[example:tutorial deliveries]]
+
+We have put all important milestones of the project as subtasks of the
+deliveries task. This way they show up nicely grouped in the reports.
+All milestones either have a dependency or a fixed start date. For the
+first milestone we have used the attribute [[start]] to set a fixed start
+date. All other tasks have direct or indirect dependencies on this
+task. Moving back the start date will slip the whole project. This has
+actually happened, so we use the ''''delayed:'''' prefix again to
+specify the start date for the delayed scenario.
+
+Every milestone is linked to a customer payment. By using the
+[[charge]] attribute we can credit the specified amount to the
+account associated with this task. Since we have assigned the
+''''rev'''' account to the enclosing task, all milestones will use
+this account as well. This time, we use the keyword ''''onstart''''
+to indicate that this is not a continuous charge but a one-time
+charge that is credited at the begin of the task.
+
+Did you notice the line in the task done that starts with a hash? This
+line is commented out. If TaskJuggler finds a hash, it ignores the
+rest of the line. This way you can include comments in your project.
+The [[maxend]] attribute specifies that the task should end no
+later than the specified date. This information is not used for
+scheduling, but only for checking the schedule afterwards. Since the
+task will end later than the specified date, commenting out the line
+would trigger a warning.
+
+Now the project has been completely specified. Stopping here would
+result in a valid TaskJuggler file that could be processed and
+scheduled. But no reports would be generated to visualize the results.
+
+=== Generating Reports of the scheduled Project ===
+
+TaskJuggler offers a number of report types. Probably the most popular ones are interactive reports and HTML reports.
+
+==== Generating Interactive Reports ====
+
+Interactive reports are only available in the TaskJuggler GUI. The
+command line version will just ignore interactive report definitions.
+To view a task report in the GUI, you have to add the following lines
+to your project. This will give you a list of all the project's tasks
+and the classical Gantt chart.
+
+[[example:tutorial planoverview]]
+
+The GUI requires the name column to be present in the report. If you
+don't specify it, it will be added automatically. It does not support
+any of the index columns. They will not be shown in the GUI.
+Nonetheless, it's a good idea to request it, as the printed version of
+the interactive reports behave like the other reports. They only show
+specified columns. The printed reports repeat the first column on
+every page in case it does not fit on a single page. To print a report
+from the GUI just select File->Print from the menu or click the
+printer icon in the toolbar.
+
+For this report we like to have the abbreviated weekday in front of
+the date. %a is the tag for this. See the manual for a complete list
+of all options.
+
+We don't want to see any resources in this report, so we hide them
+all. 1 means always hide a resource. To show all resources we could
+write a 0, which means never hide a resource. Or we could write a
+logical expression that only shows the leaf resources and sorts them
+by name as we did for the next report. It's a list of all tasks
+showing the resources assigned to each task.
+
+ taskreport "Task Usage" {
+   headline "Task Usage Report"
+   columns hierarchindex, name, start, end, effort { title "Work" }, duration,
+     cost, revenue
+   timeformat "%Y-%m-%d"
+   loadunit days
+   hideresource ~isLeaf()
+   sortresources nameup
+ }
+
+The default title for the effort column is replaced with a custom
+title. Additionally we show the cost and revenue of all tasks and
+resources. All loads are shown as resource-days.  The next report is
+similar to the first one, but has the completion degree as additional
+column.
+
+ # A list of all tasks with the percentage complete for each task
+ taskreport "Tracking Gantt" {
+   headline "Tracking Gantt Chart"
+   columns hierarchindex, name, start, end, effort { title "Work" }, duration,
+     completed, chart
+   timeformat "%a %Y-%m-%d"
+   loadunit days
+   hideresource 1
+ }
+
+We can also have resource-centric reports. This is done with the
+report type resourcereport. The following report is showing resource
+allocation. It identifies whether each resource is under- or
+over-allocated for.
+
+ resourcereport "Resource Graph" {
+   headline "Resource Allocation Graph"
+   columns no, name, rate, utilization, freeload, chart
+   loadunit days
+   hidetask 1
+ }
+
+The next report is a list of all project resources, both human and
+material resources, together with the associated costs.
+
+ resourcereport "Resource Sheet" {
+   headline "Resource Sheet"
+   columns no, name, efficiency, id, maxeffort, rate
+   loadunit days
+   hidetask 1
+ }
+
+The next report is similar to the previous one, but also lists the
+tasks for each of the resources. It also provides details about the
+cost for each resource and task.
+
+ # A list of resources and each task associated with each resource.
+ resourcereport "Resource Usage" {
+   headline "Resource Usage Report"
+   columns no, name, utilization, freeload, cost
+   loadunit days
+   hidetask 0
+ }
+
+==== Generating HTML Reports ====
+
+In addition to the interactive reports, TaskJuggler also provides HTML
+reports. These reports have the benefit that you can create report
+files that you can publish on a web server. TaskJuggler supports a
+variety of HTML reports. Please refer to the manual for a full list.
+In this tutorial we will only cover a subset of them.
+
+To conclude the HTML reports, a report is generated that shows how
+poorly the project is calculated. The company won't get rich with this
+project. Due to the slip, it actually needs a loan from the bank to
+pay the salaries.
+
+ htmlaccountreport "Accounting.html" {
+   columns no, name, scenario, total, monthly
+   headline "P&L for the Project"
+   caption "The table shows the profit and loss analysis as well as
+            the cashflow situation of the Accounting Software Project."
+   accumulate
+   scenarios plan, delayed
+ }
+
+The htmlaccountreport property produces similar reports as the ones
+shown above, but it lists accounts instead of tasks or resources. The
+total column shows the value of the account at the end of the reported
+time interval. The accumulate attribute puts the calendar in
+accumulation mode. The monthly columns list the value of the account
+at the end of the month. Normally the amount that has been added or
+subtracted from the account would be listed.
+