wrote major-bugs list; misc. documentation improvements/tweaks

BUGS.md

@@ -1,2 +1,101 @@
+<!--
+  This file is part of Flood, an interactive flood-fill visualizer.
+
+  Copyright (C) 2021 Eliah Kagan <[email protected]>
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+  AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+  OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+  PERFORMANCE OF THIS SOFTWARE.
+-->
+
+# Known Major Bugs
+
+## Accessibility
+
+### Colors cannot be customized.
+
+Each kind of fill has a specific associated color, detailed in `doc/tips.html`
+and `doc/help.html`. Flood should let the user customize these easily.
+
+(The tips and full help are already customized with JavaScript; if the user
+sets any non-default colors, they could reflect those when being accessed as
+part of the program&rsquo;s UI, with the full help also mentioning the default
+color.)
+
+## UI/Features
+
+### The UI is confusing.
+
+People who&rsquo;ve tried out this program could not immediately tell how to
+use most of its functionality.
+
+This could be ameliorated by having a palette (accessible to the left of
+&ldquo;Show Tips&rdquo; and/or always visible) of tools that provide specific
+fills, and possibly also speed adjustments, as well as a default pointer tool
+that has the current modifier-key-driven behavior.
+
+### No videorecording.
+
+Flood should provide a facility to record (appropriately compressed) video
+files of fills, but I have not yet implemented that feature.
+
+## Documentation
+
+### The help and tips retrieve assets from the internet on each run.
+
+Flood&rsquo;s built-in help retrieves fonts and JavaScript libraries from the
+internet every time it runs, even though Flood is not itself a webapp. This was
+convenient for development, but I do not regard it to be a good software
+engineering practice for a desktop application.
+
+### The &ldquo;full&rdquo; help is incomplete.
+
 The full help file, `doc/help.html`, lacks some information that is present in
-`README.md`.
+`README.md`.
+
+### The technical explanation of `async` is confusing.
+
+The technical explanation of how Flood uses `async`/`await` (which is used by
+every fill except &ldquo;instant fill&rdquo;) is buried in a subsection of the
+section on &ldquo;recursive fill&rdquo;. It is also hard to follow.
+
+That material should be given its own top-level section and at least partly
+rewritten.
+
+## Stability
+
+### The tab-management code breaks encapsulation.
+
+As commented on `PanelSwitcher.TrySwitch`, the way program-driven switching
+between LINQPad output panels is implemented is by circumventing encapsulation
+on on the `OutputPanel` object (which runs in the query process, but is
+supplied by a library, being present as a separate assembly from the query
+assembly) and calling the `Activate` method.
+
+The comment gives details about why I don&rdquo;t think any currently available
+good means of doing this exist. But as long as I&rsquo;m doin that, Flood
+cannot have a stable release, as `OutputPanel.Activate` has the `internal`
+access modifier and it may be removed, or change behavior, in any future
+version of LINQPad.
+
+### The chart tooltip customization code breaks encapsulation.
+
+The charting control doesn&rsquo;t support changing tooltip timings, and
+I&rsquo;m circumventing encapsulation to work around that.
+
+Unlike the tab-management encapsulation violation, this isn&rsquo;t necessarily
+a huge big deal, since `System.Windows.Forms.DataVisualization` is no longer
+maintained and unlikely to get updates, since this is not core program
+functionality, and since I already degrade gracefully rather than crashing if
+the attempt to access the tooltip object fails. *Arguably*, Flood could even
+get a stable release without fixing this.
+
+But it would be better to just fork the library (it&rsquo;s free open source
+software) and add the functionality.

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020, 2021 Eliah Kagan <[email protected]>
+Copyright (C) 2020, 2021 Eliah Kagan <[email protected]>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.

NOTICES.md

@@ -1,7 +1,7 @@
 <!--
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.
@@ -26,10 +26,10 @@ reproduced here:
 <details>
 <summary>
 <strong>View 0BSD</strong>&nbsp;&nbsp;&nbsp;
-<em>&ldquo;Copyright 2020, 2021 Eliah Kagan &hellip;&rdquo;</em>
+<em>&ldquo;Copyright (C) 2020, 2021 Eliah Kagan &hellip;&rdquo;</em>
 </summary>
 
-> Copyright 2020, 2021 Eliah Kagan &lt;[email protected]&gt;
+> Copyright (C) 2020, 2021 Eliah Kagan &lt;[email protected]&gt;
 >
 > Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.

README.md

@@ -1,7 +1,7 @@
 <!--
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.
@@ -104,6 +104,9 @@ copyright/licensing information.
 
 I&rsquo;d like to thank:
 
+- David Vassallo, for testing the program and giving usability feedback.
+- Another user, for testing the program and giving usability feedback, and
+  finding a severe performance bug.
 - [Zanna Star](https://github.com/ZannaStar), for examining and giving advice
   about how to improve the presentation and styling for `help.html`. It was
   rather difficult to read before, and it is much better as a result of her

devmode.linq

@@ -2,5 +2,19 @@
 
 // devmode.linq - Chains to "developer mode" for Flood.
 // You probably want to open and run the "flood.linq" query directly instead.
+// This file is part of Flood, an interactive flood-fill visualizer.
+//
+// Copyright (C) 2021 Eliah Kagan <[email protected]>
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-#load ".\flood.linq"
+#load "./flood.linq"

doc/help.css

@@ -2,7 +2,7 @@
   help.css - Styling for the full-length help file.
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2020, 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2020, 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.
@@ -205,6 +205,14 @@ abbr {
   background-color: #ffc;
 }
 
+details>summary {
+  color: #707080;
+}
+
+details>summary>strong {
+  letter-spacing: .01em;
+}
+
 b {
   font-style: normal;
   font-weight: 600;

doc/help.html

@@ -4,7 +4,7 @@
   help.html - Full-length help file.
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2020, 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2020, 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.
@@ -862,9 +862,9 @@ <h2 id="dependencies">
         <details>
           <summary>
             <strong>View 0BSD</strong>&nbsp;&nbsp;&nbsp;
-            <em>&ldquo;Copyright 2020, 2021 Eliah Kagan &hellip;&rdquo;</em>
+            <em>&ldquo;Copyright (C) 2020, 2021 Eliah Kagan &hellip;&rdquo;</em>
           </summary>
-          <pre>Copyright 2020, 2021 Eliah Kagan <degeneracypressure@gmail.com>
+          <pre>Copyright (C) 2020, 2021 Eliah Kagan &lt;[email protected]&gt;
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.
@@ -898,7 +898,7 @@ <h3 id="platform">
                href="https://dotnet.microsoft.com/"
                title=".NET | Microsoft">.NET 5</a>
             on Windows. It uses
-            <a class="external"
+            <a class="external wide"
                href="https://github.com/dotnet/winforms"
                title="Windows Forms on GitHub">Windows Forms</a>,
             and to a much lesser extent
@@ -911,7 +911,7 @@ <h3 id="platform">
                title="LINQPad website">LINQPad</a>
             is a properietary freeware application written by Joseph Albahari.
             Flood&rsquo;s charting feature uses the version of
-            <a class="external"
+            <a class="external wide"
                href="https://github.com/dotnet/winforms-datavisualization"
                title="System.Windows.Forms.DataVisualization on GitHub">System.Windows.Forms.DataVisualization</a>
             that is included in LINQPad 6 (which I believe is

doc/help.js

@@ -1,7 +1,7 @@
 // help.js - JavaScript customization for the full help file.
 // This file is part of Flood, an interactive flood-fill visualizer.
 //
-// Copyright 2021 Eliah Kagan <[email protected]>
+// Copyright (C) 2021 Eliah Kagan <[email protected]>
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted.

doc/hyphenate.js

@@ -1,7 +1,7 @@
 // hyphenate.js - Dynamic hyphenation configuration.
 // This file is part of Flood, an interactive flood-fill visualizer.
 //
-// Copyright 2021 Eliah Kagan <[email protected]>
+// Copyright (C) 2021 Eliah Kagan <[email protected]>
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted.

doc/shared.css

@@ -2,7 +2,7 @@
   shared.css - Styles shared by tips and help.
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.

doc/tips.css

@@ -2,7 +2,7 @@
   tips.css - Styling for tips (brief help) drawer hosted in the application.
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2020, 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2020, 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.

doc/tips.html

@@ -4,7 +4,7 @@
   tips.html - Tips (brief help) drawer hosted in the application.
   This file is part of Flood, an interactive flood-fill visualizer.
 
-  Copyright 2020, 2021 Eliah Kagan <[email protected]>
+  Copyright (C) 2020, 2021 Eliah Kagan <[email protected]>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted.

doc/tips.js

@@ -1,7 +1,7 @@
 // tips.js - JavaScript customization for the tips drawer contents.
 // This file is part of Flood, an interactive flood-fill visualizer.
 //
-// Copyright 2021 Eliah Kagan <[email protected]>
+// Copyright (C) 2021 Eliah Kagan <[email protected]>
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted.

flood.linq

@@ -28,7 +28,7 @@
 // flood.linq - Entry point and main source code file.
 // This file is part of Flood, an interactive flood-fill visualizer.
 //
-// Copyright 2020, 2021 Eliah Kagan <[email protected]>
+// Copyright (C) 2020, 2021 Eliah Kagan <[email protected]>
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted.