Copyedit GUI building section

doc/Client.md

@@ -6,7 +6,7 @@
 :glob:
 :titlesonly:
 
-client/GUI-Getting-Started
+client/GUI-Building
 client/GUI-Coding
 client/GUI-Testing
 client/GUI-Eclipse

doc/Editing-the-Wiki.md

@@ -146,3 +146,11 @@ This is a tip!
 :::
 
 The list of supported admonitions is [on the MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html).
+
+## Removing & deleting pages
+
+When moving pages, it is helpful to add redirects to the new location, so that links external to the wiki continue to
+work. To do this, we are using the [`sphinx-reredirects`](https://documatt.com/sphinx-reredirects/usage/) plugin.
+
+When moving a page, add a redirect from the old location to the new location. When deleting a page, add a redirect to
+the most suitable alternative documentation. The redirects are configured by the `redirects` key in `doc/conf.py`.

doc/Script-Generator.md

@@ -22,7 +22,7 @@ script_generator/*
 | Standalone app build directories | `base/uk.ac.isis.scriptgenerator/*` |
 
 ## Eclipse build
-To build and run the app through eclipse, the script generator product is found in `base\uk.ac.stfc.isis.scriptgenerator.client.product`. The instructions for setting up eclipse and loading the target platform (necessary for the script generator) are found in the instructions for the [main IBEX GUI setup](/client/getting_started/Building-the-GUI)
+To build and run the app through eclipse, the script generator product is found in `base\uk.ac.stfc.isis.scriptgenerator.client.product`. The instructions for setting up eclipse and loading the target platform (necessary for the script generator) are found in the instructions for the [main IBEX GUI setup](/client/compiling/Building-the-GUI)
 
 {#scriptgenerator_enable_perspective}
 ### Adding the perspective into the client

doc/client/GUI-Building.md

@@ -0,0 +1,8 @@
+# Building
+
+```{toctree}
+:glob:
+:titlesonly:
+
+compiling/*
+```

doc/client/GUI-Troubleshooting.md

@@ -11,6 +11,15 @@ The following pages also contain GUI troubleshooting information for specific pr
 troubleshooting/*
 ```
 
+## Display resolution & scaling
+
+If the GUI loads up but items are the wrong size, you may need to change your display settings. The exact settings that
+you need may vary from computer to computer. This is a common issue on Windows 10 machines due to the OS' scaling
+setting for text, icons etc. that is meant to ensure they do not look too small on high screen resolutions. 
+
+Generally a resolution of 1920 x 1080 with a scaling factor of 100% should look correct on standard screens. You can
+increase both of those settings slightly if you feel like the display elements look uncomfortably small.
+
 ## IBEX appears fullscreen with top menu items hidden
 
 Solution: right click inside any OPI and select "exit full screen".
@@ -95,7 +104,6 @@ Add `Eclipse-BundleShape: dir` in the `MANIFEST.MF`; see the `.opis` `MANIFEST.M
 This makes the maven build build the directory into a directory rather than a jar, which is sometimes necessary to let eclipse then "see" the files natively on the filesystem. If you look in the `plugins/` folder of a built client you should see a folder for `.opis` but a `.jar` for most other ibex modules - except for a few that need to be built as directories, as you may be finding.
 
 
-
 ## Other issues
 ### Remote debugging with Eclipse
 The following has been done to ensure that it is possible to debug the IBEX GUI running on any particular instrument:

doc/client/compiling/Building-the-GUI.md

@@ -0,0 +1,114 @@
+# Building the GUI
+
+:::{important}
+Before following this guide, ensure you have completed the following steps from
+[the first-time installation guide](/overview/First-Time-Build):
+- [Install Java JDK](#first_time_install_java)
+- [Install Maven](#first_time_install_maven)
+- [Install Git](#first_time_install_git)
+- [Install Python (Uktena)](#first_time_install_uktena)
+:::
+
+{#gui_build_checkout_code}
+## Checking out the code
+
+Development builds of the IBEX GUI are conventionally located in `c:\instrument\dev`. Create this folder if it
+doesn't already exist.
+
+From a windows command prompt, navigate to `c:\instrument\dev` and run:
+
+```
+git clone --recursive https://github.com/ISISComputingGroup/ibex_gui.git
+```
+
+The code for the IBEX GUI will now be located in `c:\instrument\dev\ibex_gui`.
+
+A [pre-commit hook](https://github.com/ISISComputingGroup/IBEX/issues/4786) should now be installed; to do this, run:
+
+```
+cd c:\instrument\dev\ibex_gui\build
+install_pre_commit_hook.bat
+```
+
+{#gui_build_install_eclipse}
+## Installing Eclipse
+
+You must use a version of eclipse which supports the RCP and Java versions currently in use by the client. There are
+two options for this:
+- Download a recent Eclipse version directly from
+[the eclipse website](https://www.eclipse.org/downloads/packages/); choose the package for "RCP and RAP developers"
+- Use the most recent version in `\\isis\inst$\Kits$\CompGroup\ICP\Developer Tools` (which is simply a download from
+the Eclipse website, at a specific version).
+
+By convention eclipse versions are installed into `c:\tools`, for example in 
+`c:\tools\eclipse-rcp-2024-06-R-win32-x86_64`.
+
+After installing eclipse from either of the above sources, you will need to add the line
+```
+-Djdk.util.zip.disableZip64ExtraFieldValidation=true
+``` 
+to the end of `eclipse.ini` (located next to the `eclipse.exe` executable), if it is not already present.
+
+{#gui_build_via_eclipse}
+## Building in Eclipse
+
+:::{seealso}
+If at any point during these instructions you get errors, there are troubleshooting notes for Eclipse
+[here](../eclipse/Common-Eclipse-Issues) and for the GUI in general [here](../GUI-Troubleshooting).
+:::
+
+The first time the Eclipse IDE is started, it will ask you for a folder to use as a workspace. 
+Unless you have a specific reason to choose a different location, use `c:\Instrument\dev\eclipse_workspaces\ibex_gui` 
+(create this folder if it doesn't already exist).
+
+![](eclipse_workspace_selection.png)
+
+From the menu bar choose File -> Import -> General -> Existing Projects into Workspace.
+Choose "Select root directory" and browse to `c:\Instrument\dev\ibex_gui\base`. You should now see a list of plugins 
+to import with names like `uk.ac.stfc.isis.ibex.*`. Eclipse should automatically select everything so you just need 
+to click "Finish" to add them to the project. 
+
+:::{tip}
+If "Marketplace solutions available" dialogues appear, click cancel; these will be obtained later.
+:::
+
+<img src="eclipse_import_ibex_gui.png" width=400>
+
+From the "Project Explorer" tab on the left, expand the target platform folder (labelled as 
+`uk.ac.stfc.isis.ibex.targetplatform`), double click on the `targetplatform.target` file and choose 
+"Set as Active Target Platform". This may take some time as dependencies are downloaded - there is a progress bar
+in the very bottom-right of the Eclipse IDE.
+
+Once the target platform has finished downloading, the target platform view should look like this:
+
+<img src="eclipse_target_platform_view.png" width=600>
+
+To run the application from within Eclipse: open `ibex.product` from the `uk.ac.stfc.isis.ibex.e4.client.product`
+folder, select "Launch an Eclipse application". The IBEX GUI should now open.
+
+Next, From the menu bar choose Run->Run configurations and select `ibex.product` from the left hand list under 
+"Eclipse Application". In the "Main" tab, in **Run configurations**, tick the "Clear" tick box and untick the 
+"Ask for confirmation before clearing".
+
+<img src="eclipse_clear_workspace.png" width=400>
+
+In the "Configuration" tab, tick the "Clear the configuration area before launching" tick box, then click "Apply" 
+and select "Run".
+
+Lastly, you should [set up checkstyle](../eclipse/Checkstyle-setup).
+
+{#gui_build_via_maven}
+## Building via Maven
+
+Firstly, ensure you have a recent Maven version installed. Generally a suitable version will be the highest version
+number in `\\isis\inst$\Kits$\CompGroup\ICP\Binaries`. You can double-check your current Maven version by running
+`mvn -v` in a command prompt.
+
+To build using Maven, run:
+
+```
+cd c:\Instrument\dev\ibex_gui\build
+build.bat
+```
+
+Once the build finishes, the IBEX client executable can be found in `.\built_client\`.

doc/client/compiling/Maven-and-Tycho.md

@@ -0,0 +1,135 @@
+# Maven and Tycho
+
+The IBEX GUI is built using Tycho, which is a Maven plugin used for building Eclipse RCP products.
+
+This document provides a brief overview of both Maven and Tycho.
+
+:::{seealso}
+[Code chats](/processes/meetings/Code-Chats-and-Lightning-Talks) have been given on this topic (
+[slides](https://stfc365.sharepoint.com/:p:/r/sites/ISISExperimentControls/ICP%20Discussions/GUI_Chat_Slides/IBEX%20GUI%20build%20system.pptx?d=w74aa3046025f4622bcdeadbdeca9395c&csf=1&web=1&e=aQEGJZ),
+[recording](https://stfc365.sharepoint.com/sites/ISISExperimentControls/_layouts/15/stream.aspx?id=%2Fsites%2FISISExperimentControls%2FICP%20Discussions%2FGUI%5FChat%5FSlides%2FIBEX%20GUI%20build%20System%20Code%20chat%2Emp4&referrer=StreamWebApp%2EWeb&referrerScenario=AddressBarCopied%2Eview&referrer=StreamWebApp%2EWeb&referrerScenario=AddressBarCopied%2Eview%2E0f53ae8b%2D3184%2D43c1%2D955e%2D039109fcd0e1)
+).
+:::
+
+## Maven
+
+The official description:
+
+> _Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model
+> (POM), Maven can manage a project's build, reporting and documentation from a central piece of information._
+
+In simple terms, Maven is a build automation tool used primarily for Java projects.
+
+See the [getting started guide in the Maven documentation](https://maven.apache.org/guides/getting-started/index.html)
+for more information about what Maven is.
+
+### POM files
+
+POM files are XML files, called `pom.xml`, that describes the software project being built, its dependencies on other
+external modules and components, the build order, directories, and required plug-ins. In many ways, it can be considered
+the equivalent of a C-style Makefile as it defines how the project is built.
+
+See [the Maven documentation](https://maven.apache.org/pom.html) for detailed information on the various sections of a
+`pom.xml` in a pure Maven project.
+
+### Building a Maven project
+
+Maven uses multiple build phases - for example, `compile`, `test`, `package`. If you are really unsure, a good
+default is to run `mvn clean verify` to build a project; this will clean the project (deleting any old build files),
+and then run compilation, unit tests, packaging, and verification (e.g. checkstyle) phases.
+
+For more information, see the Maven
+[build lifecycle documentation](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html).
+
+## Tycho
+
+Tycho is a set of Maven plugins and extensions for building Eclipse-based applications with Maven. Tycho allows Maven
+to support building bundles, fragments, features, P2 repositories, RCP applications etc.
+
+Tycho is used to build the IBEX GUI application.
+
+### Parent POM
+
+Maven allows a parent POM to be defined which contains references to the other POM files for the other projects that
+make up an application. This is used in the IBEX GUI because it allows the centralisation of the settings for
+building the application.
+
+The [IBEX GUI parent `pom.xml`](https://github.com/ISISComputingGroup/ibex_gui/blob/master/base/uk.ac.stfc.isis.ibex.client.tycho.parent/pom.xml)
+contains a lot of information, so here is a stripped down version to show the key points:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>CSS_ISIS</groupId>
+    <artifactId>uk.ac.stfc.isis.ibex.client.tycho.parent</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <properties>
+        <tycho.version>4.0.9</tycho.version>
+        <tycho-repo.url>https://oss.sonatype.org/content/groups/public/</tycho-repo.url>
+        <photon-repo.url>http://download.eclipse.org/releases/2024-09</photon-repo.url>
+        <photon-updates-repo.url>http://download.eclipse.org/eclipse/updates/4.33</photon-updates-repo.url>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <repositories>
+        <repository>
+            <id>photon-updates</id>
+            <layout>p2</layout>
+            <url>${photon-updates-repo.url}</url>
+        </repository>
+    </repositories>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.eclipse.tycho</groupId>
+                <artifactId>tycho-maven-plugin</artifactId>
+                <version>${tycho.version}</version>
+                <extensions>true</extensions>
+            </plugin>
+            <!-- Other maven plugins omitted such as unit testing and checkstyle -->
+        </plugins>
+    </build>
+
+    <modules>
+        <module>../uk.ac.stfc.isis.ibex.client.product</module>
+        <module>../uk.ac.stfc.isis.ibex.feature.base</module>
+        <!-- Other modules that make up IBEX would be listed here -->
+        <module>../uk.ac.stfc.isis.ibex.ui.mainmenu.tests</module>
+    </modules>
+</project>
+```
+
+Let's explain the various parts shown:
+* At the top we have the standard Maven metadata: `groupId`, `artifactId`, `version`.
+* The properties section is used to define URLs for the Tycho plugin and the Eclipse RCP framework. The versions here
+are updated periodically during [dependency updates](/processes/dev_processes/Dependency-Updates)
+* The repositories section tells Maven to look for a repository for the Eclipse RCP framework version specified above
+* The build section defines the Maven plugins necessary to build the application. The Tycho plugin entry tells Maven to
+download Tycho and use it as part of the build process
+* The modules section lists the locations of the POM files for the various modules that make up the application. When a
+new module is added to IBEX, it will need to be added to this list.
+
+### Child POM
+
+A typical child POM look like
+[this](https://github.com/ISISComputingGroup/ibex_gui/blob/master/base/uk.ac.stfc.isis.ibex.dashboard/pom.xml).
+It is very simple - it points at the parent POM to get most of its information. These is one of these `pom.xml` files
+for each module that makes up the IBEX client.
+
+The packaging type is defined as `eclipse-plugin`; this is a packaging type defined by Tycho. Other Tycho types used in
+IBEX are `eclipse-feature` for features, `eclipse-test-plugin` for fragment projects that define unit tests and
+`eclipse-repository` for configuring builds.
+
+### Application POM
+
+In IBEX we define a separate project called `uk.ac.stfc.isis.ibex.e4.client.product` which defines how the product is 
+built. It has a 
+[POM file](https://github.com/ISISComputingGroup/ibex_gui/blob/master/base/uk.ac.stfc.isis.ibex.e4.client.product/pom.xml)
+of packaging type `eclipse-repository`.
+
+The key area is the `materialize-products` section, this tells Tycho to actually create the product. Without this Maven
+will compile & unit test the code, but will not produce an executable.

doc/client/eclipse/Common-Eclipse-Issues.md

@@ -4,7 +4,8 @@ Sometimes the error messages that Eclipse gives are a little opaque, so here are
 
 ## Plugin execution not covered by lifecycle configuration
 
-Go to window -> preferences -> Maven -> Errors/Warnings. Change "Plugin execution not covered by lifecycle configuration" to ignore in the drop down.
+Go to window -> preferences -> Maven -> Errors/Warnings. 
+Change "Plugin execution not covered by lifecycle configuration" to ignore in the drop down.
 
 ## The type XXXXXXX cannot be resolved. It is indirectly referenced from required .class files
 
@@ -122,8 +123,25 @@ Sometimes when you check out a new branch in the ibex GUI repository, you won't
 
 1. In Eclipse, remove all the projects from the workspace and close Eclipse.
 1. Then, while checked out to the branch you want to see the changes on, perform a `git clean -fdx && git reset HEAD --hard` to reset the git repository. This will remove any changes you have made to the branch.
-1. Restart Eclipse and repeat the steps to get the GUI working from [Building the GUI](../getting_started/Building-the-GUI).
+1. Restart Eclipse and repeat the steps to get the GUI working from [Building the GUI](../compiling/Building-the-GUI).
 
 ## Build fails with `[ERROR] Failed to resolve target definition ... targetplatform.target: Could not find "org.eclipse.e4.tools.spies.feature.feature.group..." in the repositories of the current location`
 
 This probably means that our pinned target has gone out of date and needs updating. Open the Eclipse IDE and click on `org.eclipse.tools/latest` and click `update` this should fail and show `Unable to locate installable unit ...`. To fix this remove the plugin and then add it from the `software site `, work with `org.eclipse.e4.core.tools.update - http://download.eclipse.org/e4/snapshots/org.eclipse.e4.tools/latest` then you add `Eclipse E4 - All Spies`.
+
+## Validation error in target platform `jython` manifests
+
+Make sure that `-Djdk.util.zip.disableZip64ExtraFieldValidation=true` is included in `eclipse.ini` (located right next
+to the `eclipse.exe` executable).
+
+## `java.lang.UnsupportedClassVersionError`
+
+If you see a `java.lang.UnsupportedClassVersionError` error at runtime, then:
+- Select Window -> Preferences -> Java -> Compiler
+- Set compliance level to 21.
+
+## Adding a dictionary to Eclipse's spelling checker
+
+- In Eclipse open `Window > Preferences > General > Editors > Text Editors > Spelling`
+- Change the "User defined dictionary" to `<ISIS Experiment Controls Shares>/Eclipse settings/code_dictionary.txt`
+

doc/client/eclipse/Common-Eclipse-Tasks.md

@@ -127,8 +127,7 @@ public class FooDisplay extends Canvas
 
 Instructions on adding a new perspective can be found [here](../coding/Adding-a-Button-to-the-Perspective-Switcher).
 
-Add A Preference Page
----------------------
+## Add A Preference Page
 
 Many plugins may have options that you want the user of the client to be able to configure. The simplest way to achieve this is to have the plugin contribute a preference page to the client's preference window.
 
@@ -296,7 +295,3 @@ The ``plugin.xml`` should now resemble:
 </plugin>
 ```
 The menu should now be visible in the client UI. For more details see the [Vogella menus tutorial](http://www.vogella.com/tutorials/EclipseCommands/article.html).
-
-## Add A Third Party Library To A Plugin
-
-To do