writerfilter/source/ooxml/README.efforts

   1 #
   2 # This file is part of the LibreOffice project.
   3 #
   4 # This Source Code Form is subject to the terms of the Mozilla Public
   5 # License, v. 2.0. If a copy of the MPL was not distributed with this
   6 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   7 #
   8 # This file incorporates work covered by the following license notice:
   9 #
  10 #   Licensed to the Apache Software Foundation (ASF) under one or more
  11 #   contributor license agreements. See the NOTICE file distributed
  12 #   with this work for additional information regarding copyright
  13 #   ownership. The ASF licenses this file to you under the Apache
  14 #   License, Version 2.0 (the "License"); you may not use this file
  15 #   except in compliance with the License. You may obtain a copy of
  16 #   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  17 #
  18
  19 This file describes how the remaining efforts for writerfilter can be
  20 extracted from the source code.
  21
  22 1. Marking up the efforts in the code.
  23
  24 Efforts are marked up in the code with comments like this:
  25
  26 /* WRITERFILTERSTATUS: done: <percent done>, planned: <effort planned>, spent: <effort spent, yet> */
  27
  28 The comments have to follow a case-label immediately. Consecutive
  29 case-labels can be marked up, too. In the latter case the efforts are
  30 counted for the preceeding case-labels as a whole.
  31
  32 2. Extraction process
  33
  34 2.1. Stage 1:
  35
  36 This stage is handled in status.sh. An XML-file is generated that
  37 contains a top level element <stage1>. <stage1> contains an element
  38 <analyze> and several <qname> and <status> elements.
  39
  40 2.1.1.  Use analyzemodel.xsl to extract necessary data from model.xml.
  41
  42 - Namespaces can be flagged with attribute @todo="ignore" to prevent
  43   the namespace being considered.
  44
  45 - For every <element>/<attribute> an entry in an according element in <analyze> is genereated. These elements look like this:
  46
  47 <attribute id="..." resource="..." tokenid="..." qname="..." namespace="..." define="..." name="..."/>
  48
  49 Important for the extraction of efforts: @qname is the identifier used
  50 in case-labels in .cxx files and thus links the status mark up
  51 comments with elements/attributes in the model.xml.
  52
  53 2.1.2. Extract status information
  54
  55 The variable SEARCHIN in status.sh determines in what directory the script will search for case labels and status comments. Only .cxx files are searched. Lines like this
  56
  57 case NS_rtf::LN_UNUSED4:
  58
  59 result in elements like this
  60
  61 <qname file="/DomainMapper.cxx" line="216" qname="NS_rtf::LN_UNUSED4"/>.
  62
  63 Lines like this
  64
  65 /* WRITERFILTERSTATUS: done: 0, planned: 0, spent: 0 */
  66
  67 result in elements like this
  68
  69 <status done="0" planned="0" spent="0"/>
  70
  71 The <qname> and <status> elements are children of the <stage1>
  72 element. The are inserted in the same order as found in the
  73 code. Therefore a <status> element corresponds to the group of
  74 consecutive preceding <qname> elements.
  75
  76 2.2. Stage 2
  77
  78 In this stage analyzestage2.xsl is used on the result of stage 1 to
  79 group the <qname> and <status> elements from stage 1. For each
  80 <status> element a <qnames> element is generated that contains the
  81 <qname> elements that the <status> element refers to, plus the
  82 <status> element.
  83
  84 2.3. Stage 3
  85
  86 This stage associates the <attribute> and <element> elements in
  87 model.xml with the extracted data. It uses analyzestage3.xsl on the
  88 result of stage 2 to do this.
  89
  90 E.g. for given elements from stage 2:
  91
  92 <attribute
  93            id="dml-wordprocessingDrawing:CT_Inline:distR"
  94            resource="Properties"
  95            tokenid="ooxml:CT_Inline_distR"
  96            qname="NS_ooxml::LN_CT_Inline_distR"
  97            namespace="dml-wordprocessingDrawing"
  98            define="CT_Inline"
  99            name="distR"/>
 100
 101 and
 102
 103    <qnames>
 104     <qname file="/GraphicImport.cxx" line="1078" qname="NS_ooxml::LN_CT_Inline_distT"/>
 105     <qname file="/GraphicImport.cxx" line="1079" qname="NS_ooxml::LN_CT_Inline_distB"/>
 106     <qname file="/GraphicImport.cxx" line="1080" qname="NS_ooxml::LN_CT_Inline_distL"/>
 107     <qname file="/GraphicImport.cxx" line="1081" qname="NS_ooxml::LN_CT_Inline_distR"/>
 108     <status done="0" planned="0.5" spent="0"/>
 109   </qnames>
 110
 111 the result of stage 3 will be
 112
 113   <attribute
 114              id="dml-wordprocessingDrawing:CT_Inline:distR"
 115              resource="Properties"
 116              tokenid="ooxml:CT_Inline_distR"
 117              qname="NS_ooxml::LN_CT_Inline_distR"
 118              namespace="dml-wordprocessingDrawing"
 119              define="CT_Inline" name="distR">
 120
 121              <file name="/GraphicImport.cxx" line="1081">
 122                    <status done="0" planned="0.5" spent="0" qname-count="4"/>
 123              </file>
 124
 125   </attribute>
 126
 127 @qname-count is the number of case-labels that the according mark-up comment refers to.
 128
 129 3. Collect efforts
 130
 131 This is done by the script efforts.sh. It uses status.sh to extract the status and determines the efforts in two steps.
 132
 133 3.1. Choose which <attribute>/<element> elements need effort
 134
 135 This stage uses todo.xsl on the result of 2.3.
 136
 137 There are two criteria that imply effort:
 138
 139 - The <attribute>/<element> is not handled in any file.
 140
 141 - The status for the <attribute>/<element> declares that work is
 142   planned for it and less than 100 percent of this work is done.
 143
 144 3.2. Generate table of efforts in CSV format
 145
 146 This stage uses effort.xsl on the results of 3.1. and produces the
 147 table of efforts. If there is no status defined for an
 148 <attribute>/<element> it is assumed that the planned effort is 0.5
 149 hours and no work has been done.