summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx
blob: 63acb86cee11c08d9554fc1262f175a8e7a2b7e9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
% \iffalse meta-comment
% Semantic Markup for Requirement Specification Documents
% Copyright (c) 2008 Michael Kohlhase, all rights reserved
%
% This file is distributed under the terms of the LaTeX Project Public
% License from CTAN archives in directory  macros/latex/base/lppl.txt.
% Either version 1.0 or, at your option, any later version.
%  
% The development version of this file can be found at
% $HeadURL: https://svn.kwarc.info/repos/stex/trunk/sty/reqdoc/reqdoc.dtx $
% \fi
% 
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{reqdoc}[2010/06/25 v0.3 Semantic Requirement Documents]
%
%<*driver>
\documentclass[twoside]{ltxdoc}
\EnableCrossrefs
%\CodelineIndex
%\OnlyDescription
\RecordChanges
\usepackage{reqdoc}
\usepackage{textcomp,url,a4wide}
\usepackage[show]{ed}
\usepackage[hyperref=auto,style=alphabetic]{biblatex}
\bibliography{kwarc}
\usepackage[eso-foot,today,draft]{svninfo}
\usepackage{stex-logo}
\usepackage{../ctansvn}
\usepackage{hyperref}
\makeindex
\begin{document}
\svnInfo $Id: reqdoc.dtx 1502 2010-07-20 08:17:00Z kohlhase $
\svnKeyword $HeadURL: https://svn.kwarc.info/repos/stex/trunk/sty/reqdoc/reqdoc.dtx $
\DocInput{reqdoc.dtx}
\end{document}
%</driver>
% \fi
% 
%\CheckSum{195}
% 
% \changes{v0.3}{2008/06/26}{Integrated LaTeXML bindings}
% \changes{v0.2}{2008/02/04}{First Version with Documentation}
% \changes{v0.1}{2008/01/18}{First Version}
% 
% \GetFileInfo{reqdoc.sty}
% 
% \MakeShortVerb{\|}
% \def\latexml{{\LaTeX}ML}
%
% \title{{\texttt{reqdoc.sty}}: Semantic Markup for Requirements Specification Documents\thanks{Version 
% {\fileversion} (last revised {\filedate})}} 
%    \author{Michael Kohlhase\\
%            Computer Science, Jacobs University\\
%            \url{http://kwarc.info/kohlhase}}
% \maketitle
%
% \begin{abstract}
%   This package provides an infrastructure for semantically enhanced requirements
%   specifications used in software engineering. This allows to embed structural
%   information into documents that can be used by semantic document management systems
%   e.g. for management of change and requirements tracing.
% \end{abstract}
%
% \newpage\tableofcontents\newpage
%
% \section{Introduction}\label{sec:intro}
% 
% In software engineering, the development process is accompanied with a trail of
% structured documents, user specifications, architecture specifications, test reports,
% etc. All of these documents\ednote{continue}
% 
% For an example of a requirement document see the file |requirements.tex| provided in
% this package. \ednote{need to bring this in line with the \texttt{sref} package}
% 
% \section{The User Interface}\label{sec:interface}
%
% \subsection{Package Options}
% 
% The |reqdoc| package takes the package option \DescribeMacro{recorddeps}|recorddeps|. If
% this is given, then the package generates an external file with dependencies that can be
% used by external systems like the {\texttt{locutor}} system\ednote{add citation here},
% see Section~\ref{sec:moc-deps}.
%
% \subsection{Requirements}
% The |reqdoc| package supplies two forms of writing down requirements that mainly differ
% in their presentation. We can have requirement lists and requirement tables.
%
% \DescribeEnv{requirements} The |requirements| environment marks up a list of
% requirements. It takes an optional key/value list as an argument: if |numbering| is set
% to |yes| (the default), then the requirements are numbered for referencing it visually;
% the label is created using the prefix specified in the key |prefix|.
%
% \DescribeEnv{requirement} The individual requirements are specified by the |requirement|
% environment, which takes an optional key/value list as an argument: the |id| key allows
% to specify a symbolic label for cross-referencing, the |prio| key allows to specify a
% priority of the requirement, the |reqs| key allows to specify a comma-separated list of
% labels of requibments this one depends on or refines. Finally, the visual label of the
% requirement can be fixed by the |num| key\ednote{this is not implemented yet}.
% 
% \DescribeEnv{reqtable} The |reqtable| environment is a varian of the |\requirements|
% environment that shows the requirements in a tabular form that gives a better overview;
% its optional key/value argument works the same. \DescribeMacro{\reqline}The respective
% requirements are marked up with the |\reqline| macro, which takes three arguments. The
% first one is an optional key/value specification and corresponds to be one on the
% |requirement| environment. The second one contains the actual text of the requirements
% and the third one a comment.
% 
% \DescribeMacro{\importreqs}Note that if we want to refer to requirements from a document
% \meta{doc}, then we will need to know about their representations and can import the
% necessary information via |\importreqs{|\meta{doc}|}|.
%
% \StopEventually{\newpage\PrintIndex\newpage\PrintChanges\printbibliography}
% \newpage
%
% \section{The Implementation}\label{sec.impl}
% 
% The |reqdoc| package generates to files: the {\LaTeX} package (all the code between
% {\textsf{$\langle$*package$\rangle$}} and {\textsf{$\langle$/package$\rangle$}}) and the
% {\latexml} bindings (between {\textsf{$\langle$*ltxml$\rangle$}} and
% {\textsf{$\langle$/ltxml$\rangle$}}). We keep the corresponding code fragments together,
% since the documentation applies to both of them and to prevent them from getting out of
% sync.
%
% \subsection{Package Options}\label{sec.impl.options}
%
% We first introduce the single option |recorddeps| which comes with its own switch |\if@deps|
% 
%    \begin{macrocode}
%<*package>
\newif\if@deps\@depsfalse
\DeclareOption{recorddeps}{\@depstrue}
\ProcessOptions
%    \end{macrocode}
% Then we load a couple of packages
%    \begin{macrocode}
\RequirePackage{sref}
\RequirePackage{longtable}
%</package>
%<*ltxml>
package LaTeXML::Package::Pool;
use strict;
use LaTeXML::Package;
%</ltxml>
%    \end{macrocode}
%
% Then we register the namespace of the requirements ontology
%    \begin{macrocode}
%<*ltxml>
RegisterNamespace('r'=>"http://omdoc.org/ontology/requirements#");
RegisterDocumentNamespace('r'=>"http://omdoc.org/ontology/requirements#");
%</ltxml>
%    \end{macrocode}
%
% \subsection{Requirements}\label{sec.impl.requirements}
%
% \begin{environment}{requirements}
%   and now the |requirements| environment, it is empty at the moment\ednote{think about
%     this again!}  
%   \begin{macrocode}
%<*package>
\newif\ifreqsnum\reqsnumfalse
\omdaddkey{reqs}{numbering}
\omdaddkey[R]{reqs}{prefix}
\def\reqs@no{no}
\newenvironment{requirements}[1][]%
{\omdsetkeys{reqs}{#1}\ifx\reqs@numbering\reqs@no\reqsnumfalse\else\reqsnumtrue\fi}{}
%</package>
%<*ltxml>
DefEnvironment('{requirements} OptionalKeyVals:reqs',
       "<omdoc:omgroup type='itemize'>#body</omdoc:omgroup>");
%</ltxml>
%    \end{macrocode}
% \end{environment}
%
% We define a group of keywords using the |\omdaddkey| command from the |omd|
% package~\ctancite{Kohlhase:omd}.  The group below, named as |req|, consists of three
% keywords |id|, |prio| and |refs|. 
%    \begin{macrocode}
%<*package>
\omdaddkey{req}{id}
\omdaddkey{req}{prio}
\omdaddkey{req}{refs}
\omdaddkey{req}{num}
\newcounter{reqnum}[section]
%    \end{macrocode}
% This function cycles over a comma-separated list and does the references 
%    \begin{macrocode}
\def\req@do@refs#1#2{\let\@tmpop=\relax\@for\@I:=#1\do{\@tmpop\req@do@ref{\@I}\let\@tmpop=#2}}
%    \end{macrocode}
% The |\req@do@ref| command creates a hyperlink from \ednote{What is req at ref? It has
%   appeared for the first time.}
%    \begin{macrocode}
\def\req@do@ref#1{\sref@hlink@ifh{#1}{\req@ref{#1}{number}}}
%    \end{macrocode}
% this function defines a requirement aspect
% the first arg is the label, the second one the aspect to be defined and the third one the value
% expand |csname| before |xdef|
%
% The command |\req@def@aux| creates the name of a command, 
% which is determined by the text given between |\csname| and |\endcsname|, 
% and defines this command globally to function as |#3|.
% We use the command |\expandafter| in the definition of |\req@def@aux|
% to execute the command |\xdef| after |\csname| is executed.
%    \begin{macrocode}
\def\req@def@aux#1#2#3{\expandafter\xdef\csname req@#1@#2\endcsname{#3}}
%    \end{macrocode}
% this function takes the same arguments and writes the command to the aux file
%    \begin{macrocode}
\def\req@write@aux#1#2#3{\protected@write\@auxout{}{\string\req@def@aux{#1}{#2}{\thesection.#3}}}
%    \end{macrocode}
% and finally this function does both 
%    \begin{macrocode}
\def\req@def#1#2#3{\req@def@aux{#1}{#2}{#3}\req@write@aux{#1}{#2}{#3}}
%    \end{macrocode}
% this function references an aspect of a requirement. 
%    \begin{macrocode}
\def\req@ref#1#2{\csname req@#1@#2\endcsname}
%    \end{macrocode}
% these functions print the priority, label, and references (if specified)
%    \begin{macrocode}
\def\print@req@prio{\ifx\req@prio\@empty\else(Priority: \req@prio)\fi}
\def\print@req@label{\sref@target@ifh\req@id{\reqs@prefix\arabic{reqnum}: }}
\def\print@req@refs{\ifx\req@refs\@empty\else\hfill [from~\req@do@refs{\req@refs}{,}]\fi}
%    \end{macrocode}
% \ednote{What are |number| and |\thereqnum|?}
% First argument is a list of key-value pairs which are assigned to req.
% Increase the counter reqnum, i.e., increase the requirement number.
% Remember the number for reference.
% Print the requirement label (with the requirement number) 
% Print the priority?
% Print the requirement (given as arg 2)
% Print the references
% We define a new command |\reqnote| to annotate the notes given for a requirement.
% The command |\reqnote| simply prints the note, which is given by the user as a text,
% in the form |Note: <text>|.
% \begin{environment}{requirement}
%    \begin{macrocode}
\newenvironment{requirement}[1][]%
{\omdsetkeys{req}{#1}\stepcounter{reqnum}
\ifreqsnum\ifx\req@id\@empty\else\req@def\req@id{number}\thereqnum\fi
\noindent\textbf{\print@req@label}\fi
\newcommand{\reqnote}[1]{\par\noindent Note: ##1}
\print@req@prio}
{\medskip\print@req@refs}
%</package>
%<*ltxml>
DefCMPEnvironment('{requirement} OptionalKeyVals:req',
      "<omdoc:omtext ?&KeyVal(#1,'id')(xml:id='&KeyVal(#1,'id')')() r:dummy='to ensure the namespace'>"
      . "<omdoc:meta property='texttype' content='r:requirement'/>"
     .  "?&KeyVal(#1,'refs')(<omdoc:link rel='r:dependsOn' href='#&KeyVal(#1,'refs')'/>)()"
      .  "#body"
      ."</omdoc:omtext>");
DefConstructor('\reqnote{}',
       "<omdoc:note type='requirement'>#1</omdoc:note>");
%</ltxml>
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{reqtable}
%    \begin{macrocode}
%<*package>
\newenvironment{reqtable}[1][]{\omdsetkeys{reqs}{#1}
\begin{center}\begin{longtable}{|l|l|p{6cm}|p{5cm}|l|}\hline
\# & Prio & Requirement & Notes & Refs\\\hline\hline}
{\end{longtable}\end{center}}
%</package>
%<*ltxml>
DefEnvironment('{reqtable} OptionalKeyVals:reqs',
       "<omdoc:omgroup type='itemize'>#body</omdoc:omgroup>");
%</ltxml>
%    \end{macrocode}
%  \end{environment}
%  
% \begin{macro}{\reqline}
%    \begin{macrocode}
%<*package> 
\newcommand{\reqline}[3][]%
{\omdsetkeys{req}{#1}\stepcounter{reqnum}
\req@def\req@id{number}\thereqnum% remember the number for reference
\textbf{\sref@target@ifh\req@id{\reqs@prefix\arabic{reqnum}}}&
\req@prio &#2&#3&\req@do@refs\req@refs{,}\tabularnewline\hline}
%</package>
%<*ltxml>
DefCMPConstructor('\reqline OptionalKeyVals:req{}{}',
       "<omdoc:omtext type='requirement'><omdoc:CMP>#2</omdoc:CMP></omdoc:omtext>"
      ."<omdoc:omtext type='note'><omdoc:CMP>#3</omdoc:CMP></omdoc:omtext>");
%</ltxml>
%    \end{macrocode}
% \end{macro}
%    
% \begin{macro}{\importreqs}
%   The |\importreqs| macro reports a dependency to the dependencies file. and then reads
%   the |aux| file specified in the argument.
%    \begin{macrocode}
%<*package>
\newcommand{\importreqs}[1]{\req@dep@write{"#1.tex"}{IMPORTREQS}\makeatletter\input{#1.aux}\makeatother}
%</package>
%<*ltxml>
DefConstructor('\importreqs {}',"<omdoc:imports from='#1'/>");
%</ltxml>
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\rinput}
%   The |\rinput| macro\ednote{this should go somewhere up; probably merge with sinput;
%     which should also go into the stex package.} inputs the file and protocols this in
%   the dependencies file. Note that this only takes place on the top level; i.e. the
%   |\@ifdeps| switch is set to false.
%  \begin{macrocode}
%<*package>
\newcommand{\rinput}[1]{\req@dep@write{"#1.tex"}{[dt="input"]}\bgroup\@depsfalse\input{#1}\egroup}
%</package>
%<*ltxml>
DefMacro('\rinput','\input');
%</ltxml>
%    \end{macrocode}
%  \end{macro}
%
% \subsection{Recording the dependencies for Change Management}\label{sec:moc-deps}
% 
% The macros in this section record dependencies in a special file to be used in change
% management by the {\texttt{locutor}} system. This is still not optimal, since we do not
% know the actual path.
%
%    \begin{macrocode}
%<*package>
\if@deps\newwrite\req@depfile
\immediate\openout\req@depfile=\jobname.deps
\AtEndDocument{\closeout\req@depfile}
%</package>
%    \end{macrocode}
% we redefine the |\importmodule| command, so that it does the reporting. 
%    \begin{macrocode}
%<*package>
\renewcommand{\importmodule}[2][]{\req@dep@write{"#1.tex"}{[dt="importmodule"]}\def\@test{#1}%
\ifx\@test\@empty\else\requiremodules{#1}\fi
\expandafter\gdef\csname#2@cd@file@base\endcsname{#1}
\activate@defs{#2}\export@defs{#2}}
\fi
%</package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*package>
\def\req@dep@write#1#2{\if@deps\protected@write\req@depfile{}{#1 #2}\fi}
%</package>
%    \end{macrocode}
% \subsection{Finale}
%
% Finally, we need to terminate the file with a success mark for perl.
%    \begin{macrocode}
%<ltxml>1;
%    \end{macrocode}
% \Finale
\endinput



% LocalWords:  iffalse reqdoc reqdoc.dtx kohlhase latexml texttt fileversion
% LocalWords:  maketitle newpage tableofcontents newpage ednote sref recorddeps
% LocalWords:  recorddeps moc-deps DescribeEnv prio reqs reqtable reqtable deps
% LocalWords:  reqline importreqs printbibliography sec.impl textsf langle ifx
% LocalWords:  textsf langle ltxml newif depsfalse depstrue longtable ifreqsnum
% LocalWords:  reqsnumfalse omdaddkey newenvironment omdsetkeys reqsnumtrue omd
% LocalWords:  OptionalKeyVals omdoc omgroup ctancite req newcounter reqnum
% LocalWords:  tmpop tmpop csname xdef endcsname expandafter auxout thesection
% LocalWords:  hfill thereqnum reqnote stepcounter noindent textbf newcommand
% LocalWords:  medskip omtext texttype hline tabularnewline makeatletter rinput
% LocalWords:  makeatother sinput stex ifdeps bgroup egroup newwrite depfile
% LocalWords:  openout jobname.deps renewcommand requiremodules gdef defs defs