path: root/Master/texmf-dist/source/latex/stex/reqdoc/reqdoc.dtx

% \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}
\svnInfo $Id: reqdoc.dtx 1671 2010-11-06 07:05:15Z kohlhase $
\svnKeyword $HeadURL: https://svn.kwarc.info/repos/stex/trunk/sty/reqdoc/reqdoc.dtx $
\usepackage{stex-logo}
\usepackage{../ctansvn}
\usepackage{hyperref}
\makeindex
\def\tracissue#1{\cite{sTeX:online}, \hyperlink{http://trac.kwarc.info/sTeX/ticket/#1}{issue #1}}
\begin{document}\DocInput{reqdoc.dtx}\end{document}
%</driver>
% \fi
% 
%\iffalse\CheckSum{195}\fi
% 
% \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}.  If the \DescribeMacro{showmeta}|showmeta| is set, then
% the metadata keys are shown (see~\cite{Kohlhase:metakeys:ctan} for details and customization
% options).
%
% \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}|}|.
%
%
% \section{Limitations}\label{sec:limitations}
% 
% In this section we document known limitations. If you want to help alleviate them,
% please feel free to contact the package author. Some of them are currently discussed in
% the \sTeX TRAC~\cite{sTeX:online}. 
% \begin{compactenum}
% \item none reported yet
% \end{compactenum}
% 
% \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 declare some switches which will modify the behavior according to the package
% options. Generally, an option |xxx| will just set the appropriate switches to true
% (otherwise they stay false).\ednote{need an implementation for {\latexml}}
%
%    \begin{macrocode}
%<*package>
\DeclareOption{showmeta}{\PassOptionsToPackage{\CurrentOption}{metakeys}}
\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
\addmetakey{reqs}{numbering}
\addmetakey[R]{reqs}{prefix}
\def\reqs@no{no}
\newenvironment{requirements}[1][]%
{\metasetkeys{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 |\addmetakey| command from the |metakeys|
% package~\ctancite{Kohlhase:metakeys}.  The group below, named as |req|, consists of three
% keywords |id|, |prio| and |refs|. 
%    \begin{macrocode}
%<*package>
\addmetakey{req}{id}
\addmetakey{req}{prio}
\addmetakey{req}{refs}
\addmetakey{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][]%
{\metasetkeys{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][]{\metasetkeys{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][]%
{\metasetkeys{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 newenvironment 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
% LocalWords:  showmeta showmeta metakeys addmetakey metasetkeys