New copy editors
diff --git a/org.eclipse.rmf.documentation/rmf-images/error-editor.png b/org.eclipse.rmf.documentation/rmf-images/error-editor.png
new file mode 100644
index 0000000..8b2c7f4
--- /dev/null
+++ b/org.eclipse.rmf.documentation/rmf-images/error-editor.png
Binary files differ
diff --git a/org.eclipse.rmf.documentation/rmf-images/reqif-editor.png b/org.eclipse.rmf.documentation/rmf-images/reqif-editor.png
new file mode 100644
index 0000000..4362bdc
--- /dev/null
+++ b/org.eclipse.rmf.documentation/rmf-images/reqif-editor.png
Binary files differ
diff --git a/org.eclipse.rmf.documentation/rmf-latex/reference-part1.tex b/org.eclipse.rmf.documentation/rmf-latex/reference-part1.tex
index 0643ff6..86bba7b 100644
--- a/org.eclipse.rmf.documentation/rmf-latex/reference-part1.tex
+++ b/org.eclipse.rmf.documentation/rmf-latex/reference-part1.tex
@@ -178,9 +178,68 @@
\eclipsehelp{org.eclipse.platform.doc.user/reference/ref-43.htm}{Eclipse's Workbench User Guide}.
\begin{info}
- There may be more than one editor for a given file type. To pick a specific one, right-click the file and select \menu{Open With...}, which will give you the list of installed editors. In particular, the \menu{fmStudio Main Editor} from Formal Mind is more powerful than the stock editor (see Section~\ref{sec:StudioSpecEditor}).
+ There may be more than one editor for a given file type. To pick a specific one, right-click the file and select \menu{Open With...}, which will give you the list of installed editors. In particular, the \menu{ReqIF Studio Main Editor} from Formal Mind is more powerful than the stock editor (see Section~\ref{sec:StudioSpecEditor}).
\end{info}
A model contains any number of Specifications, and the details of each Specification can be inspected individually. The windows in which all relevant information appears are called \term{views}. At your disposal are many views with productivity, debugging, help and team resources. We will be focusing only on the views relevant to \pror{}.
+\begin{figure}
+\centering
+\includegraphics[width=.7\textwidth]{../rmf-images/reqif-editor.png}
+\caption{ReqIF Editor}
+\label{fig:reqif-editor}
+\end{figure}
+% -----------------------------------------------------------------------------------
+\subsection{ReqIF Editor}
+\label{sec:reqif-editor}
+\index{editor!ReqIF}
+\index{ReqIF editor}
+% -----------------------------------------------------------------------------------
+
+The \menu{ReqIF Editor} is the first editor that opens when opening a ReqIF file. It is shown in Figure~\ref{fig:reqif-editor}.
+
+The \menu{ReqIF Editor} lists all Specifications, which can be opened by double-clicking.
+
+\begin{info}
+If only one Specification is contained in the ReqIF file, it is opened automatically in a \menu{Specification Editor}.
+\end{info}
+
+Further, there are a few sections that are collapsed by default:
+
+\begin{description}
+\item[RMF - Getting Started.] This section contains some basic information for new users.
+\item[Document Properties.] This section show the embedded metadata. Some of it can be edited, some elements are read-only, as they are set by the tool.
+\end{description}
+
+\begin{figure}
+\centering
+\includegraphics[width=.7\textwidth]{../rmf-images/error-editor.png}
+\caption{ReqIF Editor With an active error tab}
+\label{fig:error-editor}
+\end{figure}
+
+% -----------------------------------------------------------------------------------
+\subsection{Errors in ReqIF Editor}
+\label{sec:errors-reqif-editor}
+\index{errors}
+\index{problems}
+% -----------------------------------------------------------------------------------
+
+If a ReqIF file is invalid, then \pror{} makes an attempt to recover. If this succeeds, then the \menu{ReqIF Editor} will show two tabs, as shown in Figure~\ref{fig:error-editor}.
+
+On the bottom, the editor now has two tabs, labeled \menu{Selection} and \menu{Problems}. The \menu{Problems} tab has three options:
+
+\begin{description}
+\item[Open with Text Editor.] This button will open the raw XML in a text editor. It is recommended to press \menu{Create Markers} first.
+\item[Create Markers.] This button will create error markers. This helps to pinpoint the problematic XML in the text editor.
+\item[Details.] This will open an area showing the error tree. This information will also be shown in the \menu{Problem View}.
+\end{description}
+
+The \menu{Selection} tab shows the recovered ReqIF. Depending on the reason for the error condition, most or even all of the ReqIF is still there.
+
+Saving the file will remove all problematic elements.
+
+\begin{info}
+A problematic ReqIF file can be fixed by simply by saving the ReqIF file again. It is recommended to inspect hte recovered ReqIF first, and to make a backup.
+\end{info}
diff --git a/org.eclipse.rmf.documentation/rmf-latex/tutorial.tex b/org.eclipse.rmf.documentation/rmf-latex/tutorial.tex
index 8e93297..389124a 100644
--- a/org.eclipse.rmf.documentation/rmf-latex/tutorial.tex
+++ b/org.eclipse.rmf.documentation/rmf-latex/tutorial.tex
@@ -12,7 +12,8 @@
% ===================================================================================
\section{Basic Concepts}
-\index{Concepts}
+\label{sec:tutorial-basic-concepts}
+\index{concepts}
% ===================================================================================
In this tutorial, we will use the ReqIF terminology, which can be confusing. Therefore, please familiarize yourself with the terminology first (Section~\ref{sec:terminology}).
@@ -23,12 +24,15 @@
% ===================================================================================
\section{Tutorial 1: Creating a Basic ReqIF Model}
+\label{sec:tutorial-create-basic-model}
% ===================================================================================
In this section, we will build a ReqIF model from scratch, step by step.
% -----------------------------------------------------------------------------------
\subsection{Install \pror{}}
+\label{sec:install-reqif-studio}
+\index{installation}
% -----------------------------------------------------------------------------------
The easiest way for installing \pror{} is downloading \href{https://reqif.academy}{ReqIF Studio}. This is a standalone-application that is based on Eclipse RMF, combined with some enhancements.
@@ -41,6 +45,9 @@
% -----------------------------------------------------------------------------------
\subsection{Create the Model}
+\label{sec:create-model}
+\index{create ReqIF model}
+\index{ReqIF model!create}
% -----------------------------------------------------------------------------------
\begin{itemize}
@@ -86,6 +93,11 @@
% -----------------------------------------------------------------------------------
\subsection{Customizing the SpecType}
+\label{sec:customize-spec-type}
+\index{SpecType configuration}
+\index{Datatype configuration}
+\index{configuration!SpecType}
+\index{configuration!Datatype}
% -----------------------------------------------------------------------------------
To get familiar with the tool, we will:
@@ -118,6 +130,9 @@
% -----------------------------------------------------------------------------------
\subsection{Showing the New Attributes}
+\label{sec:show-new-attributes}
+\index{configuration!columns}
+\index{column configuration}
% -----------------------------------------------------------------------------------
\begin{figure}
@@ -143,6 +158,9 @@
% -----------------------------------------------------------------------------------
\subsection{Adding new SpecObjects}
+\label{sec:add-specobjects}
+\index{SpecObjects!create}
+\index{create!SpecObjects}
% -----------------------------------------------------------------------------------
\begin{figure}
@@ -165,6 +183,8 @@
% -----------------------------------------------------------------------------------
\subsection{Rearranging Elements}
+\label{sec:rearrange-elements}
+\index{SpecObjects!rearrange}
% -----------------------------------------------------------------------------------
\begin{figure}
@@ -186,18 +206,23 @@
% -----------------------------------------------------------------------------------
\subsection{Export Specification as HTML}
+\label{sec:export-specs}
+\index{printing}
+\index{HTML export}
% -----------------------------------------------------------------------------------
If you want to export your Specification as HTML, open the Specification you would like to export and initiate printing \menu{File | Print...}. The HTML representation is generated and opened in your system's web browser.
% -----------------------------------------------------------------------------------
\subsection{Conclusion}
+\label{sec:tutorial-conclusion}
% -----------------------------------------------------------------------------------
Quite an achievement—but there's still a bit of a way to go. One improvement we can make is simplifying data entry. Another is improving the visibility of the descriptions. In the next part of the tutorial, we will address these issues.
% ===================================================================================
\section{Tutorial 2: Use Presentations}
+\label{sec:tutorial-presentations}
\index{presentation}
\index{plugin}
% ===================================================================================
@@ -226,6 +251,9 @@
% -----------------------------------------------------------------------------------
\subsection{ID Presentation}
+\label{sec:id-presentation}
+\index{create!IDs}
+\index{ID creation}
% -----------------------------------------------------------------------------------
It would be nice if every SpecObject had its own unique ID. Actually, they do: The unique ID is shown in the \menu{All Attributes} tab of the \menu{Property View}, if a SpecObject is selected. But that ID is meant for machines and is not practical.
@@ -253,12 +281,14 @@
% ===================================================================================
\section{Tutorial 3: Advanced SpecTypes}
+\label{sec:tutorial-spec-types}
% ===================================================================================
So far, we have a model with only one SpecObjectType. In this tutorial, we will show how we can work with multiple SpecTypes, and we will introduce other SpecTypes.
% -----------------------------------------------------------------------------------
\subsection{Multiple SpecTypes}
+\label{sec:multiple-spec-types}
% -----------------------------------------------------------------------------------
The first entry in our Specification (``A ReqIF Tutorial'') isn't really a requirement. Thus, it doesn't need an ID or an owner, and it would be nice to highlight it somehow. For highlighting, we have the \menu{Headline Presentation}. We will:
@@ -328,6 +358,7 @@
% -----------------------------------------------------------------------------------
\subsection{Other SpecTypes}
+\label{sec:other-spec-types}
% -----------------------------------------------------------------------------------
\begin{figure}
@@ -350,12 +381,15 @@
% ===================================================================================
\section{Tutorial 4: Links Between Elements}
+\label{sec:tutorial-links}
+\index{create!SpecRelations}
% ===================================================================================
A central feature of professional requirements tools is the ability to connect requirements with each other. These are typically called links, traces or relations. In ReqIF, these are \term{SpecRelations}.
% -----------------------------------------------------------------------------------
\subsection{Creating SpecRelations}
+\label{sec:create-links}
% -----------------------------------------------------------------------------------
There are two ways of creating SpecRelations: (1) via the context menu and (2) via drag and drop.
@@ -368,6 +402,7 @@
% -----------------------------------------------------------------------------------
\subsection{Linking Via Context Menu}
+\label{sec:context-links}
% -----------------------------------------------------------------------------------
Linking via context menu happens in two steps: initiating linking and completing linking.
@@ -380,6 +415,7 @@
% -----------------------------------------------------------------------------------
\subsection{Linking Via Drag and Drop}
+\label{sec:drag-links}
% -----------------------------------------------------------------------------------
SpecRelations are also be created by ``Link-Dragging''. This is platform specific:
@@ -396,6 +432,7 @@
% -----------------------------------------------------------------------------------
\subsection{SpecRelations in the User Interface}
+\label{sec:links-ui}
% -----------------------------------------------------------------------------------
\begin{figure}
@@ -422,8 +459,27 @@
Figure~\ref{fig:linksInGui} shows a Specification where REQ-1a and REQ-3a are linked.
% -----------------------------------------------------------------------------------
-\subsection{SpecRelations in the Outline View}
+\subsection{Following SpecRelations}
+\label{sec:follow-links}
+\index{SpecRelations!follow}
+\index{follow SpecRelations}
% -----------------------------------------------------------------------------------
-The \menu{Outline View} has a folder showing all SpecRelations.
+It is possible to navigate along SpecRelations. To do so, make the links visible, as described in Section~\ref{sec:links-ui}. Double-clicking on the label of the link target will open the appropriate Specification and select the SpecObject.
+
+As Specifications contain references to SpecObjects, there are two other situations that can occur:
+\begin{description}
+
+\item
+ [The target SpecObject is not used in any Specification.] In that situation, double-clicking will have no effect. But clicking on the label will show the target SpecObject's attributes in the Properties View, where they can be inspected and edited.
+\item
+ [The target SpecObject is referenced multiple times in Specifications.] In that case, a menu will open to show all places where the SpecObject is used. The user can select the place to navigate to.
+\end{description}
+
+% -----------------------------------------------------------------------------------
+\subsection{SpecRelations in the Outline View}
+\label{sec:links-outline}
+% -----------------------------------------------------------------------------------
+
+The \menu{Outline View} has a folder showing all SpecRelations. This folder is shown only when the ReqIF editor (Section~\ref{}) is active.
