docs

Author: SimonCropp

docs/diff-tool.md

@@ -149,6 +149,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_BeyondCompare`
   * Supported binaries: .7z, .bcpkg, .bin, .bmp, .bz, .bz2, .cab, .chm, .deb, .ear, .gif, .gz, .ico, .img, .iso, .iso, .jar, .jpeg, .jpg, .kmz, .nupkg, .pdf, .png, .rar, .rpm, .rtf, .svg, .swm, .tar, .tbz, .tbz2, .tbz2, .tgz, .tif, .tiff, .war, .webp, .wim, .xlsx, .xz, .zip, .zipx
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise BeyondCompare over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.BeyondCompare);
+```
+
 #### Notes:
 
  * [Command line reference](https://www.scootersoftware.com/v4help/index.html?command_line_reference.html)
@@ -211,6 +219,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_DeltaWalker`
   * Supported binaries: .bmp, .bz2, .doc, .docx, .ear, .gif, .gz, .htm, .html, .ico, .j2k, .jar, .jp2, .jpg, .pbm, .pct, .pdf, .pgm, .pic, .pict, .png, .pnm, .ppm, .ppt, .psd, .rtf, .svg, .tar, .tbz2, .tgz, .tif, .xls, .xlsx, .zip
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise DeltaWalker over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.DeltaWalker);
+```
+
 #### Notes:
 
  * [Command line usage](https://www.deltawalker.com/integrate/command-line)
@@ -255,6 +271,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Diffinity`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Diffinity over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Diffinity);
+```
+
 #### Windows settings:
 
   * Example target on left arguments:
@@ -281,6 +305,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_ExamDiff`
   * Supported binaries: .bin, .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise ExamDiff over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.ExamDiff);
+```
+
 #### Notes:
 
  * [Command line reference](https://www.prestosoft.com/ps.asp?page=htmlhelp/edp/command_line_options)
@@ -313,6 +345,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Guiffy`
   * Supported binaries: .bmp, .gif, .jpeg, .jpg, .png, .svg, .wbmp
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Guiffy over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Guiffy);
+```
+
 #### Notes:
 
  * [Command line reference](https://www.guiffy.com/help/GuiffyHelp/GuiffyCmd.html)
@@ -360,6 +400,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Kaleidoscope`
   * Supported binaries: .bin, .bmp, .gif, .ico, .jpeg, .jpg, .png, .svg, .tif, .tiff
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Kaleidoscope over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Kaleidoscope);
+```
+
 #### OSX settings:
 
   * Example target on left arguments:
@@ -383,6 +431,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_KDiff3`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise KDiff3 over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.KDiff3);
+```
+
 #### Notes:
 
  * `--cs CreateBakFiles=0` to not save a `.orig` file when merging
@@ -430,6 +486,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Neovim`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Neovim over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Neovim);
+```
+
 #### Notes:
 
  * https://neovim.io/doc/user/diff.html
@@ -484,6 +548,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_P4Merge`
   * Supported binaries: .bmp, .gif, .jpeg, .jpg, .pbm, .pgm, .png, .ppm, .svg, .tif, .tiff, .xbm, .xpm
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise P4Merge over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.P4Merge);
+```
+
 #### Windows settings:
 
   * Example target on left arguments for text:
@@ -561,6 +633,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Rider`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Rider over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Rider);
+```
+
 #### Notes:
 
  * https://www.jetbrains.com/help/rider/Command_Line_Differences_Viewer.html
@@ -621,6 +701,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_TkDiff`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise TkDiff over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.TkDiff);
+```
+
 #### OSX settings:
 
   * Example target on left arguments:
@@ -645,6 +733,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_TortoiseGitIDiff`
   * Supported binaries: .bmp, .gif, .ico, .jpeg, .jpg, .png, .tif, .tiff
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise TortoiseGitIDiff over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.TortoiseGitIDiff);
+```
+
 #### Windows settings:
 
   * Example target on left arguments:
@@ -671,6 +767,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_TortoiseGitMerge`
   * Supported binaries: .bin, .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise TortoiseGitMerge over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.TortoiseGitMerge);
+```
+
 #### Windows settings:
 
   * Example target on left arguments:
@@ -697,6 +801,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_TortoiseIDiff`
   * Supported binaries: .bmp, .gif, .ico, .jpeg, .jpg, .png, .tif, .tiff
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise TortoiseIDiff over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.TortoiseIDiff);
+```
+
 #### Windows settings:
 
   * Example target on left arguments:
@@ -723,6 +835,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_TortoiseMerge`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise TortoiseMerge over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.TortoiseMerge);
+```
+
 #### Windows settings:
 
   * Example target on left arguments:
@@ -749,6 +869,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Vim`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Vim over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Vim);
+```
+
 #### Notes:
 
  * [Options](http://vimdoc.sourceforge.net/htmldoc/options.html)
@@ -797,6 +925,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_WinMerge`
   * Supported binaries: .bin, .bmp, .bw, .cut, .dds, .exr, .g3, .gif, .hdp, .hdr, .ico, .iff, .j2c, .j2k, .jif, .jng, .jp2, .jpe, .jpeg, .jpg, .jxr, .koa, .lbm, .mng, .pbm, .pcd, .pct, .pcx, .pfm, .pgm, .pic, .pict, .png, .ppm, .psd, .ras, .rgb, .rgba, .sgi, .svg, .targa, .tga, .tif, .tiff, .wap, .wbm, .wbmp, .wdp, .webp, .xbm, .xpm
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise WinMerge over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.WinMerge);
+```
+
 #### Notes:
 
  * [Command line reference](https://manual.winmerge.org/en/Command_line.html).
@@ -836,6 +972,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_AraxisMerge`
   * Supported binaries: .bmp, .dib, .emf, .gif, .j2c, .j2k, .jif, .jp2, .jpc, .jpeg, .jpg, .jpx, .pbm, .pcx, .pgm, .png, .ppm, .ras, .svg, .tga, .tif, .tiff, .wmf
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise AraxisMerge over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.AraxisMerge);
+```
+
 #### Notes:
 
  * [Supported image files](https://www.araxis.com/merge/documentation-windows/comparing-image-files.en)
@@ -883,6 +1027,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Cursor`
   * Supported binaries: .bin, .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Cursor over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Cursor);
+```
+
 #### Notes:
 
  * [Command line reference](https://cursor.com/docs/configuration/shell)
@@ -940,6 +1092,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_Meld`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise Meld over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.Meld);
+```
+
 #### Notes:
 
  * While Meld is not MDI, it is treated as MDI since it uses a single shared process to managing multiple windows. As such it is not possible to close a Meld merge process for a specific diff. [Vote for this feature](https://gitlab.gnome.org/GNOME/meld/-/issues/584)
@@ -998,6 +1158,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_SublimeMerge`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise SublimeMerge over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.SublimeMerge);
+```
+
 #### Notes:
 
  * While SublimeMerge is not MDI, it is treated as MDI since it uses a single shared process to managing multiple windows. As such it is not possible to close a Sublime merge process for a specific diff. [Vote for this feature](https://github.com/sublimehq/sublime_merge/issues/1168)
@@ -1055,6 +1223,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_VisualStudio`
   * Supported binaries: .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise VisualStudio over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.VisualStudio);
+```
+
 #### Windows settings:
 
   * Example target on left arguments:
@@ -1090,6 +1266,14 @@ Non-MDI tools are preferred since it allows [DiffEngineTray](tray.md) to track a
   * Environment variable for custom install location: `DiffEngine_VisualStudioCode`
   * Supported binaries: .bin, .svg
 
+#### Tool order:
+
+Use [tool order](diff-tool.order.md) to prioritise VisualStudioCode over other tools.
+
+```
+DiffTools.UseOrder(DiffTool.VisualStudioCode);
+```
+
 #### Notes:
 
  * [Command line reference](https://code.visualstudio.com/docs/editor/command-line)

src/DiffEngine.Tests/DefinitionsTest.cs

@@ -133,6 +133,17 @@ static void AddTool(StreamWriter writer, Definition tool)
             writer.WriteLine($"  * Supported binaries: {string.Join(", ", tool.BinaryExtensions.OrderBy(_ => _))}");
         }
 
+        writer.WriteLine(
+            $"""
+
+             #### Tool order:
+
+             Use [tool order](diff-tool.order.md) to prioritise {tool.Tool} over other tools.
+
+             ```
+             DiffTools.UseOrder(DiffTool.{tool.Tool});
+             ```
+             """);
         if (tool.Notes != null)
         {
             writer.WriteLine(