Browse Source

reduce documentation size

Eren Yilmaz 6 years ago
parent
commit
f117ef71cd

+ 1 - 2
doc/chapter/1introduction.tex

@@ -7,12 +7,11 @@ Then each stage of the node placing algorithm by Brandes and Köpf~\cite{brandes
 After each step the current progress of the algorithm is displayed visually.
 
 In chapter~\ref{ch:architecture} we provide an overview over the \appname 's internal architecture while chapter~\ref{ch:ui} presents and explains the graphical user interface.
-To provide an overview of what is going on, chapter~\ref{ch:progress} lists features and their degree of completion.
 A glossary of some of the more difficult terms we can be found in the appendix (table~\ref{table:glossary}).
 
 \appname\ is currently a work in progress so keep in mind that any of the here presented screenshot, diagram or other information may be slightly outdated\footnote{even this one}.
 Also note that some PDF viewers have problems with vector graphics exported from Visual Paradigm, so if you feel like there is a missing line in a class or component diagram, you are wrong.
-You may want to use Internet Explorer 11, where this bug does not exist.
+We recommend Internet Explorer 11, where this bug does not exist.
 
 Yet another note: Some of our tables span multiple pages so make sure to always check the next and previous pages.
 This was necessary because our tables tend to get quite large.

+ 14 - 13
doc/chapter/2architecture.tex

@@ -13,8 +13,7 @@ Assumptions~\ref{itm:hyperedges},~\ref{itm:constraints} and~\ref{itm:labels} wer
 Assumption~\ref{itm:cross-hierarchy-edges} was made because these are not possible with the Sugiyama approach.
 
 Regarding assumption~\ref{itm:connected}, we found an example where for a disconnected graph the algorithm behaved incorrectly.
-Maybe we will get rid of this assumption later, see chapter~\ref{ch:progress}.
-This example is included in the appendix (figures~\ref{fig:error_disconnected_img} and~\ref{fig:error_disconnected}).
+This example is included in the appendix (figure~\ref{fig:error_disconnected}).
 
 
 \section{Overview}\label{sec:components}
@@ -43,7 +42,7 @@ Advantages of this architecture include:
 \end{figure}
 
 
-\section{System Requirements}\label{sec:systemRequirements}
+\section{System Requirements and Software Dependencies}\label{sec:systemRequirements}
 {
 \centering
 \small
@@ -67,7 +66,6 @@ Advantages of this architecture include:
 \end{longtable}
 }
 
-\section{Software Dependencies}\label{sec:softwareDependencies}
 {
 \centering
 \small
@@ -76,8 +74,8 @@ Advantages of this architecture include:
     \textbf{Dependency} && \textbf{Version} \\
     Java && $\geq8$ \\
     \rowcolor{gray!25}
-    JSON-java~\ref{leary_json-java:_2018} && \\
-    Eclipse Layout Kernel~\ref{noauthor_elk:_2018} && \\
+    JSON-java~\cite{leary_json-java:_2018} && \\
+    Eclipse Layout Kernel~\cite{noauthor_elk:_2018} && \\
     \\
     \caption[Software Dependencies]{Software Dependencies. If no version is given, all should work and the latest is recommended.}
     \label{table:softwareDependencies}
@@ -99,7 +97,9 @@ For parsing the JSON file the JSON-java library~\cite{leary_json-java:_2018} is
 The classes for reading and writing those JSON files are displayed in figure~\ref{fig:io}.
 The internal representation of graphs is further explained in the section~\ref{sec:graph}.
 
+{
 \centering
+\small
 \begin{longtable}{|l|l|l|p{8.5cm}|}
     \hline
     Attribute & Type & Optional & Explanation \\\hline\hline
@@ -118,7 +118,7 @@ The internal representation of graphs is further explained in the section~\ref{s
     \caption[Node Attributes]{Node Attributes. < \emph{element type} > is a list.}
     \label{table:node-attributes}
 \end{longtable}
-\raggedright
+}
 
 \begin{figure}[htp]
     \centering
@@ -129,6 +129,7 @@ The internal representation of graphs is further explained in the section~\ref{s
 
 \begin{table}[htp]
     \centering
+    \small
     \begin{longtable}{|l|l|l|p{8.5cm}|}
         \hline
         Attribute & Type & Optional & Explanation \\\hline\hline
@@ -151,16 +152,16 @@ The internal representation of graphs is further explained in the section~\ref{s
 \begin{figure}[htp]
     \begin{lstinputlisting}[language=json,emph={}]{src/graph.json}
     \end{lstinputlisting}
-    \caption[Example input file]{Example input file that is understood by \appname.}
+    \caption[Example input file]{Example input file that is understood by \appname.
+    The graph is also displayed in figure~\ref{fig:full-application-example}.}
     \label{fig:json-example}
 \end{figure}
 
 
 \section{Internal graph representation, \code{graph}}\label{sec:graph}
-One feature that is important to us, is to be able to work with hierarchical graphs (cf.\ chapter~\ref{ch:progress}).
+One feature that is important to us, is to be able to work with hierarchical graphs.
 Therefore a node can contain other nodes and edges.
-So far this is similar to what we described in section~\ref{sec:inputFileFormat}.
-Additionally, there are multiple attributes that are used during the computation or as output variables.
+In addition to the variables described in section~\ref{sec:inputFileFormat}, there are multiple attributes that are used during the computation or as output variables.
 \begin{itemize}
     \item The \member{parent} of a node is the node that contains it in the hierarchy.
     \item \member{dummy} specifies whether this node is a dummy node.
@@ -175,6 +176,7 @@ Additionally, there are multiple attributes that are used during the computation
 \end{itemize}
 The last six bullet points are available separately for each of the four extremal layouts.
 The last four bullet points are also separately available for the combined layout.
+To achieve this, they are stored in the internal classes \code{LayoutInfo} and \code{CombinedLayoutInfo}.
 
 Similarly, edges have the following attributes in addition to those given through the JSON format:
 \begin{itemize}
@@ -270,7 +272,6 @@ A class diagrams for the \code{processor} package is displayed in figure~\ref{fi
 \section{View}\label{sec:view}
 This section only covers the software architecture regarding the views.
 For an explanation of what is actually displayed, see chapter~\ref{ch:ui}
-\TODO{outdated}
 
 \begin{itemize}
     \item The main window displays a \code{JLayeredPane} on the right where the graph is shown and a \code{menu} of the class \code{JPanel} on the left, where \code{NiceButton}s and \code{PseudoCodeNode}s are located.
@@ -289,7 +290,7 @@ A class diagram of the package \code{view} is displayed in figure~\ref{fig:view}
 
 \begin{figure}[htp]
     \centering
-    \includegraphics[width=0.9\linewidth,trim=0 11cm 0 0,clip]{img/main_and_view.pdf}
+    \includegraphics[width=\linewidth,trim=0 11cm 0 0,clip]{img/main_and_view.pdf}
     \caption[Class diagram of the packages \code{view} and \code{main}]{Class diagram of the packages \code{view} and \code{main}.
     Getters, setters and contructors are not omitted because most of them perform nontrivial computations.}
     \label{fig:view}

+ 4 - 11
doc/chapter/3ui.tex

@@ -1,7 +1,6 @@
 Note that since the application is still under construction, so not all screenshots may be up to date.
 
 \section{Graphical presentation of the running algorithm}\label{sec:graphicalPresentationOfTheRunningAlgorithm}
-A first sketch of how we want \appname\ to look is shown in figure~\ref{fig:sketch}.
 The current development status is displayed in figure~\ref{fig:full-application-example}.
 Another example graph and an explanation of the shapes and colors is provided in figure~\ref{fig:example}.
 Figure~\ref{fig:originalpapergraph} compares our results to those of Brandes and Köpf~\cite{brandes_fast_2001}.
@@ -73,6 +72,9 @@ Currently the two main ways to interact with the application are keyboard events
 The possible keyboard inputs are listed in table~\ref{table:keys}.
 To improve the user experience even further, these can also be used by clicking on one of the buttons displayed in figure~\ref{fig:full-application-example}.
 
+{
+\centering
+\small
 \begin{longtable}{|l|p{12cm}|}
     \hline
     Key & Action \\\hline\hline
@@ -95,6 +97,7 @@ To improve the user experience even further, these can also be used by clicking
     The lazy user might not want to learn these by rote but instead use the buttons displayed in figure~\ref{fig:full-application-example}.}
     \label{table:keys}
 \end{longtable}
+}
 
 The decision to open new windows was made to save room in each single window.
 For example the fields for generating a random graph are rarely used, so the were chosen to be displayed in a separate dialog when needed.
@@ -102,13 +105,3 @@ For example the fields for generating a random graph are rarely used, so the wer
 There is one interaction that is available neither on keyboard nor on a button: Breakpoints.
 For this, the user performs a triple click on one of the lines in the pseudocode or a single click on one of the line numbers.
 Upon reaching the beginning of that stage (beginning in forwards direction) the automatic execution pauses.
-Imagine the following scenario:
-\begin{enumerate}
-    \item The user starts up \appname.
-    \item The user sets a breakpoint on \enquote{Extremal Layout: leftmost lower} (this is the third extremal layout in the order they are computed).
-    \item The user activates automatic forwards execution.
-    \item The algorithm pauses when reaching the first step of \enquote{Extremal Layout: leftmost lower}.
-    \item The user activates automatic forwards execution again.
-    \item After the stage of \enquote{Extremal Layout: leftmost lower} is roughly halfway finished, the user pauses the automatic execution and activates automatic \emph{backwards} execution.
-    \item The algorithm stops again, when it reaches the beginning of the stage.
-\end{enumerate}

+ 0 - 34
doc/chapter/5contributors.tex

@@ -1,34 +0,0 @@
-\begin{table}[ht]
-	\centering
-    \small
-    \begin{longtable}{p{7cm} p{7cm}}
-        \rowcolor{gray!50}
-		\textbf{Competency} & \textbf{Contributor} \\
-		Producer & Eren Bora Yilmaz \\
-        \rowcolor{gray!25}
-        Producer & Kolja Samuel Strohm \\
-		Lead Designer & Kolja Samuel Strohm \\
-        \rowcolor{gray!25}
-		Documentation & Eren Bora Yilmaz \\
-        Lead Systems Programmer & Kolja Samuel Strohm \\
-        \rowcolor{gray!25}
-		Lead Graphics Programmer & Kolja Samuel Strohm \\
-		Non-German Comments & Eren Bora Yilmaz \\
-        \rowcolor{gray!25}
-		Operations Director & Kolja Samuel Strohm \\
-        Director Of Quality Assurance & Eren Bora Yilmaz \\
-        \rowcolor{gray!25}
-		Senior Community Manager & Eren Bora Yilmaz \\
-		Lead Artist & Eren Bora Yilmaz \\
-        \rowcolor{gray!25}
-        Creative Director & Kolja Samuel Strohm \\
-        Localization Producer & Eren Bora Yilmaz \\
-        \rowcolor{gray!25}
-        Manual Code Formatting & Kolja Samuel Strohm \\
-        Black-Box Testing & Eren Bora Yilmaz \\
-        \\\\\rowcolor{gray!25}
-		Special Thanks & Jens Burmeister \\\\
-	\end{longtable}
-	\caption{Contributors}
-	\label{table:contributors}
-\end{table}

+ 73 - 40
doc/chapter/appendix.tex

@@ -1,21 +1,50 @@
-\begin{table}[ht]
-	\centering
+\begin{table}[htp]
+    \centering
     \small
-    \begin{longtable}{p{3cm} p{8cm} p{4cm}}
+    \begin{longtable}{p{7cm} p{7cm}}
         \rowcolor{gray!50}
-		\textbf{Term} & \textbf{Explanation} & \textbf{Example} \\
-		Phase & One phase of the Sugiyama approach~\cite{sugiyama_methods_1981} & Node Placement \\
+        \textbf{Competency} & \textbf{Contributor} \\
+        Producer & Eren Bora Yilmaz \\
         \rowcolor{gray!25}
-		Stage & One stage of the BK algorithm~\cite{brandes_fast_2001} & Balancing \\
-		Step & Atomic part of a stage of the BK algorithm~\cite{brandes_fast_2001} & Computing one $x$ coordinate during balancing stage \\
-		\rowcolor{gray!25}
-        \appname & The name of the application for which this is the documentation & \\
-        \member{sink} & See table~\ref{table:bk-variables} & \\
+        Producer & Kolja Samuel Strohm \\
+        Lead Designer & Kolja Samuel Strohm \\
+        \rowcolor{gray!25}
+        Documentation & Eren Bora Yilmaz \\
+        Lead Systems Programmer & Kolja Samuel Strohm \\
+        \rowcolor{gray!25}
+        Lead Graphics Programmer & Kolja Samuel Strohm \\
+        Non-German Comments & Eren Bora Yilmaz \\
+        \rowcolor{gray!25}
+        Operations Director & Kolja Samuel Strohm \\
+        Director Of Quality Assurance & Eren Bora Yilmaz \\
+        \rowcolor{gray!25}
+        Senior Community Manager & Eren Bora Yilmaz \\
+        Lead Artist & Eren Bora Yilmaz \\
+        \rowcolor{gray!25}
+        Creative Director & Kolja Samuel Strohm \\
+        Localization Producer & Eren Bora Yilmaz \\
+        \rowcolor{gray!25}
+        Manual Code Formatting & Kolja Samuel Strohm \\
+        Black-Box Testing & Eren Bora Yilmaz \\
+        \\\\\rowcolor{gray!25}
+        Special Thanks & Jens Burmeister \\\\
+    \end{longtable}
+    \caption{Contributors}
+    \label{table:contributors}
+\end{table}
+
+\begin{table}[ht]
+    \centering
+    \small
+    \begin{longtable}{p{4cm} p{7cm} l}
+        \rowcolor{gray!50}
+        \textbf{Term} & \textbf{Explanation} & \textbf{Example} \\
+        Phase & One phase of the Sugiyama approach~\cite{sugiyama_methods_1981} & Node Placement \\
         \rowcolor{gray!25}
-        \member{shift} & See table~\ref{table:bk-variables} & \\
-        \member{root} & See table~\ref{table:bk-variables} & \\
+        Stage & One stage of the BK algorithm~\cite{brandes_fast_2001} & Balancing \\
+        Step & Atomic part of a stage of the BK algorithm~\cite{brandes_fast_2001} & Initializing a \reserved{for}-loop \\
         \rowcolor{gray!25}
-        \member{align} & See table~\ref{table:bk-variables} & \\
+        \appname & The name of the application for which this is the documentation & \\
         Extremal layout & Defines in which order the layers are traversed and if a node is aligned with its upper or lower median. & Leftmost lower \\
         \rowcolor{gray!25}
         Automatic execution & The state of the \code{ProcessController} where it repeatedly sends step commands with a certain delay & See section~\ref{sec:userInterface} \\
@@ -23,22 +52,13 @@
         \rowcolor{gray!25}
         pseudocode & Code that does not clearly belong to a specific programming language.
         It can actually be executed, although we call it pseudocode. & see figure~\ref{fig:full-application-example} \\
-        step overrun & The state of the \code{ProcessController} where it repeatedly sends step commands, but only inserts a delay after steps whose line of pseudocode is currently unfolded in the pseudocode view. & See section~\ref{sec:userInterface} \\
-        \rowcolor{gray!25}
         Processor & See section~\ref{sec:theActualAlgorithm}. & \\
         \\\\
-	\end{longtable}
-	\caption{Glossary for the most difficult terms as we use them.}
-	\label{table:glossary}
+    \end{longtable}
+    \caption{Glossary for the most difficult terms as we use them.}
+    \label{table:glossary}
 \end{table}
 
-\begin{figure}[htp]
-    \centering
-    \includegraphics[width=0.33\linewidth]{img/random-graph-dialog}
-    \caption[Random graph dialog]{Dialog for generating random graphs.}
-    \label{fig:random-graph-dialog}
-\end{figure}
-
 \begin{figure}[htp]
     \centering
     \includegraphics[width=\linewidth]{img/debug-table}
@@ -46,25 +66,38 @@
     \label{fig:debug-table}
 \end{figure}
 
-\begin{figure}[htp]
-    \centering
-    \includegraphics[width=0.33\linewidth]{img/preferences}
-    \caption[Preferences]{The dialog for adjusting the preferences.}
-    \label{fig:preferences}
-\end{figure}
 
 \begin{figure}[htp]
-    \centering
-    \includegraphics[width=0.33\linewidth]{img/error_disconnected}
-    \caption[Error caused by disconnected graph]{An illustration of the error caused by the graph displayed in figure~\ref{fig:error_disconnected}.
-    In the lowest layer the two nodes are drawn at the same position.}
-    \label{fig:error_disconnected_img}
+    \begin{subfigure}[t]{.4\textwidth}
+        \centering
+        \includegraphics[width=0.8\linewidth]{img/random-graph-dialog}
+        \caption[Random graph dialog]{Dialog for generating random graphs.}
+        \label{fig:random-graph-dialog}
+    \end{subfigure}
+    \begin{subfigure}[t]{.6\textwidth}
+        \centering
+        \includegraphics[width=0.9\linewidth]{img/preferences}
+        \caption[Preferences]{The dialog for adjusting the preferences.}
+        \label{fig:preferences}
+    \end{subfigure}
+    \caption[Dialogs]{Dialogs}
+    \label{fig:dialogs}
 \end{figure}
 
+
 \begin{figure}[htp]
-    \begin{lstinputlisting}[language=json,emph={},basicstyle=\scriptsize\ttfamily,numberstyle=\tiny]{src/error_disconnected.json}
-    \end{lstinputlisting}
-    \caption[Disconnected graph causing an error]{Example graph where the node placement algorithm does not behave correctly, possibly because it is not connected.
-    The error is illustrated in figure~\ref{fig:error_disconnected_img}.}
+    \begin{subfigure}[b]{.5\textwidth}
+        \begin{lstinputlisting}[language=json,emph={},basicstyle=\tiny\ttfamily,numberstyle=\tiny]{src/error_disconnected.json}
+        \end{lstinputlisting}
+        \caption{A disconnected graph causing an error}
+        \label{fig:error_disconnected_json}
+    \end{subfigure}
+    \begin{subfigure}[b]{.5\textwidth}
+        \centering
+        \includegraphics[width=0.7\linewidth]{img/error_disconnected}
+        \caption[Illustration of the disconnected graph causing an error]{\code{n6} and \code{n7} drawn on each other}
+        \label{fig:error_disconnected_img}
+    \end{subfigure}
+    \caption[Error in disconnected graph]{Example graph where the node placement algorithm does not behave correctly, possibly because it is not connected.}
     \label{fig:error_disconnected}
 \end{figure}

+ 2 - 1
doc/custom_hyphenations.tex

@@ -10,4 +10,5 @@
 \hyphenation{re-con-struc-tion}
 \hyphenation{rou-tings}
 \hyphenation{Aa-chen}
-\hyphenation{Sa-bour}
+\hyphenation{Sa-bour}
+\hyphenation{back-wards}

+ 2 - 5
doc/doc.tex

@@ -221,9 +221,9 @@ frame=tb}
         Kolja Samuel Strohm (1036051)\\
         Summer term 2018\\
         \vspace{8mm}
-	    \includegraphics[width=10cm]{img/logo}
+	    \includegraphics[height=10cm]{img/logo}
     \end{center}
-    \clearpage\null\clearpage
+    \clearpage%\null\clearpage
 
     \pagestyle{scrheadings} %Seitenstil festlegen, damit die folgenden Einträge auch wirksam sind
     \cfoot*{\pagemark} %center, Fuß
@@ -260,9 +260,6 @@ frame=tb}
     \chapter{Retrospection}
     \input{chapter/4retrospection}
 
-    \chapter{Contributors}
-    \input{chapter/5contributors}
-
     \appendix
     \chapter{Appendix}\label{ch:appendix}
     \input{chapter/appendix}

BIN
doc/img/error_disconnected.png


BIN
doc/img/logo.png


BIN
doc/img/preferences.png


+ 9 - 38
doc/src/error_disconnected.json

@@ -1,44 +1,15 @@
 {
    "layers":[
-      [
-      { "name": "n0" },
-      { "name": "n1" },
-      { "name": "n2" }
-      ],
-      [
-      { "name": "n3" },
-      { "name": "n4" },
-      { "name": "n5" }
-      ],
-      [
-      { "name": "n6" },
-      { "name": "n7" }
-      ]
+      [ { "name": "n0" }, { "name": "n1" }, { "name": "n2" } ],
+      [ { "name": "n3" }, { "name": "n4" }, { "name": "n5" } ],
+      [ { "name": "n6" }, { "name": "n7" } ]
    ],
    "edges":[
-      {
-         "source":"n0",
-         "target":"n5"
-      },
-      {
-         "source":"n1",
-         "target":"n5"
-      },
-      {
-         "source":"n2",
-         "target":"n5"
-      },
-      {
-         "source":"n3",
-         "target":"n7"
-      },
-      {
-         "source":"n4",
-         "target":"n7"
-      },
-      {
-         "source":"n5",
-         "target":"n7"
-      }
+      { "source":"n0", "target":"n5" },
+      { "source":"n1", "target":"n5" },
+      { "source":"n2", "target":"n5" },
+      { "source":"n3", "target":"n7" },
+      { "source":"n4", "target":"n7" },
+      { "source":"n5", "target":"n7" }
    ]
 }