From 38e0dfd6833baa7ee606ca251a489ed347aa708d Mon Sep 17 00:00:00 2001
From: Damien Regad <dregad@mantisbt.org>
Date: Wed, 25 Nov 2020 14:16:59 +0100
Subject: [PATCH] Improve setup documentation for relationship graphs

Fixes #27584
---
 .../Admin_Guide/en-US/config/relationship.xml | 42 +++++++++++++++----
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/docbook/Admin_Guide/en-US/config/relationship.xml b/docbook/Admin_Guide/en-US/config/relationship.xml
index f26ae12ff9..df78adb267 100644
--- a/docbook/Admin_Guide/en-US/config/relationship.xml
+++ b/docbook/Admin_Guide/en-US/config/relationship.xml
@@ -5,6 +5,41 @@
 <section id="admin.config.relationship">
 	<title>Relationship Graphs</title>
 
+	<para>MantisBT can display a graphical representation of the relationships
+		between issues. Two types of interactive visualizations are available,
+		<emphasis>dependencies</emphasis> and a full
+		<emphasis>relationships</emphasis> graph.
+	</para>
+
+	<important>
+		<para>This feature relies on the external
+			<emphasis>dot</emphasis> and <emphasis>neato</emphasis> tools
+			from the <ulink url="https://www.graphviz.org/">GraphViz</ulink>
+			library, which must be installed separately.
+		</para>
+		<para>Most Linux distributions have a GraphViz package available
+			for easy download and install.
+		</para>
+		<para>Under Windows, the software needs to be installed manually.
+			The following post-installation steps
+			<ulink url="https://mantisbt.org/bugs/view.php?id=27584#c64693">may be required</ulink>
+			for proper operations:
+			<itemizedlist>
+				<listitem>
+					<para>Update the system PATH to point to GraphViz's
+						<literal>bin</literal> directory
+					</para>
+				</listitem>
+				<listitem>
+					<para>Initialize the graph engine by running
+						<literal>dot -c</literal>
+						from an <emphasis>Administrator</emphasis> command prompt.
+					</para>
+				</listitem>
+			</itemizedlist>
+		</para>
+	</important>
+
 	<variablelist>
 		<varlistentry>
 			<term>$g_relationship_graph_enable</term>
@@ -14,13 +49,6 @@
 					nodes and relationships as links between such nodes.  Possible values are ON or OFF.
 					Default is OFF.
 				</para>
-				<note>
-					<para>This feature requires installing the
-						<ulink url="https://www.graphviz.org/">GraphViz</ulink> library.
-						Refer to the notes near the top of <filename>core/graphviz_api.php</filename>
-						and <filename>core/relationship_graph_api.php</filename> for more information.
-					</para>
-				</note>
 			</listitem>
 		</varlistentry>
 		<varlistentry>