taskjuggler 0.0.2 → 0.0.3

data/manual/Tutorial

@@ -9,31 +9,33 @@ 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
+[http://www.taskjuggler.org/tj3/examples/Overview.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.
+property. It tells TaskJuggler the name of your project 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 file="tutorial" tag="header1"]>
+
+All TaskJuggler properties have two required attributes, a unique ID
+and a name, and a set of optional attributes. The name must always be
+specified. The ID can be omitted if you never have to reference the
+property from another context. If you omit the ID, TaskJuggler will
+automatically generate a unique ID. The other 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
@@ -46,7 +48,7 @@ of this manual.
 
 The [[currency]] attribute specifies the unit of currency values.
 
-[[example:tutorial currency]]
+<[example file="tutorial" tag="currency"]>
 
 Because each culture has its own way of specifying dates and numbers,
 the format for these are configurable.  Use the [[timeformat]]
@@ -55,7 +57,7 @@ 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]]
+<[example file="tutorial" tag="formats"]>
 
 We also can specify the way numbers or currency values are shown in
 the reports. Use the [[numberformat]] and [[currencyformat]]
@@ -69,7 +71,7 @@ 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]]
+<[example file="tutorial" tag="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
@@ -85,13 +87,13 @@ 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]]
+<[example file="tutorial" tag="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]]
+<[example file="tutorial" tag="header2"]>
 
 === Global Attributes ===
 
@@ -107,7 +109,7 @@ 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]]
+<[example file="tutorial" tag="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
@@ -117,7 +119,7 @@ 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]]
+<[example file="tutorial" tag="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
@@ -133,7 +135,7 @@ 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]]
+<[example file="tutorial" tag="macro"]>
 
 To use the macro you simply have to write
 ''''${allocate_developers}'''' and TaskJuggler will replace the term
@@ -149,7 +151,7 @@ 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]]
+<[example file="tutorial" tag="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
@@ -165,15 +167,16 @@ In order not to get lost with all the various amounts, we declare 3
 for the development costs, one for the documentation costs, and one
 for the customer payments.
 
-[[example:tutorial accounts]]
+<[example file="tutorial" tag="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.
+IDs may only consist of the characters a to z, A to Z and the
+underscore. All but the first character may also be digits 0 to 9.
+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
@@ -181,7 +184,7 @@ 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]]
+<[example file="tutorial" tag="balance"]>
 
 === Declaring Resources ===
 
@@ -189,7 +192,7 @@ 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]]
+<[example file="tutorial" tag="resources"]>
 
 This snippet of the example shows the use of the [[resource
 resource property]]. Just like accounts, resources always have an ID
@@ -242,7 +245,7 @@ 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]]
+<[example file="tutorial" tag="task1"]>
 
 Similar to resources, tasks are declared by using the task keyword
 followed by an ID and a name string. All TaskJuggler properties have
@@ -263,7 +266,7 @@ 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]]
+<[example file="tutorial" tag="spec"]>
 
 The [[effort]] to complete the task is specified with 20 man-days.
 Alternatively we could have used the [[length]] attribute or
@@ -286,7 +289,7 @@ sub tasks.
 Here we use the allocate_developers macro mentioned above. The
 expression ''''${allocate_developers}'''' is simply expanded to 
 
-[[example:tutorial expandedmacro]]
+<[example file="tutorial" tag="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
@@ -328,7 +331,7 @@ 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]]
+<[example file="tutorial" tag="software"]>
 
 We use the [[priority]] attribute to mark the importance of
 the tasks. 500 is the default priority of top-level tasks. Setting the
@@ -339,7 +342,7 @@ 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]]
+<[example file="tutorial" tag="database"]>
 
 The work on the database coupling should not start before the
 specification has been finished. So we again use the [[depends]]
@@ -349,7 +352,7 @@ 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]]
+<[example file="tutorial" tag="gui"]>
 
 TaskJuggler can schedule your project for two different [[scenario
 scenarios]]. We have called the first scenario ''''plan'''' scenario
@@ -366,7 +369,7 @@ 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]]
+<[example file="tutorial" tag="backend"]>
 
 By default, TaskJuggler assumes that all tasks are on schedule.
 Sometimes you want to generate reports that show how much of a task
@@ -378,7 +381,7 @@ 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]]
+<[example file="tutorial" tag="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
@@ -398,7 +401,7 @@ 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]]
+<[example file="tutorial" tag="charge"]>
 
 Since we specify the attribute for the top-level task before we
 declare any subtasks, this attribute will be inherited by all subtasks
@@ -406,7 +409,7 @@ 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]]
+<[example file="tutorial" tag="manual"]>
 
 === Specifying Milestones ===
 
@@ -420,7 +423,7 @@ 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]]
+<[example file="tutorial" tag="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.
@@ -452,128 +455,171 @@ 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.
+=== Visualizing the Project ===
+
+To see and share the project data you reports can be generated. You
+can generate any number of reports and you can select from a variety
+of report types and output formats. To have a report generated after
+the project scheduling has been completed, you need include a report
+definition into the project description. Report definitions are
+properties that are very similar to the task and resource properties
+that you are already familiar with. Just like these, report
+definitions can be nested to take advantage of the attribute
+inheritance mechanism. Every report definition starts with the type
+of the report. Each type of report has a particular focus. A
+[[taskreport]] lists the project data in the form of a task list.
+A [[resourcereport]] does the same in form of a resource list. For a
+more generic report, you can use the [[textreport]].
+
+A ''''textreport'''' does not directly present the data in form of a
+task or resource list. It just consists of text building blocks that
+are described by [[Rich_Text_Attributes Rich Text]]. There can be a
+building block at the top and bottom, as well as three columns in
+the center. The column are called ''''left'''', ''''center'''' and
+''''right''''.
+
+For our first report, we'll just use the center column for now. Like
+every property, you need to specify a name. This name will be the
+base name of the generated report file. Depending on the output
+format, the proper suffix is appended. For this report, we only chose
+to generate a web page in HTML format. There is no default format
+defined for reports. If the [[formats]] attribute is not specified,
+no output file will be generated for the report specification.
+
+This may seem odd at first glance since TaskJuggler syntax always
+tries to use the most compact and readable syntax for the common
+case. As you will see in a minute, reports may be composed of several
+report specifications. One report specification can include the
+output of another report specification as well. In this case, the
+included report does not need to generate it's own file. The output
+will be included within the output of another report specification.
+In case of such composed reports, the output format specification of
+the top-level format will be used for all included reports as well.
+
+<[example file="tutorial" tag="overview_report1"]>
+
+Web browsers usually look for a file called ''''Overview.html'''' when
+they are pointed to a directory. For the main report, we choose the
+file name ''''Overview'''' and the format ''''html''''.
+
+As we've mentioned before, the sections of a ''''textreport'''' are
+defined in Rich Text format. Here we use a so called block generator
+to include the HTML output of another report definition. The
+''''report'''' block generator allows us to compose reports by
+combining their output into a single report. You must provide the
+''''id'''' parameter to specify which report definition you would
+like to use. In this case, it is a report definition with the ID
+''''overview''''. Note that generator parameters need to be enclosed
+in single or double quotes. We are essentially marking a string
+within a string. This can only work out, if we don't use the same
+parameter for both. Let's define this report first.
+
+<[example file="tutorial" tag="overview1"]>
+
+Instead of another [[textreport]] definition we are now using a
+[[taskreport]]. A task report contains a list of tasks in a table
+structure. By default, it contains all tasks of the project. As we
+will see later on, we can use filter expressions to limit the content
+to a well defined subset of tasks. The table contains a line for each
+task and comes by default with a few columns like the name of the
+task, and the start and end dates. For this project overview report,
+we like to have also the effort for each task, the duration, the
+effort, the cost and revenue numbers included. To top it off, we also
+include a column with a Gantt chart.
+
+By including the cost and revenue column, we are able to do a simple
+profit and loss analysis on the project. This P&L is computed from
+the accounts that we have provided above. For this to work, we need
+to tell TaskJuggler which accounts are cost accounts and which are
+revenue accounts. We have already conveniently grouped the accounts
+and the [[balance]] attribute specifies which accounts are used for
+the P&L in this report.
+
+<[example file="tutorial" tag="overview2"]>
+
+We have chosen to include the start and end date of each task in the
+report. By default, TaskJuggler lists dates as day, month and year.
+We like the format to be similar to the format that the project
+syntax uses, but also like to include the weekday. To change the date
+format, the [[timeformat]] attribute can be used.
+
+The project will last a few weeks. The most convenient unit to list
+efforts in is man or resource days. The [[loadunit]] attribute tells
+TaskJuggler to list the load of each task or resource in man days.
+Since this will just be a number without a unit, it is advisable to
+include a small hint for the reader that these values are indeed man
+or resource days. The caption of the table is a convenient place to
+put this information by using the [[caption]] attribute.
+
+<[example file="tutorial" tag="overview3"]>
+
+The ''''taskreport'''' can contain more than just the table. It is
+not as flexible as the ''''textreport'''', but still has support for
+a header and footer. Let's look at the header first. We not only
+like to put a headline here, but several paragraphs of text. The
+[[header]] attribute is a [[Rich_Text_Attributes Rich Text]]
+attribute just like [[center]]. We could enclose it in single or
+double quotes again. But for Strings that span multiple lines and
+potentially include single or double quotes as well, scissor-marks or
+cut-here-marks are recommended. These marks look like a pair of
+scissors that cut along a dashed line. Use ''''-8<-'''' to begin a
+string and ''''->8-'''' to terminate it. The opening cut mark must be
+immediately followed by a line break. The indentation of the
+following line defines the indentation that will be ignored for all
+lines of the string. The following lines must have at least the same
+indentation. The indentation that exceeds the indentation of the
+first line will be kept in the resulting string. With this feature,
+you can define multi-line Rich Text strings without disturbing the
+indentation structure of your project file.
+
+<[example file="tutorial" tag="overview4"]>
+
+Section headers are surrounded by ''''<nowiki>==</nowiki>''''. The
+number of equal signs, define the section level. You need to start
+with two equal characters for the first level. Text that is surrounded
+by blank lines will create a paragraph. Bullet lists can be made by
+starting a line with a ''''#'''' character. Remember that the
+indentation of cut-mark strings will be ignored. Your ''''#''''
+character must not be the first character in the line as long it is
+only preceded by the exact same number of blanks as the first line of
+the cut-mark string.
+
+If you want to reference other reports from this report, you can
+include the file name of this report by ''''<nowiki>[[</nowiki>''''
+and ''''<nowiki>]]</nowiki>''''.  Don't include the extension of the
+file name, it will be automatically appended. The actual
+representation of the reference depends on the chosen output format.
+For HTML output, the reference is a click-able link to the referenced
+report file.
+
+For the [[footer]] we can proceed accordingly. We just add a few more
+paragraphs of text the describe certain aspects of the project. By
+putting it all together, we end up with the following report
+definition.
+
+<[example file="tutorial" tag="overview"]>
+
+The generated report can be found
+[http://www.taskjuggler.org/tj3/examples/Overview.html
+here]. It servers as an entry page for the other reports. While it
+already contains some references, a navigator bar would be handy as
+well. Fortunately, there is a block generator called 'navigator' to
+take care of this. But before we can include the navigator in the
+report, we need to define it first.
+
+<[example file="tutorial" tag="navigator"]>
+
+[[hidereport]] is a filter attribute. The logical expression
+determines which reports will be included in the navigator bar. A
+logical expression of 0 means hide no reports, so all are included.
+
+The best place to put a navigator bar in the report is right at the
+top. We use two horizontal lines to separate the navigator from the
+main headline and the rest of the report.
+''''<nowiki>----</nowiki>'''' at the begin of the line create such a
+horizontal separation line.
+
+<[example file="tutorial" tag="overview_report2"]>
+
+
 

data/tasks/test.rake

@@ -1,6 +1,9 @@
+$:.unshift File.join(File.dirname(__FILE__), '..', 'test')
 
 require 'rake/testtask'
 
+REQUIRE_PATHS.unshift File.join(File.dirname(__FILE__), '..')
+
 # TEST TASK
 test_task_name = HAVE_EXT ? :test_ext : :test
 Rake::TestTask.new( test_task_name ) do |t|

data/test/TestSuite/CSV-Reports/celltext.tjp

@@ -1,7 +1,8 @@
 project test "Test" "1.0" 2007-12-16 +3m
 include "project-1.tji"
 
-csvtaskreport "." {
+taskreport csv "." {
+  formats csv
   columns wbs, name { celltext "$${name} ($${id})" }
 }
 

data/test/TestSuite/CSV-Reports/resourcereport.tjp

@@ -1,7 +1,8 @@
 project test "Test" "1.0" 2007-12-16 +3m
 include "project-1.tji"
 
-csvresourcereport "." {
+resourcereport csv "." {
+  formats csv
   columns wbs, name, effort, weekly
   timeformat "%Y-%m-%d-%H:%M:%S"
   loadunit days

data/test/TestSuite/CSV-Reports/resourcereport_with_tasks.tjp

@@ -1,7 +1,8 @@
 project test "Test" "1.0" 2007-12-16 +3m
 include "project-1.tji"
 
-csvresourcereport "." {
+resourcereport csv "." {
+  formats csv
   columns wbs, name, effort, weekly
   timeformat "%Y-%m-%d-%H:%M:%S"
   loadunit days