summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx372
1 files changed, 372 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx b/Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx
new file mode 100644
index 00000000000..63acb86cee1
--- /dev/null
+++ b/Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx
@@ -0,0 +1,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