taskjuggler 0.0.3 → 0.0.4

data/lib/tj3man.rb

@@ -3,7 +3,7 @@
 #
 # = tj3man.rb -- The TaskJuggler III Project Management Software
 #
-# Copyright (c) 2006, 2007, 2008, 2009 by Chris Schlaeger <cs@kde.org>
+# Copyright (c) 2006, 2007, 2008, 2009, 2010 by Chris Schlaeger <cs@kde.org>
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of version 2 of the GNU General Public License as
@@ -27,12 +27,12 @@ class Arguments
     @manual = false
 
     opts = OptionParser.new
-    opts.banner = "#{AppConfig.packageName} v#{AppConfig.version} - " +
+    opts.banner = "#{AppConfig.softwareName} v#{AppConfig.version} - " +
                   "#{AppConfig.packageInfo}\n\n" +
                   "Copyright (c) #{AppConfig.copyright.join(', ')}" +
                   " by #{AppConfig.authors.join(', ')}\n\n" +
                   "#{AppConfig.license}\n" +
-                  "For more info about #{AppConfig.packageName} see " +
+                  "For more info about #{AppConfig.softwareName} see " +
                   "#{AppConfig.contact}\n"
     opts.separator ''
     opts.separator "Usage: #{AppConfig.appName} [options] [<keyword> ...]"
@@ -77,7 +77,7 @@ def main
     end
   end
 
-  #$stderr.puts "#{AppConfig.packageName} v#{AppConfig.version} - " +
+  #$stderr.puts "#{AppConfig.softwareName} v#{AppConfig.version} - " +
   #             "#{AppConfig.packageInfo}\n\n"
   #puts man.to_s(args.keyword)
 

data/manual/Getting_Started

@@ -60,53 +60,3 @@ define them in the following sequence.
 * [[report reports]]
 * [[export exports]]
 
-=== Types of variable Syntax Elements ===
-
-==== ABSOLUTE_ID ====
-
-An absolute identifier is composed of identifiers that are
-concatenated by dots, e. g. ''''foo.bar''''. It is used to reference
-a TaskJuggler property that lives in a hierarchical name space.
-Accounts, Tasks, Reports are examples for such hierarchical name
-spaces. To reference the sub-task ''''bar'''' of task ''''foo'''' the
-absolute ID ''''foo.bar'''' is used.
-
-==== ID ====
-
-An identifier is composed of the letters ''''a'''' to ''''z'''',
-''''A'''' to ''''Z'''', the underscore and the digits ''''0'''' to
-''''9''''. There are no limits for the number of characters, but it
-may not begin with a digit.
-
-==== INTEGER ====
-
-An integer is any natural number, e. g. ''''0'''', ''''1'''',
-''''2'''' and so on.
-
-==== STRING ====
-
-Strings are character sequences that are enclosed by special
-character marks. There are three different marks supported. For
-short strings that fit on one lines, you can either use single or
-double quotes.
-
- 'This is a single quoted string.'
- "This is a double quoted string."
-
-Single quoted strings may contain double quotes and vice versa.
-
-For multi-line strings cut mark strings are recommended. A
-cut-mark-string starts with ''''-8<-'''' (scissor on a dotted line) and
-ends with ''''->8-''''. The start mark must be immediately followed
-by a line break. The indentation of the first line must be repeated
-for all following lines of the string and is not included in the
-resulting strings. The terminating cut mark must only be preceeded by
-white spaces by may not be indented more than the first line indentation.
-
- -8<-
-   This is a
-   multi-line
-   string.
-   ->8-
-
-

data/manual/How_To_Contribute

@@ -31,13 +31,8 @@ for your TaskJuggler contributions, you should consider using a Linux
 Live (or bootable) CD/DVD or use a VmWare Player image of a Linux
 distribution.
 
-As a first step, you need to checkout the latest version of
-the TaskJuggler. This will create a directory called taskjuggler in
-your current directory. It not only contains the latest sources, but
-also the full revision history of the code. It is your local copy of
-the TaskJuggler source repository.
-
- git clone http://www.taskjuggler.org/git-repos/taskjuggler.git
+Make sure you have followed the steps described in the
+[Installation#Installation_Steps_for_Developers] chapter.
 
 If you have never used Git before, you need to configure it first. You
 need to set your name and email address. This information will be
@@ -46,12 +41,10 @@ present in all patches that you submit.
  git config --global user.name "Your Name"
  git config --global user.email "firstname.lastname@domain.org"
 
-See the [[Installation]] section for how to build and install
-TaskJuggler.
-
-Do not use the development snapshots and send your patches as plain
-diff files. After having switched to Git, we no longer accept such
-patches.
+Do not use the development snapshots or send your patches as plain
+diff files. We'd like to ensure that we know who contributed to
+TaskJuggler. Therefor we are only accepting signed-off git patches
+with full user names and valid email addresses.
 
 Next you need to find the files where you want to make your
 modifications. Sometimes files will be generated from other files. Do

data/manual/Installation

@@ -2,11 +2,13 @@
 
 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''''.
+standard Ruby mechanism for distribution, a package format called
+[http://docs.rubygems.org RubyGems].
 
-This is a prototype. Consider it being alpha quality at best!
+TaskJuggler III is still under development. There is no stable
+version yet. You are welcome to try it. Some users are already using
+it successfully for their purposes, but it might not yet be right for
+you.
 
 === Requirements ===
 
@@ -15,54 +17,126 @@ 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
+* '''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.
+TaskJuggler currently needs at least Ruby version 1.8.6.
 
-* ''RubyGems'' If it did not come with your OS or Ruby package, see
-[http://docs.rubygems.org here] how to get and install it.
+* '''RubyGems:''' If it did not come with your OS or the Ruby
+installation, 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 Steps for Users ===
 
-=== Installation Process ===
+==== The easy way ====
 
-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.
+TaskJuggler is a commandline tool. It does not (yet) have a graphical
+user interface. To use it, you need to know how to open a command
+or terminal window. In this manual, we refer to it as your shell. The
+following paragraphs describe the commands you need to type into your
+[http://en.wikipedia.org/wiki/Shell_(computing) shell].
 
-In addition to the above listed dependencies, you need to have the
-following packages installed:
+On systems that already have Ruby and the gem package manager
+installed you can simply type the following command into your shell
+or command window:
 
-* [http://rake.rubyforge.org Rake] The Ruby build tool.
+  gem install taskjuggler
 
-* [http://eigenclass.org/hiki.rb?rcov rcov] The rcov code
-coverage analysis tool.
+This will download and install the latest version from the
+[http://gemcutter.org/ Gemcutter] site.
 
-The following command will create an archive file called a gem
-package.
+==== The manual way ====
+
+If the easy way doesn't work for you, you need to download and install
+the packages manually.  Get TaskJuggler III from the
+[http://www.taskjuggler.org/download.php Download Page].
 
- 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
+has Ruby and RubyGems installed.  Normally, you should be logged-in
 as root or administrator to run the following installation command.
+Replace the X.X.X with the actual version that you have downloaded.
 
  gem install pkg/taskjuggler-X.X.X.gem 
 
 It will install all components of the Gem in the appropriate place.
 
-=== Update from previous versions ===
+On user friendly Linux distributions, the start scripts will be
+installed in a standard directory like ''''/usr/bin''''. On Debian
+based distributions, the start scripts end up in a place like
+''''/var/lib/gems/1.8/bin/'''' that is not listed in the ''''PATH''''
+variable. You either have to create a symbolic link for each start
+script or add the directory to your PATH variable. If you use the
+standard [http://en.wikipedia.org/wiki/Bash bash shell], put the
+following line in your ''''${HOME}/.profile'''' file.
+
+ PATH=${PATH}:/var/lib/gems/1.8/bin/
+
+Windows and MacOS platforms may require similar steps.
+
+=== Update from older TaskJuggler III versions ===
 
 Updates work just like the installation.
 
+ gem update taskjuggler
+
+For downloaded or self-built packages use the following command:
+
  gem update pkg/taskjuggler-X.X.X.gem
 
 
+=== Installation Steps for Developers ===
+
+The following description is for users that want to learn more about
+TaskJuggler or want to make improvements. TaskJuggler is
+[http://en.wikipedia.org/wiki/Open_source Open Source] software and
+you are encouraged to read and modify the source code.
+
+To get the source code, the recommended way it to check out the
+latest code from the developer repository. To do this, you need to
+have [http://www.kernel.org/pub/software/scm/git/docs/ git] installed.
+
+Then checkout the source code with the following command
+
+ git clone http://www.taskjuggler.org/git-repos/taskjuggler3.git
+
+Make sure, you
+have removed all previously installed instances of TaskJuggler from
+your 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.
+
+If your Ruby installation does not come with the
+[http://rake.rubyforge.org Rake] build tool, you need to install it
+now.
+
+If you are interested in a code coverage analysis, you need to also
+install the [http://eigenclass.org/hiki.rb?rcov rcov] code coverage
+analysis tool. This tool is not needed for most developers. You can
+safely ignore the warning during rake builds if you don't have it
+installed.
+
+The following command will create a gem package from the source code.
+
+ cd taskjuggler3; rake gem
+ 
+If you plan to modify the TaskJuggler files, creating and installing
+the gem file for every test run is not very comfortable. To run tj3
+from source put the following code in ''''${HOME}/bin/tj3''''. 
+
+ #! /usr/bin/ruby
+ 
+ # Set this to your source code directory
+ ENV['TASKJUGGLER_DATA_PATH'] = "#{ENV['HOME']}/src/taskjuggler3"
+ 
+ $:.unshift "#{ENV['TASKJUGGLER_DATA_PATH']}/lib/"
+ 
+ require "taskjuggler3"
+
+Don't forget to mark it as executable.
+
+ chmod 750 ${HOME}/bin/tj3
+
+

data/manual/Intro

@@ -63,7 +63,7 @@ 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.
+This manual is Copyright (c) 2006, 2007, 2008, 2009, 2010 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
@@ -72,6 +72,16 @@ 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".
 
+The HTML reports use icons from the
+[http://www.kde.org/people/credits/ KDE Icon Team]. The icons are
+licensed under the [http://www.fsf.org/licenses/lgpl.html GNU Lesser
+General Public License].
+
+The HTML reports use Java Script code from [http://www.walterzorn.com
+Walter Zorn]. The code is licensed under the
+[http://www.fsf.org/licenses/lgpl.html GNU Lesser General Public
+License].
+
 === Features and Highlights ===
 
 * Manages tasks, resources and costs in one package

data/manual/Reporting_Bugs

@@ -15,19 +15,35 @@ particular, you should check the
 [http://groups.google.com/group/taskjuggler-bugs/topics existing bug
 reports].
 
-* Possibly the bug was already found
-and a patch or workaround exists.
+* 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.
 
 * If TaskJuggler has crashed you will usually get some debug output. This
 may not make any sense to you but it is vital information to analyze
-the bug. Please include it completely in your bug report.
+the bug. Please include it completely in your bug report. Use the
+following command to store the messages into a file.
+
+ tj3 yourproject.tjp 2> error_message
 
 * Send the test project and a detailed description of the problem to
-the [http://www.taskjuggler.org/forum.php 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.
+the TaskJuggler developers. If you are pretty confident, that you've
+found a new bug, please post it to the
+[http://groups.google.com/group/taskjuggler-bugs TaskJuggler Bug
+Group]. If you aren't sure or want to provide patches or feedback,
+please use the [http://groups.google.com/group/taskjuggler-dev
+TaskJuggler Developer Group].
+
+* When posting complete files, make sure you attach them. Don't paste
+them into the body of the email. Some email servers and clients have
+a habit of converting the body into HTML which will corrupt the file
+contents. Unfortunately, the Google Groups web interface does not
+support attachments. Please use a regular email program instead. The
+posting addresses can be found on the above mentioned pages.
+
+* Not attaching a test case will severely limit our abilities to help
+you. Please make sure you provide meaningful descriptions and a small
+but complete test project.  Not providing this information usually
+triggers requests or leads to bug reports being ignored.
 

data/manual/Rich_Text_Attributes

@@ -112,20 +112,73 @@ by double or single quotes, make sure you don't use the same quoting
 marks for the parameter value. Alternatively you can put a backslash
 in front of the quote mark to escape it.
 
+----
 '''Block Generator''' ''''navigator''''
 
 Parameters:
 
-* id : ID of a defined [[navigator]]
-
-''The navigator generator inserts the referenced navigator.''
+* ''''id'''' : ID of a defined [[navigator]]
 
+The navigator generator inserts the referenced navigator.
+----
 '''Block Generator''' ''''report''''
 
 Paramters:
 
-* id : ID of a defined [[report]]
+* ''''id'''' : ID of a defined [[report]]
 
-''The report generator inserts the referenced report as a new block
+The report generator inserts the referenced report as a new block
 of this text. The referenced report inherits some context such as the
-report period and the property set from the referencing report.''
+report period and the property set from the referencing report.
+----
+'''Inline Generator''' ''''query''''
+
+* ''''family'''' : Specifies whether a ''''task'''' or a ''''resource''''
+should be queried.
+
+* ''''property'''' : The ID of the task or resource to be queried. If no
+property is specified, the query will return a global project
+attribute.
+
+* ''''scopeproperty'''' : The ID of the scope property. If the property is a
+task this must be a resource ID and vice versa.
+
+* ''''attribute'''' : The ID of the attribute which value should be returned
+by the query. If a property ID is provided, this must be one of the
+names that can be used as [[columnid]] values. Without a property,
+global attributes of the project can be requested. The following
+attributes are supported: ''''copyright'''', ''''currency'''',
+''''end'''', ''''name'''', ''''now'''', ''''projectid'''',
+''''start'''' and ''''version''''.
+
+* ''''scenario'''' : The ID of a scenario. This must be provided whenever the
+requested attribute is scenario specific.
+
+* ''''start'''' : The start date of the report period of the current report.
+
+* ''''end'''' : The end date of the report period of the current report.
+
+* ''''loadunit'''' : The [[loadunit]] that should be used in case the
+requested attribute is an effort or duration value.
+
+* ''''timeformat'''' : The [[timeformat]] used to format date attributes.
+
+* ''''numberformat'''' : The [[numberformat]] used to format arithmetic
+attributes.
+
+* ''''currencyformat'''' : The [[currencyformat]] used to format currency
+values.
+
+The query generator inserts any requested value from the project, a
+task or a resource.
+
+Queries are context aware. Depending on the context where the query
+is used, certain or all of the above parameters have already
+predefined values. When used in the header section of a report, the
+context does not provide a property or scope property. Start and end
+dates as well the formatting options are taken from the report
+context. But when used e. g. in [[celltext.column]] the cell
+provides, that property and the attribute and possibly even the scope
+property.
+
+

data/manual/TaskJuggler_2x_Migration

@@ -38,3 +38,30 @@ What used to be ''''startup'''' is now ''''plan.start.up''''. See
 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]].
+
+* Shifts and limits for allocations have been deprecated. The concept
+was bogus and not compatible with bookings. The functionality is
+now provided by [[shifts.task shifts]] and [[limits.task limits]] on the
+task level. Limits for a task can be [[limit.resources selectively
+applied]] to certain resources.
+
+* Support for reading and writing XML files is no longer available.
+The content was redundant with the TJP file format and it was not
+widely used. Keeping it in sync was too much of an effort to be worth
+it. There is nothing in the TJ3 design that would prevent this
+feature from being added again, but there are no plans for this right
+now.
+
+* The format for [[report reports]] has been changed considerably.
+The old format was not very flexible and had some design flaws.
+TaskJuggler III now supports report nesting and composition. A report
+definition can be used to generated multiple output [[formats]]. The
+name of a report must now be specified without the file name
+extension. It will be automatically added depending on the output
+format.
+
+* IDs for properties such as tasks, resources and reports are now
+optional. If you don't need to reference a property, you can omit the
+ID. TaskJuggler will automatically assign an ID then.
+
+