6

I'm working on a document that contains the requirements and specification for a code suite, and I'd like to create a requirements traceability matrix that shows what part of the spec covers each requirement. I have a list of requirements that I've created "manually". (I don't want to auto generate the item numbering...the requirements will be referenced by number outside of the document.)

I also have a specification that I've created just using a normal enumerate environment.

How can I automate the creation of a requirement traceability matrix (table) that lists the portion of the spec that covers each requirement as in the example below? The first column is each of the requirements and the second column lists all of the specification items that reference that particular requirement.

\documentclass{article}

\begin{document}

% define \req command to label requirements in description environment
\makeatletter
\newcommand{\req}[1]{
  \textbf{R#1}
  \def\@currentlabel{R#1}\label{req#1}
}
\makeatother

% requirements are listed and labeled manually in description environment
\begin{description}
  \item[\req{1}] First requirement
  \item[\req{2}] Second requirement
  \begin{description}
    \item[\req{2.1}] Requirement 2.1
      \begin{description}
        \item[\req{2.1.1}] Requirement 2.1.1
        \item[\req{2.1.2}] Requirement 2.1.2
      \end{description}
    \item[\req{2.2}] Requirement 2.2
  \end{description}
\end{description}

% specifications are items in enumerate environment with references to 
% requirements met at end of each specification
\begin{enumerate}
  \item\label{spec1} First specification. \ref{req2.1.2}
  \item\label{spec2} Second specification. \ref{req1}
  \begin{enumerate}
    \item\label{spec3} Third specification. \ref{req1}
    \item\label{spec4} Fourth specification. \ref{req2}, \ref{req2.1.1}
  \end{enumerate}
\end{enumerate}

% requirement traceability matrix (table) should be auto-generated
% first column is refs to requirement labels manually generated
% second column is refs to specification labels generated in enumerate environment
%    for all specifications in which the requirement ref appears in the enumerate
%    environment
\begin{table}[h]
\begin{tabular}{|l|l|}
\hline
Requirement & Specification   \\ \hline
\ref{req1}          & \ref{spec2}, \ref{spec3}     \\ \hline
\ref{req2}          & \ref{spec4}                  \\ \hline
\ref{req2.1}        &                              \\ \hline
\ref{req2.1.1}      & \ref{spec4}                  \\ \hline
\ref{req2.1.2}      & \ref{spec1}                  \\ \hline
\ref{req2.2}        &                              \\ \hline
\end{tabular}
\end{table}

\end{document}
6
  • Welcome to TeX.SX! Please make your code a minimal working example (MWE) in order to make it easier for the users willing to help.
    – Pier Paolo
    Jan 4 '15 at 0:03
  • Thanks, @PierPaolo. I wanted to show that some requirements would have multiple cross-references with specs and some would have no cross-references. I will edit down a little though.
    – DrPositron
    Jan 4 '15 at 0:09
  • So you want to automate the procedure of creating the ending tabular given the above lists?
    – Werner
    Jan 4 '15 at 1:26
  • @Werner yes, will update the question. Sorry for the vagueness.
    – DrPositron
    Jan 4 '15 at 1:29
  • 2
    some of us don't know what a "traceability matrix" is. maybe a change of title to something like "automate creation of table using data in enumerated list" Jan 4 '15 at 14:25
3

Some package should be written for that, to account for more possibilities than what my proposal already allows (1), keeping quite close to your initial set-up.

(1) for example, to sort lexicographically the requirements, here they are already in correct order from the way they are generated.

I have added hyperref to check that the automatically produced table indeed has hyperlinks, both to the requirements and to the specifications.

requirement table

\documentclass{article}

\newcommand{\requirements}{}
\providecommand*\phantomsection{}

\makeatletter
\newcommand{\req}[1]{%
  \textbf{R#1}%
  \phantomsection
  \def\@currentlabel{R#1}%
  \label{req@#1}%
  \g@addto@macro\requirements{{req@#1}}%
  \global\@namedef{req@#1@ismetby}{}%
}

\newcommand{\meetsreq}[1]{%
  \ref{req@#1}%
  \expandafter\g@addto@macro\csname req@#1@ismetby\expandafter\endcsname 
              \expandafter {\expandafter{\@currentspec}}%
}

\newcommand{\specswithreq}[1]% 
% The space before \ref below is intentional and will be swallowed by \xintApply
% It is not mandatory however, the thing works without it too.
 {\xintListWithSep{, }{\xintApply { \ref}{\csname #1@ismetby\endcsname }}}

\newcommand{\spec}[1]{\label{spec@#1}\gdef\@currentspec{spec@#1}}
% (update Jan 5, to use \gdef rather than \def in \spec, allowing more flexible usage; has its pros and cons)
\makeatother

\usepackage{xinttools}

\usepackage{hyperref}% check if ok with hyperlinks
\hypersetup{colorlinks=true}

\begin{document}


\begin{description}
  \item[\req{1}] First requirement
  \item[\req{2}] Second requirement
  \begin{description}
    \item[\req{2.1}] Requirement 2.1
      \begin{description}
        \item[\req{2.1.1}] Requirement 2.1.1
        \item[\req{2.1.2}] Requirement 2.1.2
      \end{description}
    \item[\req{2.2}] Requirement 2.2
  \end{description}
\end{description}

\begin{enumerate}
  \item\spec{1} First specification. \meetsreq{2.1.2}
  \item\spec{2} Second specification. \meetsreq{1}
  \begin{enumerate}
    \item\spec{3} Third specification. \meetsreq{1}
    \item\spec{4} Fourth specification. \meetsreq{2}, \meetsreq{2.1.1}
  \end{enumerate}
\end{enumerate}


\begin{table}[htbp]
\begin{tabular}{|l|l|}
\hline
Requirement & Specification   \\ 
\hline
\xintFor* #1 in \requirements\do {\ref{#1}&\specswithreq{#1}\\
                                  \hline }%
\end{tabular}
\end{table}

\end{document}

The update renames macros as per the comments.

One immediate extension which comes to mind would be to allow \meetsreq to accept a comma separated list. The following modified code does it:

\newcommand{\meetsthisreq}[1]{% (renamed from \meetsreq above)
  \ref{req@#1}%
  \expandafter\g@addto@macro\csname req@#1@ismetby\expandafter\endcsname 
              \expandafter {\expandafter{\@currentspec}}%
}

\newcommand{\meetsreq}[1]{% (handles comma separated list)
  \xintListWithSep{, }{\xintApply{ \meetsthisreq}{\xintCSVtoList{#1}}}%
}

One can then use for example

    \item\spec{4} Fourth specification. \meetsreq{2, 2.1.1}
3
  • 1
    I didn't read too closely what the vocabulary meant, thus possibly \requires should have been called \meetsrequirement, from second reading of edited OP's question. And things such as isrequiredby should have been called ismetby, if I understand correctly.
    – user4686
    Jan 4 '15 at 22:46
  • Very impressive @jfbu. Yes, \meetsrequirement and \ismetby are more appropriate. I'm new to the site. Is it appropriate for me to edit your answer?
    – DrPositron
    Jan 5 '15 at 0:28
  • 1
    @DrPositron I have edited the answer, as I am not sure you actually would have been allowed by the site viz. your current reps ;-).
    – user4686
    Jan 5 '15 at 7:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.