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