Clarify callbacks, highlighting, minor stuff

Author: florian-beetz

Makefile

@@ -6,10 +6,10 @@ FILTERS = -F "filters/abbrevs.py" -F "filters/pandoc-svg.py" -F pandoc-crossref
 all: $(NAME).pdf
 
 $(NAME).pdf: $(NAME).tex
-	latexmk -interaction=nonstopmode -pdf $(NAME).tex
+	latexmk -g -interaction=nonstopmode -pdf $(NAME).tex
 
 $(NAME).tex: $(FILES)
-	pandoc -o $@ --biblatex --template template.latex $(FILTERS) $(FILES)
+	pandoc -o $@ --highlight-style=tango --biblatex --template template.latex $(FILTERS) $(FILES)
 
 graphics:
 	@for svg in `find images/*.svg`;	\

ReleaseChecklist.md

@@ -7,4 +7,5 @@ Things that need to be done before release.
 * [ ] Check cite ordering
 * [ ] Update syntax highlighting
 * [ ] Check citations in listings
-* [ ] Check for `code` in listing captions
+* [ ] Check for `code` in listing captions
+* [ ] Set \DataTypeTok to \KeywordTok

images/future_based.pdf

@@ -0,0 +1,61 @@
+\documentclass[crop,tikz]{standalone}
+\usetikzlibrary{positioning,arrows,fit,calc}
+\pgfdeclarelayer{bg}
+\pgfsetlayers{bg,main}
+\tikzset{
+	>=stealth'
+}
+\usepackage{tikz-uml}
+\begin{document}
+\begin{tikzpicture}[
+node distance = 10mm,
+every node/.style = {
+	font = \sffamily
+},
+instance/.style = {
+	draw,
+	minimum height = 1.5\baselineskip,
+	thick
+},
+lifeline/.style = {
+	dotted,
+	thick
+},
+activity/.style = {
+	draw,
+	fill=white,
+	minimum width = 0.5cm	
+}
+]
+
+\node[instance] (gui) {:GUI Thread};	
+\node[instance, right=of gui] (background) {:Background Thread};
+\umlactor[left=1.3cm of gui, yshift=2mm] {User};
+\node[above=-2mm of User] {User};
+
+
+\draw[lifeline] (gui.south) -- +(0,-6);
+\draw[lifeline] (background.south) -- +(0,-6);
+\node[below=-3mm of User, fill=white, minimum height=0.75cm, minimum width=2cm] {};
+\draw[lifeline, yshift=2mm] (gui.south -| User.south) -- +(0,-6);
+
+\node[activity, below=4mm of gui, minimum height=0.5cm] (call) {};
+\node[activity, below=4mm of background, minimum height=4cm] (exec) {};
+
+\draw[->] (call) -- node[above]{verifyDuplicates()} (call -| exec.west);
+
+\node[activity, below=40mm of gui, minimum height=1.5cm] (success) {};
+
+\draw[->, dashed] (exec.262) -- node[above]{success} (exec.262 -| success.east);
+
+\draw[->] (success) -- +(5mm,0) |- node[right, yshift=3mm] {handleDuplicates()} (success.295);
+
+\node[activity, below=12mm of User, minimum height=2cm] (interaction) {};
+\node[activity, below=16mm of gui, minimum height=17mm] (action) {};
+
+\draw[->] (interaction.70) -- (interaction.70 -| action.west);
+\draw[->, dashed] (action.250) -- (action.250 -| interaction.east); 
+
+\end{tikzpicture}
+	
+\end{document}

images/future_based.svg

@@ -47,33 +47,6 @@
 \IfFileExists{upquote.sty}{\usepackage{upquote}}{}
 % use microtype if available
 \IfFileExists{microtype.sty}{\usepackage{microtype}}{}
-\usepackage{color}
-\usepackage{fancyvrb}
-\newcommand{\VerbBar}{|}
-\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
-\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
-% Add ',fontsize=\small' for more characters per line
-\usepackage{framed}
-\definecolor{shadecolor}{RGB}{248,248,248}
-\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
-\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{{#1}}}}
-\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{{#1}}}
-\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{{#1}}}
-\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{{#1}}}
-\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{{#1}}}
-\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{{#1}}}
-\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{{#1}}}
-\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{{#1}}}}
-\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{{#1}}}
-\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{{#1}}}
-\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{{#1}}}
-\newcommand{\RegionMarkerTok}[1]{{#1}}
-\newcommand{\ErrorTok}[1]{\textbf{{#1}}}
-\newcommand{\NormalTok}[1]{{#1}}
-\newcommand{\BuiltInTok}[1]{{#1}}
-\newcommand{\SpecialCharTok}[1]{\StringTok{#1}}
-\newcommand{\ImportTok}[1]{{#1}}
-\newcommand{\ExtensionTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{{#1}}}}
 
 %
 % Einbindung des Grafik-Pakets

images/future_based.tex

@@ -5,6 +5,9 @@
 $for(header-includes)$
 $header-includes$
 $endfor$
+$if(highlighting-macros)$
+$highlighting-macros$
+$endif$
 
 \addbibresource{$bibliography$}
 %

includes/config.tex

@@ -398,7 +398,7 @@ its dependencies as mentioned in [@sec:j9_adv]. This is done using a module
 descriptor, a file called `module-info.java` in the root package, that will be
 compiled as classes to a file called `module-info.class` [@Mac2017]. 
 [@lst:module-desc] shows the module descriptor of the default Java module
-`java.prefs` that contains Java's Preferences +API as an example^[All examples in [@sec:j9_impl] were taken from the source code of Oracle's JDK version 9.0.4. The source code is available in `${JAVA_HOME}/lib/src.zip`.].
+`java.prefs` that contains Java's Preferences +API as an example^[Most examples in [@sec:j9_impl] were taken from the source code of Oracle's JDK version 9.0.4. The source code is available in `${JAVA_HOME}/lib/src.zip`.].
 
 ```{#lst:module-desc .java caption="Excerpt of Module Descriptor of `java.prefs`"}
 module java.prefs {
@@ -1028,6 +1028,31 @@ open module org.jabref {
 }
 ```
 
+An event bus is an implementation of the Observer pattern, implementing a
+publish-subscribe style communication.
+The event bus handles the dispatching of events without requiring publishers to
+explicitly know who the subscribers are or vice-versa.
+As shown in [@lst:guava], Guava uses annotations, such as the `@Subscribe`
+annotation, to register event listeners in an event bus.
+Those annotations are accessed using reflection, thus Guava requires the
+packages to be open.
+Since the event bus is an integral part of JabRef and is used across many
+packages, the whole module was declared as open, instead of opening each package
+on its own.
+
+```{#lst:guava .java caption="Excerpt of JabRef's `BibDatabase`"}
+package org.jabref.model.database;
+// [...]
+public class BibDatabase {
+    // [...]
+    @Subscribe
+    private void relayEntryChangeEvent(FieldChangedEvent event) {
+        eventBus.post(event);
+    }
+    // [...]
+}
+```
+
 ## Upgrading Libraries
 
 In the second iteration the focus lay on updating the libraries removed in
@@ -1098,10 +1123,11 @@ libraries.
 | 2018-04-28    | Bug report created                                           |
 | 2018-05-18    | Code contribution provided                                   |
 | 2018-05-29    | Proposed fix accepted by library maintainer                  |
-| 2018-xx-xx    | Version including fix published                              |
 
 : Timeline of the bug report for latex2unicode {#tbl:l2u-split}
 
+The maintainer of latex2unicode accepted the code contribution, but no version
+including the fixes were released as of writing.
 The maintainer of the dependencies fastparse and sourcecode remained 
 unresponsive to the proposed fixes both provided on 2018-05-18 as of writing.
 Possible solutions to work around the problem include providing a manually 
@@ -1131,7 +1157,7 @@ The problem was reported to the library maintainers of ApplicationInsights^[[htt
 | ------------- | ------------------------------------------------------------ |
 | 2018-05-05    | Bug Report Created                                           |
 | 2018-06-08    | Bug fixed by maintainers of the library                      |
-| 2018-xx-xx    | Version including fix published                              |
+| 2018-07-31    | Version including fix published                              |
 
 : Timeline of the bug report of missed package relocation in Google Guava {#tbl:ai-split}
 
@@ -1202,14 +1228,23 @@ BackgroundTask.wrap(this::verifyDuplicates)
               .executeWith(Globals.TASK_EXECUTOR);
 ```
 
-**To do: explain this more**
-
 [@lst:background_task] shows how background tasks are used in JabRef. The
 method `verifyDuplicates` is executed on a thread of the `Globals.TASK_EXECUTOR`
 executor service. When the verification of duplicates succeeds the method
 `handleDuplicates` is called on the JavaFX +GUI thread, failures are not handled
 in this case.
 
+![Interaction of the Callbacks between Threads](images/future_based.svg){#fig:callbacks}
+
+[@fig:callbacks] shows the interaction of the +GUI thread and the background
+thread.
+While the time-consuming action -- in this case `verifyDuplicates()` -- is 
+called on the background thread, the +GUI thread stays responsive and can handle
+user interactions.
+Once the action is finished, either the success case -- here
+`handleDuplicates()` -- or an error case is executed on the +GUI thread to give
+the user feedback.
+
 # Modularizing JabRef {#sec:modularization}
 
 **To do: only runnable with restrictions**
@@ -1274,7 +1309,8 @@ Second, the dependency on the Preferences module could be removed. Depending on
 the type of the dependency this may be a viable solution, for example if 
 alternatives for the used functionalities are available. In this case however,
 removing the dependency would have lead to code duplication, which is often
-unfavorable for enabling good software maintainability.
+unfavorable for enabling good software maintainability, because the duplicated
+code would then need to be maintained in both instances.
 
 Third, the components Logic and Preferences could be joined in one module. This
 would weaken the encapsulation of the components, but especially if there