2

In my document I have a list of requirements (currently these are just text created through a custom command).

One special thing is that these requirements are manually numbered (and not ordered by number). This is very important because that way we can assure requirements stay uniquely identifiable across documents and versions.

How can I make a list of requirements? And how can I refer (clickable in PDF) to my requirements from the text?

I have found several examples of this (for instance using ntheorem), but they all do the numbering automatically.

This could work for example as follows (the requirements are spread across the document):

\requirement{7}{Important requirement}
...
\requirement{8}{Secondary requirement}
...
\requirement{3}{Moved requirement, this must be followed if \refRequirement{7} is not follow}

\listOfRequirements

This would produce the requirements in order of set in the document, with a clickable link to requirement 7, and alist of requirements (sorted by number) in a separate chapter, these indicate the page the requirement is on, as well as a link to them.

  • Can you please post some sample code to show us what you have tried and what effect you wish to achieve. – Andrew Swann Feb 12 '14 at 9:09
  • I have not found anything yet that I could try. I will add some example usages/effects. – Thirler Feb 12 '14 at 9:16
  • I’d use standard enumerate or description environments or make a list of my own. Sadly, \label and \ref don’t work with the optional parameter to \item out of the box. That can be solved, though. – Crissov Feb 12 '14 at 10:09
3

Here's a solution that does both of your requests; let's go through the code.

The line

\newcommand\listOfRequirements{\@starttoc{req}}

starts a file called \jobname.req to which we will write the requirements. The \requirement command is defined as

\newcommand{\requirement}[2]{%
    \hypertarget{req:#1}
    #1. #2%
    \phantomsection
    \addcontentsline{req}{subsection}{\protect\numberline{\protect#1} #2}%
}

which

  • sets a hypertarget to be used by the \refRequirement command (more on that in a moment)
  • outputs #1 and #2 to the document
  • sets a phantomsection which is necessary for the hyperlinks to work
  • adds a numbered entry containing #2 with #1 as its number to \jobname.rec

Finally, the \refRequirement command hyperlinks to the original location of the requirement.

\newcommand{\refRequirement}[1]{\hyperlink{req:#1}{#1}}

As with any toc-based command, it takes at least two compilations to stabilize (possibly more if you have any other changing toc type elements).

% arara: pdflatex
% arara: pdflatex
% !arara: indent: {overwrite: on}
\documentclass{report}
\usepackage{lipsum}
\usepackage{hyperref}

\makeatletter
% requirements
\newcommand\listOfRequirements{\@starttoc{req}}
% command to output requirement on the page, and also add it
% to the list of requirements
\newcommand{\requirement}[2]{%
    \hypertarget{req:#1}
    #1. #2%
    \phantomsection
    \addcontentsline{req}{subsection}{\protect\numberline{\protect#1} #2}%
}

\newcommand{\refRequirement}[1]{\hyperlink{req:#1}{#1}}

\begin{document}

\begin{itemize}
    \item here's a reference to requirement \refRequirement{7}
    \item here's a reference to requirement \refRequirement{3}
    \item here's a reference to requirement \refRequirement{8}
\end{itemize}
\lipsum

\requirement{7}{Important requirement}

\lipsum

\requirement{8}{Secondary requirement}

\lipsum

\requirement{3}{Moved requirement, this must be followed if  is not follow}

\lipsum


\chapter{Requirements}
\listOfRequirements
\end{document}
  • Thanks, this works well. Is it also possible to sort the listOfRequirements? I've looked for documentation on the starttoc command, but there isn't a whole lot I could find. – Thirler Feb 13 '14 at 11:48
  • @Thirler sorting the listOfRequirements won't be trivial; is it likely that the recommendations will appear out of order in the document? – cmhughes Feb 13 '14 at 16:10
  • Yes indeed they can be out of order, I guess one ugly way is to use command line to sort the files inbetween the two latex calls. – Thirler Feb 14 '14 at 10:44
  • @Thirler I'm not sure how to sort the toc; however, I'm still a little confused. Wouldn't requirement 1 come first in the document? Wouldn't the reader be a little confused to read requirement 7 before seeing any of the first 6 requirements? Regardless, if the requirements are out of order in the document, then they should probably be out of order in the list-- maybe I'm just copping out because sorting the toc differently from the order it was created is going to be a fair bit of effort :) – cmhughes Feb 14 '14 at 15:51
  • The reason is that we don't ever want to renumber the requirements (very common way of working in requirements documents), hence the reason for wanting to manually number them. Often for readability you do want to reorder the requirements. (or add one in the middle of the document because something changed). I did a quick trial and just using linux or windows sort command on the .req file will give the desired sorting in the index (but its a dirty fix because it depends on the build script). – Thirler Feb 17 '14 at 10:40
2

To get the numbering and the reference you only need to set the number at the begin of your command to Arg-1 and then use \refstepcounter:

\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}%
\usepackage{hyperref}
\newcounter{requirement}
\newcommand\requirement[1]{%
 \par
 \setcounter{requirement}{\the\numexpr #1-1}% number -1
 \refstepcounter{requirement}% +1 
 \therequirement:}
\begin{document}
\requirement{3} blablablaq\label{a}

\requirement{7} blablablaq\label{b}


\newpage

see requirement \ref{b}

\end{document}

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.