taskjuggler 3.2.0 → 3.3.0

data/lib/taskjuggler/TextParser.rb

@@ -339,7 +339,8 @@ class TaskJuggler
             # the syntax rules.
             error("no_reduce",
                   "Unexpected token '#{token[1]}' found. " +
-                  "Expecting one of " +
+                  "Expecting #{@stack.last.state.expectedTokens.length > 1 ?
+                               'one of ' : ''}" +
                   "#{@stack.last.state.expectedTokens.join(', ')}",
                   @scanner.sourceFileInfo)
           end
@@ -428,8 +429,8 @@ class TaskJuggler
             end
           end
         end
-        print " -> #{sl.state ? sl.state.to_s(true) : 'nil'} #{sl.function.nil? ? '' : '(Called)'}"
-        puts ""
+        puts " -> #{sl.state ? sl.state.to_s(true) : 'nil'}" +
+             "#{sl.function.nil? ? '' : '(Called)'}"
       end
     end
 

data/lib/taskjuggler/TextParser/MacroTable.rb

@@ -62,9 +62,11 @@ class TaskJuggler::TextParser
       resolved = @macros[name].value.dup
       i = 0
       args.each do |arg|
-        resolved.gsub!("${#{i}}", arg)
+        resolved.gsub!(Regexp.new("(([^$]|^))\\$\\{#{i}\\}"), "\\1#{arg}")
         i += 1
       end
+      # Remove the escape character from all the escaped '${...}'.
+      resolved.gsub!('$${', '${')
       [ @macros[name], resolved ]
     end
 

data/lib/taskjuggler/TextParser/Scanner.rb

@@ -84,12 +84,11 @@ class TaskJuggler::TextParser
         @line = preCall + text + @scanner.post_match
         # Start the StringScanner again at the first character of the injected
         # text.
-        @scanner = StringScanner.new(@line)
+        @scanner.string = @line
         @scanner.pos = preCall.bytesize
       end
 
       def injectMacro(macro, args, text, callLength)
-        # We add 3 chars more for the ${}.
         injectText(text, callLength)
 
         # Simple detection for recursive macro calls.
@@ -99,7 +98,7 @@ class TaskJuggler::TextParser
         true
       end
 
-      def scan(re)
+      def readyNextLine
         # We read the file line by line with gets(). If we don't have a line
         # yet or we've reached the end of a line, we get the next one.
         if @scanner.nil? || @scanner.eos?
@@ -109,15 +108,20 @@ class TaskJuggler::TextParser
           else
             # We've reached the end of the current file.
             @scanner = nil
-            # Return special EOF symbol.
-            return :scannerEOF
+            return false
           end
           @scanner = StringScanner.new(@line)
           @wrapped = @line[-1] == ?\n
         end
-        return nil if (token = @scanner.scan(re)).nil?
-        #puts "#{re.to_s[0..20]}: [#{token}]"
 
+        true
+      end
+
+      def scan(re)
+        @scanner.scan(re)
+      end
+
+      def cleanupMacroStack
         if @nextMacroEnd
           pos = @scanner.pos
           while @nextMacroEnd && @nextMacroEnd < pos
@@ -125,8 +129,6 @@ class TaskJuggler::TextParser
             @nextMacroEnd = @macroStack.empty? ? nil : @macroStack.last.endPos
           end
         end
-
-        token
       end
 
       def peek(n)
@@ -240,9 +242,9 @@ class TaskJuggler::TextParser
       tokenPatterns.each do |pat|
         type = pat[0]
         regExp = pat[1]
-        mode = pat[2] || :tjp
-        postProc = pat[3]
-        addPattern(type, regExp, mode, postProc)
+        mode = pat[3] || :tjp
+        postProc = pat[4]
+        addPattern(type, Regexp.new(regExp), mode, postProc)
       end
       self.mode = defaultMode
     end
@@ -415,52 +417,7 @@ class TaskJuggler::TextParser
         end
       end
 
-      # Start processing characters from the input.
-      @startOfToken = sourceFileInfo
-      loop do
-        match = nil
-        begin
-          @activePatterns.each do |type, re, postProc|
-            if (match = @cf.scan(re))
-              if match == :scannerEOF
-                if @scannerMode != @defaultMode
-                  # The stream resets the line number to 1. Since we still
-                  # know the start of the token, we setup @lineDelta so that
-                  # sourceFileInfo() returns the proper line number.
-                  @lineDelta = -(@startOfToken.lineNo - 1)
-                  error('runaway_token',
-                        "Unterminated token starting at #{@startOfToken}")
-                end
-                # We've found the end of an input file. Return a special token
-                # that describes the end of a file.
-                @finishLastFile = true
-                return [ :eof, '<END>', @startOfToken ]
-              end
-
-              raise "#{re} matches empty string" if match.empty?
-              # If we have a post processing method, call it now. It may modify
-              # the type or the found token String.
-              type, match = postProc.call(type, match) if postProc
-
-              break if type.nil? # Ignore certain tokens with nil type.
-
-              return [ type, match, @startOfToken ]
-            end
-          end
-        rescue ArgumentError
-          error('scan_encoding_error', $!.to_s)
-        end
-
-        if match.nil?
-          if @cf.eof?
-            error('unexpected_eof',
-                  "Unexpected end of file found")
-          else
-            error('no_token_match',
-                  "Unexpected characters found: '#{@cf.peek(10)}...'")
-          end
-        end
-      end
+      scanToken
     end
 
     # Return a token to retrieve it with the next nextToken() call again. Only 1
@@ -515,6 +472,64 @@ class TaskJuggler::TextParser
 
     private
 
+    def scanToken
+      @startOfToken = sourceFileInfo
+      begin
+        match = nil
+        loop do
+          # First make sure that the line buffer has been filled and we have a
+          # line to parse.
+          unless @cf.readyNextLine
+            if @scannerMode != @defaultMode
+              # The stream resets the line number to 1. Since we still
+              # know the start of the token, we setup @lineDelta so that
+              # sourceFileInfo() returns the proper line number.
+              @lineDelta = -(@startOfToken.lineNo - 1)
+              error('runaway_token',
+                    "Unterminated token starting at line #{@startOfToken}")
+            end
+            # We've found the end of an input file. Return a special token
+            # that describes the end of a file.
+            @finishLastFile = true
+            return [ :eof, '<END>', @startOfToken ]
+          end
+
+          @activePatterns.each do |type, re, postProc|
+            if (match = @cf.scan(re))
+              #raise "#{re} matches empty string" if match.empty?
+              # If we have a post processing method, call it now. It may modify
+              # the type or the found token String.
+              type, match = postProc.call(type, match) if postProc
+
+              break if type.nil? # Ignore certain tokens with nil type.
+
+              @cf.cleanupMacroStack
+              return [ type, match, @startOfToken ]
+            end
+          end
+
+          if match.nil?
+            # If we haven't found a match, we either hit EOF or a token we did
+            # not expect.
+            if @cf.eof?
+              error('unexpected_eof',
+                    "Unexpected end of file found")
+            else
+              error('no_token_match',
+                    "Unexpected characters found: '#{@cf.peek(10)}...'")
+            end
+          else
+            # Remove completely scanned expanded macros from stack.
+            @cf.cleanupMacroStack
+          end
+        end
+      rescue ArgumentError
+        # This is triggered by StringScanner.scan, but we don't want to put
+        # the block in the inner loops for performance reasons.
+        error('scan_encoding_error', $!.to_s)
+      end
+    end
+
     def message(type, id, text, sfi, data)
       unless text.empty?
         line = @cf ? @cf.line : nil

data/lib/taskjuggler/Tj3Config.rb

@@ -14,7 +14,7 @@
 require 'taskjuggler/UTF8String'
 require 'taskjuggler/AppConfig'
 
-AppConfig.version = '3.2.0'
+AppConfig.version = '3.3.0'
 AppConfig.packageName = 'taskjuggler'
 AppConfig.softwareName = 'TaskJuggler'
 AppConfig.packageInfo = 'A Project Management Software'

data/lib/taskjuggler/TjpSyntaxRules.rb

@@ -247,6 +247,11 @@ exactly it will be assigned to the task. Shifts and limits can be used to
 restrict the allocation to certain time intervals or to limit them to a
 certain maximum per time period. The purge statement can be used to remove
 inherited allocations or flags.
+
+For effort-based tasks the task duration is clipped to only extend from the
+begining of the first allocation to the end of the last allocation. This is
+done to optimize for an overall minimum project duration as dependent tasks
+can potentially use the unallocated, clipped slots.
 EOT
        )
     example('Allocate-1', '1')
@@ -611,7 +616,7 @@ consists of one or more accounts. Each account must be a leaf account. The
 account ID may be followed by a percentage value that determines the share for
 this account. The total percentage of all accounts must be exactly 100%. If
 some accounts don't have a percentage specification, the remainder to 100% is
-distributed evenly to them.
+distributed evenly between them.
 EOT
        )
   end
@@ -731,7 +736,7 @@ which cells the text should be used. If multiple celltext patterns are
 provided for a column, the first matching one is taken for each cell.
 EOT
         )
-    arg(1, 'text',
+    arg(2, 'text',
         'Alterntive cell text specified as [[Rich_Text_Attributes|Rich Text]]')
 
     pattern(%w( _cellcolor !logicalExpression !color ), lambda {
@@ -1012,7 +1017,7 @@ EOT
 
   def rule_export
     pattern(%w( !exportHeader !exportBody ), lambda {
-      @property = nil
+      @property = @property.parent
     })
     doc('export', <<'EOT'
 The export report looks like a regular TaskJuggler file with the provided
@@ -1033,30 +1038,6 @@ EOT
     example('Export')
   end
 
-  def rule_exportHeader
-    pattern(%w( _export !optionalID $STRING ), lambda {
-      newReport(@val[1], @val[2], :export, @sourceFileInfo[0])
-      @property.set('formats', [ :tjp ])
-
-      # By default, we export all scenarios.
-      scenarios = Array.new(@project.scenarios.items) { |i| i }
-      scenarios.delete_if { |sc| !@project.scenario(sc).get('active') }
-      @property.set('scenarios', scenarios)
-      # Show all tasks, sorted by seqno-up.
-      @property.set('hideTask', LogicalExpression.new(LogicalOperation.new(0)))
-      @property.set('sortTasks', [ [ 'seqno', true, -1 ] ])
-      # Show all resources, sorted by seqno-up.
-      @property.set('hideResource',
-                    LogicalExpression.new(LogicalOperation.new(0)))
-      @property.set('sortResources', [ [ 'seqno', true, -1 ] ])
-    })
-    arg(2, 'file name', <<'EOT'
-The name of the report file to generate. It must end with a .tjp or .tji
-extension, or use . to use the standard output channel.
-EOT
-       )
-  end
-
   def rule_exportAttributes
     optional
     repeatable
@@ -1078,10 +1059,26 @@ EOT
                            'projecids' => 'Include project IDs',
                            'tasks' => 'Include task definitions',
                            'resources' => 'Include resource definitions' })
+
+    pattern(%w( _formats !exportFormats ), lambda {
+      @property.set('formats', @val[1])
+    })
+    level(:beta)
+    doc('formats.export', <<'EOT'
+This attribute defines for which output formats the export report should be
+generated. By default, the TJP format will be used.
+EOT
+       )
+
     pattern(%w( !hideresource ))
     pattern(%w( !hidetask ))
+
+    pattern(%w( !loadunit ))
+
+    pattern(%w( !purge ))
     pattern(%w( !reportEnd ))
     pattern(%w( !reportPeriod ))
+    pattern(%w( !reports ))
     pattern(%w( !reportStart ))
 
     pattern(%w( _resourceattributes !exportableResourceAttributes ), lambda {
@@ -1131,6 +1128,24 @@ EOT
                            'priority' => 'Include priorities',
                            'responsible' => 'Include responsible resource' })
 
+    pattern(%w( _taskroot !taskId), lambda {
+      if @val[1].leaf?
+        error('taskroot_leaf',
+              "#{@val[1].fullId} is not a container task",
+              @sourceFileInfo[1])
+      end
+      @property.set('taskroot', @val[1])
+    })
+    level(:experimental)
+    doc('taskroot.export', <<'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 report
+file.
+EOT
+       )
+    example('TaskRoot')
+
     pattern(%w( _timezone !validTimeZone ), lambda {
       @property.set('timezone', @val[1])
     })
@@ -1142,6 +1157,72 @@ EOT
     optionsRule('exportAttributes')
   end
 
+  def rule_exportFormat
+    pattern(%w( _tjp ), lambda {
+      :tjp
+    })
+    descr('Export of the scheduled project in TJP syntax.')
+
+    pattern(%w( _mspxml ), lambda {
+      :mspxml
+    })
+    descr(<<'EOT'
+Export of the scheduled project in Microsoft Project XML format. This will
+export the data of the fully scheduled project. The exported data include the
+tasks, resources and the assignments of resources to task. This is only a
+small subset of the data that TaskJuggler can manage. This export is intended
+to share resource assignment data with other teams using Microsoft Project.
+TaskJuggler manages assignments with a larger accuracy than the Microsft
+Project XML format can represent. This will inevitably lead to some rounding
+errors and different interpretation of the data. The numbers you will see in
+Project are not necessarily an exact match of the numbers you see in
+TaskJuggler.
+EOT
+         )
+  end
+
+  def rule_exportFormats
+    pattern(%w( !exportFormat !moreExportFormats ), lambda {
+      [ @val[0] ] + (@val[1].nil? ? [] : @val[1])
+    })
+  end
+
+  def rule_exportHeader
+    pattern(%w( _export !optionalID $STRING ), lambda {
+      newReport(@val[1], @val[2], :export, @sourceFileInfo[0])
+      unless @property.modified?('formats')
+        @property.set('formats', [ :tjp ])
+      end
+
+      # By default, we export all scenarios.
+      unless @property.modified?('scenarios')
+        scenarios = Array.new(@project.scenarios.items) { |i| i }
+        scenarios.delete_if { |sc| !@project.scenario(sc).get('active') }
+        @property.set('scenarios', scenarios)
+      end
+      # Show all tasks, sorted by seqno-up.
+      unless @property.modified?('hideTask')
+        @property.set('hideTask', LogicalExpression.new(LogicalOperation.new(0)))
+      end
+      unless @property.modified?('sortTasks')
+        @property.set('sortTasks', [ [ 'seqno', true, -1 ] ])
+      end
+      # Show all resources, sorted by seqno-up.
+      unless @property.modified?('hideResource')
+        @property.set('hideResource',
+                      LogicalExpression.new(LogicalOperation.new(0)))
+      end
+      unless @property.modified?('sortResources')
+        @property.set('sortResources', [ [ 'seqno', true, -1 ] ])
+      end
+    })
+    arg(2, 'file name', <<'EOT'
+The name of the report file to generate. It must end with a .tjp or .tji
+extension, or use . to use the standard output channel.
+EOT
+       )
+  end
+
   def rule_extendAttributes
     optional
     repeatable
@@ -1912,12 +1993,23 @@ EOT
         error('zero_duration', "The interval duration may not be 0.",
               @sourceFileInfo[1])
       end
-      duration = @val[0] * convFactors[@val[1]]
+      duration = (@val[0] * convFactors[@val[1]]).to_i
       resolution = @project.nil? ? 60 * 60 : @project['scheduleGranularity']
+      if @val[1] == 4
+        # If the duration unit is months, we have to align the duration with
+        # the timing resolution of the project.
+        duration = (duration / resolution).to_i * resolution
+      end
       # Make sure the interval aligns with the timing resolution.
-      (duration / resolution).to_i * resolution
+      if duration % resolution != 0
+        error('iv_duration_not_aligned',
+              "The interval duration must be a multiple of the specified " +
+              "timing resolution (#{resolution / 60} min) of the project.")
+      end
+      duration
     })
-    arg(0, 'duration', 'The duration of the interval. May not be 0.')
+    arg(0, 'duration', 'The duration of the interval. May not be 0 and must ' +
+                       'be a multiple of [[timingresolution]].')
   end
 
   def rule_intervalEnd
@@ -1993,6 +2085,14 @@ EOT
 This mode only yields entries if used in the context of a task. It contains
 all journal entries that are dated in the query interval for the task and all
 its sub tasks.
+EOT
+       )
+    pattern(%w( _status_dep ), lambda { :status_dep })
+    descr(<<'EOT'
+In this mode only the last entries before the report end date for each
+property and all its sub-properties and their dependencies are included. If
+there are multiple entries at the exact same date, then all these entries are
+included.
 EOT
        )
     pattern(%w( _status_down ), lambda { :status_down })
@@ -2009,6 +2109,16 @@ property are included. If there are multiple entries at the exact same date,
 then all these entries are included. If any of the parent properties has a
 more recent entry that is still before the report end date, no entries will be
 included.
+EOT
+       )
+    pattern(%w( _alerts_dep ), lambda { :alerts_dep })
+    descr(<<'EOT'
+In this mode only the last entries before the report end date for the context
+property and all its sub-properties and their dependencies is included. If
+there are multiple entries at the exact same date, then all these entries are
+included. In contrast to the ''''status_down'''' mode, only entries with an
+alert level above the default level, and only those with the highest overall
+alert level are included.
 EOT
        )
     pattern(%w( _alerts_down ), lambda { :alerts_down })
@@ -2412,6 +2522,16 @@ EOT
   end
 
   def rule_loadunit
+    pattern(%w( _loadunit !loadunitName ), lambda {
+      @property.set('loadUnit', @val[1])
+    })
+    doc('loadunit', <<'EOT'
+Determines what unit should be used to display all load values in this report.
+EOT
+       )
+  end
+
+  def rule_loadunitName
     pattern([ '_days' ], lambda { :days })
     descr('Display all load and duration values as days.')
 
@@ -2455,7 +2575,7 @@ EOT
       LogicalExpression.new(@val[0], sourceFileInfo)
     })
     pattern(%w( _@ !allOrNone ), lambda {
-      LogicalOperation.new(@val[1])
+      LogicalExpression.new(LogicalOperation.new(@val[1]), sourceFileInfo)
     })
     doc('logicalexpression', <<'EOT'
 A logical expression is a combination of operands and mathematical operations.
@@ -2559,6 +2679,10 @@ EOT
     commaListRule('!taskDep')
   end
 
+  def rule_moreExportFormats
+    commaListRule('!exportFormat')
+  end
+
   def rule_moreJournalSortCriteria
     commaListRule('!journalSortCriterium')
   end
@@ -2909,6 +3033,17 @@ EOT
       @val[0] / 100.0
     })
   end
+  def rule_optionalScenarioIdCol
+    optional
+    pattern(%w( $ID_WITH_COLON ), lambda {
+      if (@scenarioIdx = @project.scenarioIdx(@val[0])).nil?
+        error('unknown_scenario_id', "Unknown scenario: #{@val[0]}",
+              @sourceFileInfo[0])
+      end
+      @scenarioIdx
+    })
+  end
+
 
   def rule_optionalVersion
     optional
@@ -3447,21 +3582,27 @@ EOT
   end
 
   def rule_purge
-    pattern(%w( _purge $ID ), lambda {
-      if (attributeDefinition = @property.attributeDefinition(@val[1])).nil?
+    pattern(%w( _purge !optionalScenarioIdCol $ID ), lambda {
+      attrId = @val[2]
+      if (attributeDefinition = @property.attributeDefinition(attrId)).nil?
         error('purge_unknown_id',
-              "#{@val[1]} is not a known attribute for this property",
-              @sourceFileInfo[1])
+              "#{attrId} is not a known attribute for this property",
+              @sourceFileInfo[2])
       end
       if attributeDefinition.scenarioSpecific
-        attr = @property[@val[1], 0]
+        @scenarioIdx = 0 unless @val[1]
+        attr = @property[attrId, 0]
       else
-        attr = @property.get(@val[1])
+        if @val[1]
+          error('purge_non_sc_spec_attr',
+                'Scenario specified for a non-scenario specific attribute')
+        end
+        attr = @property.get(attrId)
       end
-      if @property.attributeDefinition(@val[1]).scenarioSpecific
-        @property.getAttribute(@val[1], @scenarioIdx).reset
+      if @property.attributeDefinition(attrId).scenarioSpecific
+        @property.getAttribute(attrId, @scenarioIdx).reset
       else
-        @property.getAttribute(@val[1]).reset
+        @property.getAttribute(attrId).reset
       end
     })
     doc('purge', <<'EOT'
@@ -3475,6 +3616,10 @@ the list that was inherited from the enclosing property. The purge
 attribute resets any attribute to its default value. A subsequent definition
 for the attribute within the property will then add their values to an empty
 list. The value of the enclosing property is not affected by purge.
+
+For scenario specific attributes, an optional scenario ID can be specified
+before the attribute ID. If it's missing, the default (first) scenario will be
+used.
 EOT
        )
     arg(1, 'attribute', 'Any name of a list attribute')
@@ -3506,6 +3651,7 @@ EOT
 
   def rule_reports
     pattern(%w( !accountReport ))
+    pattern(%w( !export ))
     pattern(%w( !resourceReport ))
     pattern(%w( !taskReport ))
     pattern(%w( !textReport ))
@@ -3524,14 +3670,14 @@ EOT
     singlePattern('_annualleave')
     descr(<<'EOT'
 The number of annual leave units within the reported time period. The unit
-can be adjusted with [[loadunit]].
+can be adjusted with [[loadunit.report]].
 EOT
          )
 
     singlePattern('_annualleavebalance')
     descr(<<'EOT'
 The balance of the annual leave at the end of the reporting interval. The unit
-can be adjusted with [[loadunit]].
+can be adjusted with [[loadunit.report]].
 EOT
          )
 
@@ -3880,14 +4026,14 @@ EOT
     singlePattern('_sickleave')
     descr(<<'EOT'
 The number of sick leave units within the reported time period. The unit can
-be adjusted with [[loadunit]].
+be adjusted with [[loadunit.report]].
 EOT
          )
 
     singlePattern('_specialleave')
     descr(<<'EOT'
 The number of special leave units within the reported time period. The unit
-can be adjusted with [[loadunit]].
+can be adjusted with [[loadunit.report]].
 EOT
          )
 
@@ -3921,7 +4067,7 @@ EOT
     singlePattern('_unpaidleave')
     descr(<<'EOT'
 The number of unpaid leave units within the reported time period. The unit
-can be adjusted with [[loadunit]].
+can be adjusted with [[loadunit.report]].
 EOT
          )
 
@@ -4084,13 +4230,7 @@ EOT
        )
     example('textreport')
 
-    pattern(%w( _loadunit !loadunit ), lambda {
-      @property.set('loadUnit', @val[1])
-    })
-    doc('loadunit', <<'EOT'
-Determines what unit should be used to display all load values in this report.
-EOT
-       )
+    pattern(%w( !loadunit ))
 
     pattern(%w( !numberFormat ), lambda {
       @property.set('numberFormat', @val[0])
@@ -4308,7 +4448,6 @@ EOT
   end
 
   def rule_reportProperties
-    pattern(%w( !export ))
     pattern(%w( !iCalReport ))
     pattern(%w( !nikuReport ))
     pattern(%w( !reports ))
@@ -4393,7 +4532,7 @@ EOT
     })
 
     pattern(%w( _supplement !resourceId !resourceBody ), lambda {
-      @property = @property.parent
+      @property = @idStack.pop
     })
     doc('supplement.resource', <<'EOT'
 The supplement keyword provides a mechanism to add more attributes to already
@@ -5416,21 +5555,22 @@ EOT
 
   def rule_supplement
     pattern(%w( !supplementAccount !accountBody ), lambda {
-      @property = nil
+      @property = @idStack.pop
     })
     pattern(%w( !supplementReport !reportBody ), lambda {
-      @property = nil
+      @property = @idStack.pop
     })
     pattern(%w( !supplementResource !resourceBody ), lambda {
-      @property = nil
+      @property = @idStack.pop
     })
     pattern(%w( !supplementTask !taskBody ), lambda {
-      @property = nil
+      @property = @idStack.pop
     })
   end
 
   def rule_supplementAccount
     pattern(%w( _account !accountId ), lambda {
+      @idStack.push(@property)
       @property = @val[1]
     })
     arg(1, 'account ID', 'The ID of an already defined account.')
@@ -5438,6 +5578,7 @@ EOT
 
   def rule_supplementReport
     pattern(%w( _report !reportId ), lambda {
+      @idStack.push(@property)
       @property = @val[1]
     })
     arg(1, 'report ID', 'The absolute ID of an already defined report.')
@@ -5445,6 +5586,7 @@ EOT
 
   def rule_supplementResource
     pattern(%w( _resource !resourceId ), lambda {
+      @idStack.push(@property)
       @property = @val[1]
     })
     arg(1, 'resource ID', 'The ID of an already defined resource.')
@@ -5452,6 +5594,7 @@ EOT
 
   def rule_supplementTask
     pattern(%w( _task !taskId ), lambda {
+      @idStack.push(@property)
       @property = @val[1]
     })
     arg(1, 'task ID', 'The absolute ID of an already defined task.')
@@ -5533,13 +5676,16 @@ EOT
     })
     level(:experimental)
     doc('adopt.task', <<'EOT'
-Add a previously defined task to the sub-tasks of this task. This can be used
-to create virtual sub projects that contain of task trees that were defined as
-sub tasks of other tasks. Adopted tasks don't inherit anything from their step
-parents. However, the adopting task is scheduled to fit all adopted childs as
-well.
+Add a previously defined task and its sub-tasks to this task. This can be used
+to create virtual projects that contain task (sub-)trees that are originally
+defined in another task context. Adopted tasks don't inherit anything from
+their step parents. However, the adopting task is scheduled to fit all adopted
+sub-tasks.
 
-A top-level tasks must never include the same task more than once.
+A top-level task and all its sub-tasks must never contain the same task more
+than once. All reports must use appropriate filters by setting [[taskroot]],
+[[hidetask]] or [[rolluptask]] to ensure that no tasks are contained more than
+once in the report.
 EOT
        )
 
@@ -5557,7 +5703,7 @@ EOT
     pattern(%w( !purge ))
 
     pattern(%w( _supplement !supplementTask !taskBody ), lambda {
-      @property = @property.parent
+      @property = @idStack.pop
     })
     doc('supplement.task', <<'EOT'
 The supplement keyword provides a mechanism to add more attributes to already
@@ -6245,8 +6391,10 @@ EOT
       @property['scheduled', @scenarioIdx] = true
     })
     doc('scheduled', <<'EOT'
-This is mostly for internal use. It specifies that the task can be ignored for
-scheduling in the scenario.
+This is mostly for internal use. It specifies that the task should be ignored
+for scheduling in the scenario. This option only makes sense if you provide
+all resource [[booking.resource|bookings]] manually. Without booking
+statements, the task will be reported with 0 effort and no resources assigned.
 EOT
        )