130cfceefSAndrew Rist# ************************************************************* 230cfceefSAndrew Rist# 330cfceefSAndrew Rist# Licensed to the Apache Software Foundation (ASF) under one 430cfceefSAndrew Rist# or more contributor license agreements. See the NOTICE file 530cfceefSAndrew Rist# distributed with this work for additional information 630cfceefSAndrew Rist# regarding copyright ownership. The ASF licenses this file 730cfceefSAndrew Rist# to you under the Apache License, Version 2.0 (the 830cfceefSAndrew Rist# "License"); you may not use this file except in compliance 930cfceefSAndrew Rist# with the License. You may obtain a copy of the License at 1030cfceefSAndrew Rist# 1130cfceefSAndrew Rist# http://www.apache.org/licenses/LICENSE-2.0 1230cfceefSAndrew Rist# 1330cfceefSAndrew Rist# Unless required by applicable law or agreed to in writing, 1430cfceefSAndrew Rist# software distributed under the License is distributed on an 1530cfceefSAndrew Rist# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 1630cfceefSAndrew Rist# KIND, either express or implied. See the License for the 1730cfceefSAndrew Rist# specific language governing permissions and limitations 1830cfceefSAndrew Rist# under the License. 1930cfceefSAndrew Rist# 2030cfceefSAndrew Rist# ************************************************************* 21cdf0e10cSrcweirThis file describes how the remaining efforts for writerfilter can be 22cdf0e10cSrcweirextracted from the source code. 23cdf0e10cSrcweir 24cdf0e10cSrcweir1. Marking up the efforts in the code. 25cdf0e10cSrcweir 26cdf0e10cSrcweirEfforts are marked up in the code with comments like this: 27cdf0e10cSrcweir 28cdf0e10cSrcweir/* WRITERFILTERSTATUS: done: <percent done>, planned: <effort planned>, spent: <effort spent, yet> */ 29cdf0e10cSrcweir 30cdf0e10cSrcweirThe comments have to follow a case-label immediately. Consecutive 31cdf0e10cSrcweircase-labels can be marked up, too. In the latter case the efforts are 32*86e1cf34SPedro Giffunicounted for the preceding case-labels as a whole. 33cdf0e10cSrcweir 34cdf0e10cSrcweir2. Extraction process 35cdf0e10cSrcweir 36cdf0e10cSrcweir2.1. Stage 1: 37cdf0e10cSrcweir 38cdf0e10cSrcweirThis stage is handled in status.sh. An XML-file is generated that 39cdf0e10cSrcweircontains a top level element <stage1>. <stage1> contains an element 40cdf0e10cSrcweir<analyze> and several <qname> and <status> elements. 41cdf0e10cSrcweir 42cdf0e10cSrcweir2.1.1. Use analyzemodel.xsl to extract necessary data from model.xml. 43cdf0e10cSrcweir 44cdf0e10cSrcweir- Namespaces can be flagged with attribute @todo="ignore" to prevent 45cdf0e10cSrcweir the namespace being considered. 46cdf0e10cSrcweir 47cdf0e10cSrcweir- For every <element>/<attribute> an entry in an according element in <analyze> is genereated. These elements look like this: 48cdf0e10cSrcweir 49cdf0e10cSrcweir<attribute id="..." resource="..." tokenid="..." qname="..." namespace="..." define="..." name="..."/> 50cdf0e10cSrcweir 51cdf0e10cSrcweirImportant for the extraction of efforts: @qname is the identifier used 52cdf0e10cSrcweirin case-labels in .cxx files and thus links the status mark up 53cdf0e10cSrcweircomments with elements/attributes in the model.xml. 54cdf0e10cSrcweir 55cdf0e10cSrcweir2.1.2. Extract status information 56cdf0e10cSrcweir 57cdf0e10cSrcweirThe 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 58cdf0e10cSrcweir 59cdf0e10cSrcweircase NS_rtf::LN_UNUSED4: 60cdf0e10cSrcweir 61cdf0e10cSrcweirresult in elements like this 62cdf0e10cSrcweir 63cdf0e10cSrcweir<qname file="/DomainMapper.cxx" line="216" qname="NS_rtf::LN_UNUSED4"/>. 64cdf0e10cSrcweir 65cdf0e10cSrcweirLines like this 66cdf0e10cSrcweir 67cdf0e10cSrcweir/* WRITERFILTERSTATUS: done: 0, planned: 0, spent: 0 */ 68cdf0e10cSrcweir 69cdf0e10cSrcweirresult in elements like this 70cdf0e10cSrcweir 71cdf0e10cSrcweir<status done="0" planned="0" spent="0"/> 72cdf0e10cSrcweir 73cdf0e10cSrcweirThe <qname> and <status> elements are children of the <stage1> 74cdf0e10cSrcweirelement. The are inserted in the same order as found in the 75cdf0e10cSrcweircode. Therefore a <status> element corresponds to the group of 76cdf0e10cSrcweirconsecutive preceding <qname> elements. 77cdf0e10cSrcweir 78cdf0e10cSrcweir2.2. Stage 2 79cdf0e10cSrcweir 80cdf0e10cSrcweirIn this stage analyzestage2.xsl is used on the result of stage 1 to 81cdf0e10cSrcweirgroup the <qname> and <status> elements from stage 1. For each 82cdf0e10cSrcweir<status> element a <qnames> element is generated that contains the 83cdf0e10cSrcweir<qname> elements that the <status> element refers to, plus the 84cdf0e10cSrcweir<status> element. 85cdf0e10cSrcweir 86cdf0e10cSrcweir2.3. Stage 3 87cdf0e10cSrcweir 88cdf0e10cSrcweirThis stage associates the <attribute> and <element> elements in 89cdf0e10cSrcweirmodel.xml with the extracted data. It uses analyzestage3.xsl on the 90cdf0e10cSrcweirresult of stage 2 to do this. 91cdf0e10cSrcweir 92cdf0e10cSrcweirE.g. for given elements from stage 2: 93cdf0e10cSrcweir 94cdf0e10cSrcweir<attribute 95cdf0e10cSrcweir id="dml-wordprocessingDrawing:CT_Inline:distR" 96cdf0e10cSrcweir resource="Properties" 97cdf0e10cSrcweir tokenid="ooxml:CT_Inline_distR" 98cdf0e10cSrcweir qname="NS_ooxml::LN_CT_Inline_distR" 99cdf0e10cSrcweir namespace="dml-wordprocessingDrawing" 100cdf0e10cSrcweir define="CT_Inline" 101cdf0e10cSrcweir name="distR"/> 102cdf0e10cSrcweir 103cdf0e10cSrcweirand 104cdf0e10cSrcweir 105cdf0e10cSrcweir <qnames> 106cdf0e10cSrcweir <qname file="/GraphicImport.cxx" line="1078" qname="NS_ooxml::LN_CT_Inline_distT"/> 107cdf0e10cSrcweir <qname file="/GraphicImport.cxx" line="1079" qname="NS_ooxml::LN_CT_Inline_distB"/> 108cdf0e10cSrcweir <qname file="/GraphicImport.cxx" line="1080" qname="NS_ooxml::LN_CT_Inline_distL"/> 109cdf0e10cSrcweir <qname file="/GraphicImport.cxx" line="1081" qname="NS_ooxml::LN_CT_Inline_distR"/> 110cdf0e10cSrcweir <status done="0" planned="0.5" spent="0"/> 111cdf0e10cSrcweir </qnames> 112cdf0e10cSrcweir 113cdf0e10cSrcweirthe result of stage 3 will be 114cdf0e10cSrcweir 115cdf0e10cSrcweir <attribute 116cdf0e10cSrcweir id="dml-wordprocessingDrawing:CT_Inline:distR" 117cdf0e10cSrcweir resource="Properties" 118cdf0e10cSrcweir tokenid="ooxml:CT_Inline_distR" 119cdf0e10cSrcweir qname="NS_ooxml::LN_CT_Inline_distR" 120cdf0e10cSrcweir namespace="dml-wordprocessingDrawing" 121cdf0e10cSrcweir define="CT_Inline" name="distR"> 122cdf0e10cSrcweir 123cdf0e10cSrcweir <file name="/GraphicImport.cxx" line="1081"> 124cdf0e10cSrcweir <status done="0" planned="0.5" spent="0" qname-count="4"/> 125cdf0e10cSrcweir </file> 126cdf0e10cSrcweir 127cdf0e10cSrcweir </attribute> 128cdf0e10cSrcweir 129cdf0e10cSrcweir@qname-count is the number of case-labels that the according mark-up comment refers to. 130cdf0e10cSrcweir 131cdf0e10cSrcweir3. Collect efforts 132cdf0e10cSrcweir 133cdf0e10cSrcweirThis is done by the script efforts.sh. It uses status.sh to extract the status and determines the efforts in two steps. 134cdf0e10cSrcweir 135cdf0e10cSrcweir3.1. Choose which <attribute>/<element> elements need effort 136cdf0e10cSrcweir 137cdf0e10cSrcweirThis stage uses todo.xsl on the result of 2.3. 138cdf0e10cSrcweir 139cdf0e10cSrcweirThere are two criteria that imply effort: 140cdf0e10cSrcweir 141cdf0e10cSrcweir- The <attribute>/<element> is not handled in any file. 142cdf0e10cSrcweir 143cdf0e10cSrcweir- The status for the <attribute>/<element> declares that work is 144cdf0e10cSrcweir planned for it and less than 100 percent of this work is done. 145cdf0e10cSrcweir 146cdf0e10cSrcweir3.2. Generate table of efforts in CSV format 147cdf0e10cSrcweir 148cdf0e10cSrcweirThis stage uses effort.xsl on the results of 3.1. and produces the 149cdf0e10cSrcweirtable of efforts. If there is no status defined for an 150cdf0e10cSrcweir<attribute>/<element> it is assumed that the planned effort is 0.5 151cdf0e10cSrcweirhours and no work has been done. 152