taskjuggler 0.0.7 → 0.0.8

data/lib/TextParser/State.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = Rule.rb -- The TaskJuggler III Project Management Software
+#
+# 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
+# published by the Free Software Foundation.
+#
+
+class TaskJuggler::TextParser
+
+  # A StateTransition maps a token type to the next state to be
+  # processed. A token descriptor is either a Symbol that maps to a RegExp in
+  # the TextScanner or an expected String.  The transition may also have a
+  # list of State objects that are being activated by the transition.
+  class StateTransition
+
+    attr_reader :tokenType, :state, :stateStack, :loopBack
+
+    # Create a new StateTransition object. _descriptor_ is a [ token type,
+    # token value ] touple. _state_ is the State objects this transition
+    # originates at. _stateStack_ is the list of State objects that have been
+    # activated by this transition. _loopBack_ is a boolean flag that
+    # specifies whether the transition describes a loop back to the start of
+    # the Rule or not.
+    def initialize(descriptor, state, stateStack, loopBack)
+      if !descriptor.respond_to?(:length) || descriptor.length != 2
+        raise "Bad parameter descriptor: #{descriptor} " +
+              "of type #{descriptor.class}"
+      end
+      @tokenType = descriptor[0] == :eof ? :eof : descriptor[1]
+
+      if !state.is_a?(State)
+        raise "Bad parameter state: #{state} of type #{state.class}"
+      end
+      @state = state
+
+      if !stateStack.is_a?(Array)
+        raise "Bad parameter stateStack: #{stateStack} " +
+              "of type #{stateStack.class}"
+      end
+      @stateStack = stateStack.dup
+      @loopBack = loopBack
+    end
+
+    # Generate a human readable form of the TransitionState date. It's only
+    # used for debugging.
+    def to_s
+      str = "#{@state.rule.name}, " +
+            "#{@state.rule.patterns.index(@state.pattern)}, #{@state.index} "
+      unless @stateStack.empty?
+        str += "("
+        @stateStack.each do |s|
+          str += "#{s.rule.name} "
+        end
+        str += ")"
+      end
+      str += '(loop)' if @loopBack
+      str
+    end
+
+  end
+
+  # This State objects describes a state of the TextParser FSM. A State
+  # captures the position in the syntax description that the parser is
+  # currently at. A position is defined by the Rule, the Pattern and the index
+  # of the current token of that Pattern. An index of 0 means, we've just read
+  # the 1st token of the pattern. States which have no Pattern describe the
+  # start of rule. The parser has not yet identified the first token, so it
+  # doesn't know the Pattern yet.
+  #
+  # The actual data of a State is the list of possible StateTransitions to
+  # other states and a boolean flag that specifies if Reduce operations are
+  # valid for this State or not. The transitions are hashed by the token that
+  # would trigger this transition.
+  class State
+
+    attr_reader :rule, :pattern, :index, :transitions
+    attr_accessor :noReduce
+
+    def initialize(rule, pattern = nil, index = 0)
+      @rule = rule
+      @pattern = pattern
+      @index = index
+      # Starting states are always reduceable. Other states may or may not be
+      # reduceable. For now, we assume they are not.
+      @noReduce = !pattern.nil?
+
+      @transitions = {}
+    end
+
+    # Completed the StateTransition list. We can only call this function after
+    # all State objects for the syntax have been created. So we can't make
+    # this part of the constructor.
+    def addTransitions(states, rules)
+      if @pattern
+        # This is an normal state node.
+        @pattern.addTransitionsToState(states, rules, [], self,
+                                       @rule, @index + 1, false)
+      else
+        # This is a start node.
+        @rule.addTransitionsToState(states, rules, [], self, false)
+      end
+    end
+
+    # This method adds the actual StateTransition to this State.
+    def addTransition(token, nextState, stateStack, loopBack)
+      tr = StateTransition.new(token, nextState, stateStack, loopBack)
+      if @transitions.include?(tr.tokenType)
+        raise "Ambiguous transition for #{tr.tokenType} in \n#{self}\n" +
+              "The following transition both match:\n" +
+              "  #{tr}\n  #{@transitions[tr.tokenType]}"
+      end
+      @transitions[tr.tokenType] = tr
+    end
+
+    # Find the transition that matches _token_.
+    def transition(token)
+      if token[0] == :ID
+        # The scanner cannot differentiate between IDs and literals that look
+        # like IDs. So we look for literals first and then for IDs.
+        @transitions[token[1]] || @transitions[:ID]
+      elsif token[0] == :LITERAL
+        @transitions[token[1]]
+      else
+        @transitions[token[0]]
+      end
+    end
+
+    # Return a comma separated list of token strings that would trigger
+    # transitions for this State.
+    def expectedTokens
+      tokens = []
+      @transitions.each_key do |t|
+        tokens << "#{t.is_a?(String) ? "'#{t}'" : ":#{t}"}"
+      end
+      tokens
+    end
+
+    # Convert the State data into a human readable form. Used for debugging
+    # only.
+    def to_s(short = false)
+      if short
+        if @pattern
+          str = "#{rule.name} " +
+                "#{rule.patterns.index(@pattern)} #{@index}"
+        else
+          str = "#{rule.name} (Starting Node)"
+        end
+      else
+        if @pattern
+          str = "=== State: #{rule.name} " +
+                "#{rule.patterns.index(@pattern)} #{@index}" +
+                " #{@noReduce ? '' : '(R)'}" +
+                " #{'=' * 40}\nPattern: #{@pattern}\n"
+        else
+          str = "=== State: #{rule.name} (Starting Node) #{'=' * 30}\n"
+        end
+
+        @transitions.each do |type, target|
+          targetStr = target ? target.to_s : "<EOF>"
+          str += "  #{type.is_a?(String) ? "'#{type}'" : ":#{type}"}" +
+                 " => #{targetStr}\n"
+        end
+        str += "#{'=' * 76}\n"
+      end
+      str
+    end
+
+  end
+
+end

data/lib/TextScanner.rb

@@ -57,7 +57,6 @@ class TaskJuggler
         @fileName = nil
         @stream = nil
         @line = nil
-        @pos = 0
         @endPos = 1
         @scanner = nil
         @wrapped = false
@@ -70,10 +69,11 @@ class TaskJuggler
       end
 
       def injectMacro(macro, args, text)
-        @nextMacroEnd = @pos + text.length
-        @line = @line[0, @pos] + text + @line[@pos..-1]
+        pos = @scanner.pos
+        @nextMacroEnd = pos + text.length
+        @line = @line[0, pos] + text + @line[pos..-1]
         @scanner = StringScanner.new(@line)
-        @scanner.pos = @pos
+        @scanner.pos = pos
 
         # Simple detection for recursive macro calls.
         return false if @macroStack.length > 20
@@ -109,10 +109,12 @@ class TaskJuggler
         return nil if (token = @scanner.scan(re)).nil?
         #puts "#{re.to_s[0..20]}: [#{token}]"
 
-        @pos = @scanner.pos
-        while @nextMacroEnd && @nextMacroEnd < @pos
-          @macroStack.pop
-          @nextMacroEnd = @macroStack.empty? ? nil : @macroStack.last.endPos
+        if @nextMacroEnd
+          pos = @scanner.pos
+          while @nextMacroEnd && @nextMacroEnd < pos
+            @macroStack.pop
+            @nextMacroEnd = @macroStack.empty? ? nil : @macroStack.last.endPos
+          end
         end
 
         token
@@ -246,7 +248,7 @@ class TaskJuggler
     end
 
     # Switch the parser to another mode. The scanner will then only detect
-    # with pattens of that _newMode_.
+    # patterns of that _newMode_.
     def mode=(newMode)
       #puts "**** New mode: #{newMode}"
       @activePatterns = @patternsByMode[newMode]
@@ -362,21 +364,24 @@ class TaskJuggler
         # @fileStack.
         @finishLastFile = false
         #Log << "Completed file #{@cf.fileName}"
-        @cf.close
+        @cf.close if @cf
         @fileStack.pop
 
         if @fileStack.empty?
           # We are done with the top-level file now.
           @cf = @tokenBuffer = nil
           @finishLastFile = true
-          return [ '.', '<END>', @startOfToken ]
+          return [ :endOfText, '<EOT>', @startOfToken ]
         else
           # Continue parsing the file that included the current file.
           @cf, tokenBuffer = @fileStack.last
           Log << "Parsing file #{@cf.fileName} ..."
           # If we have a left over token from previously processing this file,
           # return it now.
-          return tokenBuffer if tokenBuffer
+          if tokenBuffer
+            @finishLastFile = true if tokenBuffer[0] == :eof
+            return tokenBuffer
+          end
         end
       end
 
@@ -391,7 +396,7 @@ class TaskJuggler
                 # We've found the end of an input file. Return a special token
                 # that describes the end of a file.
                 @finishLastFile = true
-                return [ '.', '<END>', @startOfToken ]
+                return [ :eof, '<END>', @startOfToken ]
               end
 
               raise "#{re} matches empty string" if match.empty?
@@ -401,7 +406,6 @@ class TaskJuggler
 
               break if type.nil? # Ignore certain tokens with nil type.
 
-              #puts "type: #{type}  match: [#{match}]"
               return [ type, match, @startOfToken ]
             end
           end
@@ -467,7 +471,7 @@ class TaskJuggler
     end
 
     def warning(id, text, sfi = nil, data = nil)
-      message(:warning, id, text, sfi, @cf ? @cf.line : nil, data)
+      message(:warning, id, text, sfi, data)
     end
 
     private

data/lib/Tj3Config.rb

@@ -13,7 +13,7 @@
 require 'UTF8String'
 require 'AppConfig'
 
-AppConfig.version = '0.0.7'
+AppConfig.version = '0.0.8'
 AppConfig.packageName = 'taskjuggler'
 AppConfig.softwareName = 'TaskJuggler III'
 AppConfig.packageInfo = 'A Project Management Software'

data/lib/TjTime.rb

@@ -36,8 +36,7 @@ class TaskJuggler
       if t.is_a?(Time)
         @time = t
       elsif t.is_a?(String)
-        d = DateTime.parse(t)
-        @time = Time.mktime(d.year, d.mon, d.day, d.hour, d.min, d.sec)
+        @time = TjTime.parse(t).time
       else
         @time = Time.at(t)
       end
@@ -60,6 +59,111 @@ class TaskJuggler
       TjTime.new(Time.local(*args).gmtime)
     end
 
+    def TjTime.parse(t)
+      year, month, day, time, zone = t.split('-', 5)
+
+      # Check the year
+      if year
+        year = year.to_i
+        if year < 1970 || year > 2035
+          raise TjException.new, "Year #{year} out of range (1970 - 2035)"
+        end
+      else
+        raise TjException.new, "Year not specified"
+      end
+
+      # Check the month
+      if month
+        month = month.to_i
+        if month < 1 || month > 12
+          raise TjException.new, "Month #{month} out of range (1 - 12)"
+        end
+      else
+        raise TjException.new, "Month not specified"
+      end
+
+      # Check the day
+      if day
+        day = day.to_i
+        maxDay = [ 0, 31, Date.gregorian_leap?(year) ? 29 : 28, 31, 30, 31,
+                   30, 31, 31, 30, 31, 30, 31 ]
+        if month < 1 || month > maxDay[month]
+          raise TjException.new, "Day #{day} out of range (1 - #{maxDay[month]})"
+        end
+      else
+        raise TjException.new, "Day not specified"
+      end
+
+      # The time is optional. Will be expanded to 00:00:00.
+      if time
+        hour, minute, second = time.split(':')
+
+        # Check hour
+        if hour
+          hour = hour.to_i
+          if hour < 0 || hour > 23
+            raise TjException.new, "Hour #{hour} out of range (0 - 23)"
+          end
+        else
+          raise TjException.new, "Hour not specified"
+        end
+
+        if minute
+          minute = minute.to_i
+          if minute < 0 || minute > 59
+            raise TjException.new, "Minute #{minute} out of range (0 - 59)"
+          end
+        else
+          raise TjException.new, "Minute not specified"
+        end
+
+        # Check sencond. This value is optional and defaults to 0.
+        if second
+          second = second.to_i
+          if second < 0 || second > 59
+            raise TjException.new, "Second #{second} out of range (0 - 59)"
+          end
+        else
+          second = 0
+        end
+      else
+        hour = minute = second = 0
+      end
+
+      # The zone is optional and defaults to the current time zone.
+      if zone
+        if zone[0] != ?- && zone[0] != ?+
+          raise TjException.new, "Time zone adjustment must be prefixed by " +
+                                 "+ or -, not #{zone[0]}"
+        end
+        if zone.length != 5
+          raise TjException.new, "Time zone adjustment must use (+/-)HHMM format"
+        end
+
+        date = Time.utc(year, month, day, hour, minute, second)
+        sign = zone[0] == ?- ? 1 : -1
+        tzHour = zone[1..2].to_i
+        if tzHour < 0 || tzHour > 12
+          raise TjException.new, "Time zone adjustment hour out of range " +
+                                 "(0 - 12) but is #{tzHour}"
+        end
+        tzMinute = zone[3..4].to_i
+        if tzMinute < 0 || tzMinute > 59
+          raise TjException.new, "Time zone adjustment minute out of range " +
+                                 "(0 - 59) but is #{tzMinute}"
+        end
+        date += sign * (tzHour * 3600 + tzMinute * 60)
+      else
+        date = Time.mktime(year, month, day, hour, minute, second)
+      end
+
+      #puts "--> #{t}"
+      #puts(">>> #{year}-#{month}-#{day}-#{hour}:#{minute}:#{second}" +
+      #     "#{zone ? "-#{tzHour}:#{tzMinute}" : ""}")
+      #puts "=== #{date}"
+      TjTime.new(date)
+    end
+
     # Check if +zone+ is a valid time zone.
     def TjTime.checkTimeZone(zone)
       return true if zone == 'UTC'
@@ -80,7 +184,11 @@ class TaskJuggler
       region = zone[0..zone.index('/') - 1]
       res = (newZone != zone && newZone != region && newZone != 'UTC')
       # Restore TZ if it was set earlier.
-      ENV['TZ'] = tz if tz
+      if tz
+        ENV['TZ'] = tz
+      else
+        ENV.delete('TZ')
+      end
       res
     end
 

data/lib/TjpSyntaxRules.rb

@@ -155,7 +155,7 @@ EOT
     repeatable
 
     pattern(%w( _alternative !resourceId !moreAlternatives ), lambda {
-      ([ @val[1] ] + @val[2]).each do |candidate|
+      ([ @val[1] ] + (@val[2] ? @val[2] : [])).each do |candidate|
         @allocate.addCandidate(candidate)
       end
     })
@@ -558,7 +558,8 @@ EOT
 
     pattern(%w( _celltext !logicalExpression $STRING ), lambda {
       @column.cellText.addPattern(
-        CellSettingPattern.new(newRichText(@val[2]), @val[1]))
+        CellSettingPattern.new(newRichText(@val[2], @sourceFileInfo[2]),
+                               @val[1]))
     })
     doc('celltext.column', <<'EOT'
 Specifies an alternative content that is used for the cells of the column.
@@ -660,7 +661,8 @@ EOT
 
     pattern(%w( _tooltip !logicalExpression $STRING ), lambda {
       @column.tooltip.addPattern(
-        CellSettingPattern.new(newRichText(@val[2]), @val[1]))
+        CellSettingPattern.new(newRichText(@val[2], @sourceFileInfo[2]),
+                               @val[1]))
     })
     doc('tooltip.column', <<'EOT'
 Specifies an alternative content for the tooltip. This will replace the
@@ -742,15 +744,18 @@ EOT
       return if @val[1].empty?
 
       rtTokenSetMore =
-        %w( LINEBREAK SPACE WORD BOLD ITALIC CODE BOLDITALIC PRE HREF HREFEND
-            REF REFEND HLINE TITLE2 TITLE3 TITLE4 TITLE2END TITLE3END TITLE4END
-            BULLET1 BULLET2 BULLET3 BULLET4 NUMBER1 NUMBER2 NUMBER3 NUMBER4 )
+        [ :LINEBREAK, :SPACE, :WORD, :BOLD, :ITALIC, :CODE, :BOLDITALIC,
+          :PRE, :HREF, :HREFEND, :REF, :REFEND, :HLINE, :TITLE2, :TITLE3,
+          :TITLE4, :TITLE2END, :TITLE3END, :TITLE4END,
+          :BULLET1, :BULLET2, :BULLET3, :BULLET4, :NUMBER1, :NUMBER2, :NUMBER3,
+          :NUMBER4 ]
       if @val[1] == "Some more details\n"
         error('ts_default_details',
               "'Some more details' is not a valid value",
               @sourceFileInfo[1])
       end
-      @journalEntry.details = newRichText(@val[1], rtTokenSetMore)
+      @journalEntry.details = newRichText(@val[1], @sourceFileInfo[1],
+                                          rtTokenSetMore)
     })
     doc('details', <<'EOT'
 This is a continuation of the [[summary]] of the journal or status entry. It
@@ -1012,12 +1017,12 @@ EOT
     pattern(%w( !extendPropertyId ), lambda {
       case @val[0]
       when 'task'
-        @ruleToExtend = @rules['taskAttributes']
-        @ruleToExtendWithScenario = @rules['taskScenarioAttributes']
+        @ruleToExtend = @rules[:taskAttributes]
+        @ruleToExtendWithScenario = @rules[:taskScenarioAttributes]
         @propertySet = @project.tasks
       when 'resource'
-        @ruleToExtend = @rules['resourceAttributes']
-        @ruleToExtendWithScenario = @rules['resourceScenarioAttributes']
+        @ruleToExtend = @rules[:resourceAttributes]
+        @ruleToExtendWithScenario = @rules[:resourceScenarioAttributes]
         @propertySet = @project.resources
       end
     })
@@ -1218,7 +1223,7 @@ EOT
 
   def rule_headline
     pattern(%w( _headline $STRING ), lambda {
-      @property.set('headline', newRichText(@val[1]))
+      @property.set('headline', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('headline', <<'EOT'
 Specifies the headline for a report.
@@ -1316,6 +1321,11 @@ EOT
 
   def rule_includeFile
     pattern(%w( !includeFileName ), lambda {
+      unless @project
+        error('include_before_project',
+              "You must declare the project header before you include other " +
+              "files.")
+      end
       @project.inputFiles << @scanner.include(@val[0], @sourceFileInfo[0])
     })
   end
@@ -1690,7 +1700,7 @@ EOT
   def rule_listOfDays
     pattern(%w( !weekDayInterval !moreListOfDays), lambda {
       weekDays = Array.new(7, false)
-      ([ @val[0] ] + @val[1]).each do |dayList|
+      ([ @val[0] ] + (@val[1] ? @val[1] : [])).each do |dayList|
         7.times { |i| weekDays[i] = true if dayList[i] }
       end
       weekDays
@@ -1702,7 +1712,7 @@ EOT
       [ ]
     })
     pattern(%w( !timeInterval !moreTimeIntervals ), lambda {
-      [ @val[0] ] + @val[1]
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
     })
   end
 
@@ -2059,15 +2069,11 @@ EOT
   end
 
   def rule_operation
-    pattern(%w( !operand !operatorAndOperand !operationChain ), lambda {
+    pattern(%w( !operand !operationChain ), lambda {
       operation = LogicalOperation.new(@val[0])
-      unless @val[1].nil?
-        operation.operator = @val[1][0]
-        operation.operand2 = @val[1][1]
-      end
-      if @val[2]
+      if @val[1]
         # Further operators/operands create an operation tree.
-        @val[2].each do |ops|
+        @val[1].each do |ops|
           operation = LogicalOperation.new(operation)
           operation.operator = ops[0]
           operation.operand2 = ops[1]
@@ -2098,7 +2104,6 @@ EOT
   end
 
   def rule_operatorAndOperand
-    optional
     pattern(%w( !operator !operand), lambda{
       [ @val[0], @val[1] ]
     })
@@ -2193,7 +2198,7 @@ EOT
 
   def rule_outputFormats
     pattern(%w( !outputFormat !moreOutputFormats ), lambda {
-      [ @val[0] ] + @val[1]
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
     })
   end
 
@@ -2341,8 +2346,11 @@ impact on memory usage and scheduling performance. You should set this value
 to the minimum required resolution. Make sure that all values that you specify
 are aligned with the resolution.
 
-The timing resolution should be set prior to any value that represents a time
-value like now or workinghours.
+Changing the timing resolution will reset the [[workinghours.project|working
+hours]] to the default times. It's recommended that this is the very first
+option in the project header section.
+
+Do not use this option after you've set the time zone!
 EOT
         )
 
@@ -2394,8 +2402,7 @@ EOT
 
   def rule_projectHeader
     pattern(%w( _project !optionalID $STRING !optionalVersion !interval ), lambda {
-      @project = Project.new(@val[1], @val[2], @val[3],
-                                          @messageHandler)
+      @project = Project.new(@val[1], @val[2], @val[3], @messageHandler)
       @project['start'] = @val[4].start
       @project['end'] = @val[4].end
       @projectId = @val[1]
@@ -2409,7 +2416,7 @@ EOT
 
   def rule_projectIDs
     pattern(%w( $ID !moreProjectIDs ), lambda {
-      [ @val[0] ] + @val[1]
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
     })
   end
 
@@ -2499,8 +2506,7 @@ EOT
   end
 
   def rule_properties
-    pattern(%w( !propertiesBody . ))
-    lastSyntaxToken(1)
+    pattern(%w( !propertiesBody ))
   end
 
   def rule_propertiesBody
@@ -2628,8 +2634,12 @@ EOT
     example('TimeSheet1', '2')
   end
 
+  def rule_propertiesFile
+    pattern(%w( !propertiesBody . ))
+  end
+
   def rule_propertiesInclude
-    pattern(%w( _include !includeProperties !properties ), lambda {
+    pattern(%w( _include !includeProperties !properties . ), lambda {
     })
     doc('include.properties', <<'EOT'
 Includes the specified file name as if its contents would be written
@@ -2696,7 +2706,9 @@ EOT
   def rule_relativeId
     pattern(%w( _! !moreBangs !idOrAbsoluteId ), lambda {
       str = '!'
-      @val[1].each { |bang| str += bang }
+      if @val[1]
+        @val[1].each { |bang| str += bang }
+      end
       str += @val[2]
       str
     })
@@ -3019,7 +3031,7 @@ EOT
     })
 
     pattern(%w( _caption $STRING ), lambda {
-      @property.set('caption', newRichText(@val[1]))
+      @property.set('caption', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('caption', <<'EOT'
 The caption will be embedded in the footer of the table or data segment. The
@@ -3030,7 +3042,7 @@ EOT
     example('Caption', '1')
 
     pattern(%w( _center $STRING ), lambda {
-      @property.set('center', newRichText(@val[1]))
+      @property.set('center', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('center', <<'EOT'
 This attribute defines the center section of the [[textreport]]. The text will
@@ -3055,7 +3067,7 @@ EOT
     pattern(%w( !reportEnd ))
 
     pattern(%w( _epilog $STRING ), lambda {
-      @property.set('epilog', newRichText(@val[1]))
+      @property.set('epilog', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('epilog', <<'EOT'
 Define a text section that is printed right after the actual report data. The
@@ -3072,7 +3084,7 @@ EOT
        )
 
     pattern(%w( _footer $STRING ), lambda {
-      @property.set('footer', newRichText(@val[1]))
+      @property.set('footer', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('footer', <<'EOT'
 Define a text section that is put at the bottom of the report. The
@@ -3084,7 +3096,7 @@ EOT
     pattern(%w( !formats ))
 
     pattern(%w( _header $STRING ), lambda {
-      @property.set('header', newRichText(@val[1]))
+      @property.set('header', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('header', <<'EOT'
 Define a text section that is put at the top of the report. The
@@ -3099,7 +3111,7 @@ EOT
     pattern(%w( !hidetask ))
 
     pattern(%w( _left $STRING ), lambda {
-      @property.set('left', newRichText(@val[1]))
+      @property.set('left', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('left', <<'EOT'
 This attribute defines the left margin section of the [[textreport]]. The text
@@ -3119,7 +3131,7 @@ EOT
     pattern(%w( !reportPeriod ))
 
     pattern(%w( _prolog $STRING ), lambda {
-      @property.set('prolog', newRichText(@val[1]))
+      @property.set('prolog', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('prolog', <<'EOT'
 Define a text section that is printed right before the actual report data. The
@@ -3136,7 +3148,7 @@ EOT
     pattern(%w( !report ))
 
     pattern(%w( _right $STRING ), lambda {
-      @property.set('right', newRichText(@val[1]))
+      @property.set('right', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('right', <<'EOT'
 This attribute defines the right margin section of the [[textreport]]. The text
@@ -3145,6 +3157,16 @@ span the [[header]] or [[footer]] sections.
 EOT
        )
 
+    pattern(%w( _rollupresource !logicalExpression ), lambda {
+      @property.set('rollupResource', @val[1])
+    })
+    doc('rollupresource', <<'EOT'
+Do not show sub-resources of resources that match the specified logical
+expression.
+EOT
+       )
+    example('RollupResource')
+
     pattern(%w( _rolluptask !logicalExpression ), lambda {
       @property.set('rollupTask', @val[1])
     })
@@ -3178,16 +3200,29 @@ EOT
 
     pattern(%w( !reportStart ))
 
+    pattern(%w( _resourceroot !resourceId), lambda {
+      @property.set('resourceRoot', @val[1])
+    })
+    doc('resourceroot', <<'EOT'
+Only resources below the specified root-level resources are exported. The
+exported resources will have the ID of the root-level resource stripped from
+their ID, so that the sub-resourcess of the root-level resource become
+top-level resources in the report file.
+EOT
+       )
+    example('ResourceRoot')
+
     pattern(%w( _taskroot !taskId), lambda {
       @property.set('taskRoot', @val[1])
     })
     doc('taskroot', <<'EOT'
 Only tasks below the specified root-level tasks are exported. The exported
-tasks will have the id of the root-level task stripped from their ID, so that
-the sub-tasks of the root-level task become top-level tasks in the exported
+tasks will have the ID of the root-level task stripped from their ID, so that
+the sub-tasks of the root-level task become top-level tasks in the report
 file.
 EOT
        )
+    example('TaskRoot')
 
     pattern(%w( !timeformat ), lambda {
       @property.set('timeFormat', @val[0])
@@ -3365,14 +3400,21 @@ EOT
        )
   end
 
-
-
   def rule_reportType
     singlePattern('_resourcereport')
     doc('resourcereport', <<'EOT'
 The report lists resources and their respective values in a table. The task
-that are the resources are allocated to can be listed as well. See [[report]]
-for further details.
+that are the resources are allocated to can be listed as well. To reduce the
+list of included resources, you can use the [[hideresource]],
+[[rollupresource]] or [[resourceroot]] attributes. The order of the task can
+be controlled with [[sortresources]]. If the first sorting criteria is tree
+sorting, the parent resources will always be included to form the tree.
+Tree sorting is the default. You need to change it if you do not want certain
+parent resources to be included in the report.
+
+The tasks that the resources are allocated to can be included as well. Use the
+[[hidetask]] attribute for this. See [[report]] for a complete list of
+attributes and the full syntax for this keyword.
 EOT
        )
     singlePattern('_taskreport')
@@ -3381,12 +3423,13 @@ The report lists tasks and their respective values in a table. To reduce the
 list of included tasks, you can use the [[hidetask]], [[rolluptask]] or
 [[taskroot]] attributes. The order of the task can be controlled with
 [[sorttasks]]. If the first sorting criteria is tree sorting, the parent tasks
-will unconditionally be included to form the tree. Tree sorting is the
-default. You need to change it if you do not want certain parent tasks to be
-included in the report.
+will always be included to form the tree. Tree sorting is the default. You
+need to change it if you do not want certain parent tasks to be included in
+the report.
 
-The resources that are allocated to each task can be listed as well. See
-[[report]] for further details.
+The resources that are allocated to each task can be listed as well. Use the
+[[hideresource]] attribute for this. See [[report]] for a complete list of
+attributes and the full syntax for this keyword.
 EOT
        )
     singlePattern('_textreport')
@@ -3504,7 +3547,7 @@ EOT
 
   def rule_resourceLeafList
     pattern(%w( !leafResourceId !moreLeafResources ), lambda {
-      [ @val[0] ] + @val[1]
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
     })
   end
 
@@ -3542,7 +3585,7 @@ The booking attribute can be used to report completed work. This can be part
 of the necessary effort or the whole effort. When the scenario is scheduled in
 projection mode, TaskJuggler assumes that only the work reported with bookings
 has been done up to now. It then schedules a plan for the still missing
-effort. Task with bookings must be scheduled in ''''asap'''' mode.
+effort. All task with bookings must be scheduled in ''''asap'''' mode.
 
 This attribute is also used within export reports to describe the details of a
 scheduled project.
@@ -3550,6 +3593,12 @@ scheduled project.
 The sloppy attribute can be used when you want to skip non-working time or
 other allocations automatically. If it's not given, all bookings must only
 cover working time for the resource.
+
+The booking attributes is intended to capture the exact amount of completed
+work. This attribute is not really intended to specify completed effort by
+hand. Usually, booking statements are generated by [[export]] reports. The
+[[sloppy.booking|sloppy]] and [[overtime.booking|overtime]] attributes are
+only kludge for users who want to write them manually.
 EOT
        )
     also(%w( scheduling ))
@@ -4192,8 +4241,10 @@ EOT
                 @sourceFileInfo[1])
       end
       rtTokenSetIntro =
-        %w( LINEBREAK SPACE WORD BOLD ITALIC CODE BOLDITALIC HREF HREFEND )
-      @journalEntry.summary = newRichText(@val[1], rtTokenSetIntro)
+        [ :LINEBREAK, :SPACE, :WORD, :BOLD, :ITALIC, :CODE, :BOLDITALIC,
+          :HREF, :HREFEND ]
+      @journalEntry.summary = newRichText(@val[1], @sourceFileInfo[1],
+                                          rtTokenSetIntro)
     })
     doc('summary', <<'EOT'
 This is the introductory part of the journal or status entry. It should
@@ -4277,7 +4328,7 @@ EOT
     pattern(%w( !journalEntry ))
 
     pattern(%w( _note $STRING ), lambda {
-      @property.set('note', newRichText(@val[1]))
+      @property.set('note', newRichText(@val[1], @sourceFileInfo[1]))
     })
     doc('note.task', <<'EOT'
 Attach a note to the task. This is usually a more detailed specification of
@@ -4426,7 +4477,7 @@ EOT
 
   def rule_taskDepList
     pattern(%w( !taskDep !moreDepTasks ), lambda {
-      [ @val[0] ] + @val[1]
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
     })
   end
 
@@ -4439,7 +4490,7 @@ EOT
         id = (@property ? @property.fullId + '.' : '') + @val[1]
         if @project.task(id)
           error('task_exists', "Task #{id} has already been defined.",
-                @sourceFileInfo[1])
+                @sourceFileInfo[0])
         end
       end
       @property = Task.new(@project, @val[1], @val[2], @property)
@@ -4498,7 +4549,7 @@ EOT
 
   def rule_taskPredList
     pattern(%w( !taskPred !morePredTasks ), lambda {
-      [ @val[0] ] + @val[1]
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
     })
   end
 
@@ -5240,12 +5291,15 @@ possible values.
 The project start and end time are not affected by this setting. You
 have to explicitly state the time zone for those dates or the system defaults
 are assumed. Using the TZ environment variable is the recommended way to
-specify the time zone for your project. If you use this attribute within the
-project, it should be the very first thing you set. It must be set before you
-set the [[timingresolution]] or any attribute with a time or date.
+specify the time zone for your project.
 
 In case the specified time zone is not hour-aligned with UTC, the
-[[timingresolution]] will automatically be decreased.
+[[timingresolution]] will automatically be decreased accordingly. Do not
+change the timingresolution after you've set the time zone!
+
+Changing the time zone will reset the [[workinghours.project|working hours]]
+to the default times. It's recommended that you declare your working hours
+after the time zone.
 EOT
         )
     arg(1, 'zone', <<'EOT'
@@ -5664,15 +5718,17 @@ EOT
   def rule_workinghoursProject
     pattern(%w( !workinghours ))
     doc('workinghours.project', <<'EOT'
-Set the default working hours for all subsequent resource definitions.
-The working hours specification limits the availability of resources to
-certain time slots of week days.
+Set the default working hours for all subsequent resource definitions. The
+standard working hours are 9:00am - 12:00am, 1:00pm - 18:00pm, Monday to
+Friday. The working hours specification limits the availability of resources
+to certain time slots of week days.
 
 These default working hours can be replaced with other working hours for
 individual resources.
 EOT
        )
     also(%w( dailyworkinghours workinghours.resource workinghours.shift ))
+    example('Project')
   end
 
   def rule_workinghoursResource