![[RSS]](http://tweakimg.net/g/if/v2/icons/rss_small.gif){kind=icon}
Requirement list in Latex
This is just a small trick I have used in my last LaTeX-document to make separate list-environments keep incrementing, depending on the numbers of the previous list-environment. I think it is a bit hard to explain, so I will try to do by explaining the reason I needed this feature.
As a disclaimer I would like to note that there probably exists an advanced package that does the same and more, but this way I can learn more about tailoring LaTeX documents to my exact needs without using large packages.
Also, a tweaker showed me that my example is a bit misleading, because you could possibly run into troubles when requirement codes change due to an addition of a new requirement.
Defining the problem
When you are developing a software program for a customer, one of the negotiation steps is getting the requirements for the program clear for both parties. These requirements are some kind of contract both the customer and you agree with, and give you a legal foothold when the customer changes its mind during the project.
To keep the requirements organized, I am taught that you can divide them in different categories, ranging from high-priority and mandatory to low-priority and optional. So the requirement list is effectively broken down in smaller lists.
To keep track of each requirements (so you can reference to them in other documents or contracts), you need to give every requirement an unique number. And here lies the problem: every time you make a new enumeration (an ordered list) in Latex, it's index starts with one. Although you can alter that by using the "\setcounter" command to manually override this with a fixed number, you always have to make sure those numbers won't go out of sync with their predecessors when adding new requirements.
A solution
Well, one way to facilitate this synchronization is using a separate counter. This counter is used every time a new list starts and gets updated at the end of every list. When wrapping this in custom commands you get this:
code:
Please note that this code is written for use in a requirements document, but it can be adapted easily for other purposes.
When used in a document, you write the following text:
code:
This will result in a document with (roughly
) the following text:
.
As a disclaimer I would like to note that there probably exists an advanced package that does the same and more, but this way I can learn more about tailoring LaTeX documents to my exact needs without using large packages.
Also, a tweaker showed me that my example is a bit misleading, because you could possibly run into troubles when requirement codes change due to an addition of a new requirement.
Defining the problem
When you are developing a software program for a customer, one of the negotiation steps is getting the requirements for the program clear for both parties. These requirements are some kind of contract both the customer and you agree with, and give you a legal foothold when the customer changes its mind during the project.
To keep the requirements organized, I am taught that you can divide them in different categories, ranging from high-priority and mandatory to low-priority and optional. So the requirement list is effectively broken down in smaller lists.
To keep track of each requirements (so you can reference to them in other documents or contracts), you need to give every requirement an unique number. And here lies the problem: every time you make a new enumeration (an ordered list) in Latex, it's index starts with one. Although you can alter that by using the "\setcounter" command to manually override this with a fixed number, you always have to make sure those numbers won't go out of sync with their predecessors when adding new requirements.
A solution
Well, one way to facilitate this synchronization is using a separate counter. This counter is used every time a new list starts and gets updated at the end of every list. When wrapping this in custom commands you get this:
code:
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
| % Initializing the counters and define a custom label
\newcommand{\reqinit}{
% Create a new counter for keeping track of the last number
\newcounter{reqcountbackup}
% Create a new counter for the custom label
\newcounter{reqcount}
% Redefine the command for the last counter so when it is called
% it prints the number like this in a bold font: R<number>
\renewcommand{\thereqcount}{\textbf{R\arabic{reqcount}}}
}
% Used to define the start of the requirements
\newcommand{\reqstart}{
% Indicate the start of a new list and tell it to use the redefined
% command and corresponding counter for every item
\begin{list}{\thereqcount}{\usecounter{reqcount}}
% Important part: set the value of the used counter to the
% same value of the backup counter.
\setcounter{reqcount}{\value{reqcountbackup}}
}
% Used to define the end of the requirements
\newcommand{\reqend}{
% Important part: take the value of the used counter (after
% being incremented by the requirement items) and store it
% in the backup counter.
\setcounter{reqcountbackup}{\value{reqcount}}
% Mark the end of the list environment
\end{list}
} |
Please note that this code is written for use in a requirements document, but it can be adapted easily for other purposes.
When used in a document, you write the following text:
code:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| \reqinit
These requirements have a high priority:
\reqstart
\item Requirement description 1;
\item Requirement description 2;
\item Requirement description 3.
\reqend
These requirements have a low priority:
\reqstart
\item Requirement description 4;
\item Requirement description 5;
\item Requirement description 6.
\reqend |
This will result in a document with (roughly
) the following text:Knowing LaTeX, there are probably more than one way to tackle this problem. Feel free to comment on my code or give suggestions for other ways to tackle this problemThese requirements have a high priority:
R1 Requirement description 1;
R2 Requirement description 2;
R3 Requirement description 3.
These requirements have a low priority:
R4 Requirement description 4;
R5 Requirement description 5;
R6 Requirement description 6.
.
 23-05
|
Saxion en CAA, losmakelijk verbonden |
 13-05
|
Fun with Synaptics |
Comments
As you said, there is a package aptly called enumerate that does this (and more). With this package it is possible to "save" & "recall" the last number using variables. See also the documentation of the package.
But if your goal is learning more about latex, coding it your self is of course a good exercise.
But if your goal is learning more about latex, coding it your self is of course a good exercise.
By
mOrPhie,
Monday 19 May 2008 10:13
I know there are a lot of advantages in using TeX when writing scientific documentation (math and physics for example), since the language provides features to create formulas and complex structures. But why would you want to use a Tex document for writing software requirements? And even more important: why would you want TeX to decide which requirement gets which "requirement-id". This kind of documents (I've been working with them for quite a time now) are modified regularly. With your approach, when I add a high priority requirement, all requirements below change number. Since communication in email, telephone or in code commits in code repository always refers to "REQ0003" or something (to avoid having to type the complete description or title over and over again), this is not a very pragmatic approach.
This is besides the fact that you are using this as an example for doing a TeX exercise of course. But keep in mind that also TeX is just a tool, to achieve something. And your case is a good example of a good tool used the wrong way.
Do you use TeX this way in a professional environment or was it just an example?
This is besides the fact that you are using this as an example for doing a TeX exercise of course. But keep in mind that also TeX is just a tool, to achieve something. And your case is a good example of a good tool used the wrong way.
Do you use TeX this way in a professional environment or was it just an example?
By
Ghost,
Monday 19 May 2008 10:40
Well, you are right I would get into trouble when the requirement numbering would shift because of an insertion. I have already faced that when referring to the requirements from another document and was thinking of a way to reference to these requirements by giving them labels. In fact I wasn't planning on referencing to the codes outside of the documentation, so using labels would be perfectly fine.
However, I do see your point in wrongfully letting TeX decide the codes for a requirements document and perhaps I should have used another example to illustrate the concept. In this case it is for a school project where requirements are not bound to change (because of a fixed assignment). That's why you perhaps want to alter the code a bit so it suits your documentation in a more general manner, like the enumerate package does. Still, I see using it for a requirements listing would be bad and now I am less inclined to use this when writing real requirements.
Regarding the professional environment: I am using LaTeX for almost all of my documents, though, so when I have to write a report or a letter or a design documentation or anything, I greatly prefer LaTeX over WYSIWYG editors. I have found it's features match more closely my needs for effectively writing documents than editors like OOo Write or AbiWord.
However, I do see your point in wrongfully letting TeX decide the codes for a requirements document and perhaps I should have used another example to illustrate the concept. In this case it is for a school project where requirements are not bound to change (because of a fixed assignment). That's why you perhaps want to alter the code a bit so it suits your documentation in a more general manner, like the enumerate package does. Still, I see using it for a requirements listing would be bad and now I am less inclined to use this when writing real requirements.
Regarding the professional environment: I am using LaTeX for almost all of my documents, though, so when I have to write a report or a letter or a design documentation or anything, I greatly prefer LaTeX over WYSIWYG editors. I have found it's features match more closely my needs for effectively writing documents than editors like OOo Write or AbiWord.