Skip to content

Commit d8e95f9

Browse files
committed
word wrap docs at 120 columns.
1 parent c6f1406 commit d8e95f9

22 files changed

+347
-297
lines changed

.vscode/settings.json

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"editor.wordWrapColumn": 120,
3+
"rewrap.wrappingColumn": 120
4+
}

docs/dev/design.md

+50-58
Original file line numberDiff line numberDiff line change
@@ -2,99 +2,91 @@
22

33
By [Chris Lovett](http://lovettsoftware.com/), Microsoft
44

5-
In the GitHub repo, you'll find the core `XmlNotepad` DLL project, an `Application` project that
6-
builds XmlNotepad.exe, and some setup projects like `XmlNotepadSetup` which builds the .msi
7-
installer, and the `UnitTests` project for testing XML Notepad.
5+
In the GitHub repo, you'll find the core `XmlNotepad` DLL project, an `Application` project that builds XmlNotepad.exe,
6+
and some setup projects like `XmlNotepadSetup` which builds the .msi installer, and the `UnitTests` project for testing
7+
XML Notepad.
88

9-
The following DGML diagram shows the relationships between the main UI classes. The main form
10-
contains all the UI elements from the TaskList to the main XmlTreeView with Resizers in between;
11-
it's the launching point for the dialogs such as FormSearch, FormSchemas, FormOption, and FormAbout.
9+
The following DGML diagram shows the relationships between the main UI classes. The main form contains all the UI
10+
elements from the TaskList to the main XmlTreeView with Resizers in between; it's the launching point for the dialogs
11+
such as FormSearch, FormSchemas, FormOption, and FormAbout.
1212

1313
![ui](../assets/images/ui.png)
1414

15-
The main tab control contains the XmlTreeView and the XsltViewer for showing XSL output. The
16-
XmlTreeView contains a TreeView on the left and a NodeTextView on the right and coordinates
17-
scrolling between these two views. Both the TreeView and NodeTextView provide the same IntelliSense
18-
editing functionality using a TextEditorOverlay component. The XmlTreeView implements IFindTarget,
19-
which is used by the Find dialog (FormSearch) to implement find/replace functionality.
15+
The main tab control contains the XmlTreeView and the XsltViewer for showing XSL output. The XmlTreeView contains a
16+
TreeView on the left and a NodeTextView on the right and coordinates scrolling between these two views. Both the
17+
TreeView and NodeTextView provide the same IntelliSense editing functionality using a TextEditorOverlay component. The
18+
XmlTreeView implements IFindTarget, which is used by the Find dialog (FormSearch) to implement find/replace
19+
functionality.
2020

2121
![find](../assets/images/ifindtarget.png)
2222

2323
The Find dialog supports full text, regex, or XPath expressions and can filter by names or values.
2424

2525
## Model
2626

27-
The core data model behind the UI is `System.Xml.XmlDocument` and its `XmlNode` objects. These
28-
nodes are wrapped by `TreeNode` UI objects. To facilitate support for the XML Include spec, there is a
29-
custom reader that processes XML Includes, and there is also a custom DomLoader that keeps track of
30-
line information for error messages.
27+
The core data model behind the UI is `System.Xml.XmlDocument` and its `XmlNode` objects. These nodes are wrapped by
28+
`TreeNode` UI objects. To facilitate support for the XML Include spec, there is a custom reader that processes XML
29+
Includes, and there is also a custom DomLoader that keeps track of line information for error messages.
3130

3231
![model](../assets/images/model.png)
3332

3433
## Validation, IntelliSense, and Custom Editors
3534

36-
The biggest new feature is IntelliSense, which is driven by XML Schema information provided via the
37-
SchemaCache. For example, if your element or attribute is defined by an XSD simpleType and this
38-
simpleType contains a list of enumeration facets, then you will get a drop-down like this:
35+
The biggest new feature is IntelliSense, which is driven by XML Schema information provided via the SchemaCache. For
36+
example, if your element or attribute is defined by an XSD simpleType and this simpleType contains a list of enumeration
37+
facets, then you will get a drop-down like this:
3938

4039
![intellisense](../assets/images/intellisense.png)
4140

42-
The way this works is that the Checker runs after each edit operation to validate the document and
43-
report errors in the TaskList. This process also puts `System.Xml.Schema.XmlSchemaType` information
44-
on each element and attribute in the XmlDocument; then, when editing the value of that node, the
45-
TextEditorOverlay uses the `XmlIntelliSenseProvider` to get back a list of possible values. In the
46-
above example, it returns the values from the simpleType enumeration facets. For element name
47-
IntelliSense in the tree view, the `XmlIntelliSenseProvider` invokes the Checker again, captures
48-
GetExpectedParticles and GetExpectedAttributes on the `System.Xml.Schema.XmlSchemaValidator`, and
49-
uses that to provide IntelliSense.
41+
The way this works is that the Checker runs after each edit operation to validate the document and report errors in the
42+
TaskList. This process also puts `System.Xml.Schema.XmlSchemaType` information on each element and attribute in the
43+
XmlDocument; then, when editing the value of that node, the TextEditorOverlay uses the `XmlIntelliSenseProvider` to get
44+
back a list of possible values. In the above example, it returns the values from the simpleType enumeration facets. For
45+
element name IntelliSense in the tree view, the `XmlIntelliSenseProvider` invokes the Checker again, captures
46+
GetExpectedParticles and GetExpectedAttributes on the `System.Xml.Schema.XmlSchemaValidator`, and uses that to provide
47+
IntelliSense.
5048

5149
![plugins](../assets/images/plugins.png)
5250

53-
The `TextEditorOverlay` also supports custom editors like the `DateTimeEditor` or the `UriBuilder`
54-
or `ColorBuilder`. There are two types of custom editors: IXmlEditors, which are inline editors that
55-
replace the default TextBox, and IXmlBuilders, which are popup dialogs like the OpenFileDialog or
56-
ColorDialog. The type of editor is derived from the schema type information — "xs:date", "xs:time",
57-
"xs:datetime" results in the DateTimeEditor, and "xs:anyURI" results in the UriBuilder. You can also
58-
annotate the schema with a custom "vs:builder" attribute in the
59-
`http://schemas.microsoft.com/Visual-Studio-IntelliSense` namespace. See the Help content for more
60-
information.
51+
The `TextEditorOverlay` also supports custom editors like the `DateTimeEditor` or the `UriBuilder` or `ColorBuilder`.
52+
There are two types of custom editors: IXmlEditors, which are inline editors that replace the default TextBox, and
53+
IXmlBuilders, which are popup dialogs like the OpenFileDialog or ColorDialog. The type of editor is derived from the
54+
schema type information — "xs:date", "xs:time", "xs:datetime" results in the DateTimeEditor, and "xs:anyURI" results in
55+
the UriBuilder. You can also annotate the schema with a custom "vs:builder" attribute in the
56+
`http://schemas.microsoft.com/Visual-Studio-IntelliSense` namespace. See the Help content for more information.
6157

6258
## Infinite Undo/Redo
6359

64-
To implement undo/redo, XML Notepad follows a common design pattern of Command objects with Undo and
65-
Redo methods. Commands operate on both a `TreeNode` and an `XmlNode` because some commands like
66-
`InsertNode` don't have an `XmlNode` yet until they are performed, but the command needs to know
67-
where in the tree this new node will be inserted and during `Undo` where it should be removed. The
68-
UndoManager collects these in a list. Then the state of the UndoManager controls the
69-
enabled/disabled state of the Undo/Redo MenuItems. When the user selects the Undo menu item, the
70-
Undo method is called on the active command, and that command is pushed onto the Redo stack.
60+
To implement undo/redo, XML Notepad follows a common design pattern of Command objects with Undo and Redo methods.
61+
Commands operate on both a `TreeNode` and an `XmlNode` because some commands like `InsertNode` don't have an `XmlNode`
62+
yet until they are performed, but the command needs to know where in the tree this new node will be inserted and during
63+
`Undo` where it should be removed. The UndoManager collects these in a list. Then the state of the UndoManager controls
64+
the enabled/disabled state of the Undo/Redo MenuItems. When the user selects the Undo menu item, the Undo method is
65+
called on the active command, and that command is pushed onto the Redo stack.
7166

7267
![undo.png](../assets/images/undo.png)
7368

74-
Some operations in the editor cause many edits in the tree, including the replace-all operation and
75-
editing the value of a namespace attribute. (When you change the value of a namespace attribute,
76-
every XmlNode bound to that namespace needs to be reconstructed with a new namespace URI, which can
77-
obviously affect a lot of nodes in the tree!) So, to make these operations one atomic undo
78-
operation, there is a `CompoundCommand` object that contains a list of smaller edit commands, and
79-
this CompoundCommand is put into the `UndoManager`.
69+
Some operations in the editor cause many edits in the tree, including the replace-all operation and editing the value of
70+
a namespace attribute. (When you change the value of a namespace attribute, every XmlNode bound to that namespace needs
71+
to be reconstructed with a new namespace URI, which can obviously affect a lot of nodes in the tree!) So, to make these
72+
operations one atomic undo operation, there is a `CompoundCommand` object that contains a list of smaller edit commands,
73+
and this CompoundCommand is put into the `UndoManager`.
8074

81-
Other simpler command objects include the following, which all operate on XmlTreeNode and XmlNode
82-
objects:
75+
Other simpler command objects include the following, which all operate on XmlTreeNode and XmlNode objects:
8376

8477
![commands.png](../assets/images/commands.png)
8578

86-
The PasteCommand is special because it takes random XML text off the clipboard and parses it in
87-
the context of the currently selected element in the tree, inheriting the namespaces in scope. The
88-
helper class TreeData uses the special XmlTextReader constructor that takes an XmlParserContext as
89-
input.
79+
The PasteCommand is special because it takes random XML text off the clipboard and parses it in the context of the
80+
currently selected element in the tree, inheriting the namespaces in scope. The helper class TreeData uses the special
81+
XmlTextReader constructor that takes an XmlParserContext as input.
9082

9183
### Accessibility
9284

93-
In order to make testing possible using `System.Windows.Automation`, there are some custom
94-
`AccessibleObject` implementations inside the TreeView and NodeTextView. See `AccessibleNode` and
95-
`AccessibleNodeTextViewNode`. These accessibility classes should also make Windows accessibility
96-
features work better with those custom views.
85+
In order to make testing possible using `System.Windows.Automation`, there are some custom `AccessibleObject`
86+
implementations inside the TreeView and NodeTextView. See `AccessibleNode` and `AccessibleNodeTextViewNode`. These
87+
accessibility classes should also make Windows accessibility features work better with those custom views.
9788

9889
### Missing Documentation?
9990

100-
If you want more detailed documentation on some aspect of XML Notepad, please create a new [GitHub issue](https://github.com/microsoft/XmlNotepad/issues).
91+
If you want more detailed documentation on some aspect of XML Notepad, please create a new [GitHub
92+
issue](https://github.com/microsoft/XmlNotepad/issues).

docs/dev/index.md

+36-38
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ XML Notepad targets [.NET Framework version 4.8](https://dotnet.microsoft.com/en
66

77
### Coding Guidelines
88

9-
XmlNotepad follows the standard [C# Coding Guidelines](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) with
10-
the default C# formatting settings that ship with VS 2022.
9+
XmlNotepad follows the standard [C# Coding
10+
Guidelines](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) with the
11+
default C# formatting settings that ship with VS 2022.
1112

1213
The following additional conventions are also followed:
1314

@@ -19,7 +20,8 @@ The following additional conventions are also followed:
1920
1. Constants are PascalCased even if they are private to a class.
2021
1. Try and collect all private fields at the top of the class.
2122
1. Public fields are PascalCased like public properties and methods.
22-
1. Generally one class per file, unless there is a super natural family of classes, like Commands.cs, that would cause an unnecessary explosion in number of files.
23+
1. Generally one class per file, unless there is a super natural family of classes, like Commands.cs, that would cause
24+
an unnecessary explosion in number of files.
2325
1. Nice to have blank line between methods.
2426
1. Use "Remove and Sort Usings" command in VS.
2527

@@ -63,78 +65,74 @@ After building the app:
6365
6466
- Right click the `UnitTests` project and select `Run tests`.
6567
66-
This is a GUI test, so do not move your mouse or type on your keyboard or let your
67-
screen lock until this test is completed. Total test run time is about 12 minutes.
68+
This is a GUI test, so do not move your mouse or type on your keyboard or let your screen lock until this test is
69+
completed. Total test run time is about 12 minutes.
6870
69-
The tests all pass on Windows 10, but currently some tests fail on Windows 11, there seems to be
70-
some breaking changes in the Windows Automation layer that XML notepad tests are using. This is
71-
being investigated.
71+
The tests all pass on Windows 10, but currently some tests fail on Windows 11, there seems to be some breaking changes
72+
in the Windows Automation layer that XML notepad tests are using. This is being investigated.
7273
73-
Note: [bug 10244](https://github.com/dotnet/winforms/issues/10244) is still open
74-
in in .net 4.8 System.Windows.Automation of menu items that blocks the tests, so
75-
checkout the branch `clovett/net472` to run the unit tests.
74+
Note: [bug 10244](https://github.com/dotnet/winforms/issues/10244) is still open in in .net 4.8
75+
System.Windows.Automation of menu items that blocks the tests, so checkout the branch `clovett/net472` to run the unit
76+
tests.
7677
7778
### UpdateVersions
7879
79-
The `UpdateVersions` project synchronizes the `Version.props` information
80-
across multiple places so you can edit the version number in `Version.props` and this tool will
81-
replicate that across the following:
80+
The `UpdateVersions` project synchronizes the `Version.props` information across multiple places so you can edit the
81+
version number in `Version.props` and this tool will replicate that across the following:
8282
8383
1. The `Version.cs` file which sets the assembly version for all projects in the solution.
8484
1. The WIX based setup file `Product.wxs`.
8585
2. The windows package manifest file `Package.appxmanifest`.
8686
3. The updates.xml file.
8787
4. The readme.htm file.
8888
89-
You will also have to restart Visual Studio so that the new versions are picked up by the ClickOnce
90-
deployment information in `Application.csproj`.
89+
You will also have to restart Visual Studio so that the new versions are picked up by the ClickOnce deployment
90+
information in `Application.csproj`.
9191
9292
### Publish the app and all setups
9393
9494
The `publish.cmd` script runs UpdateVersions, builds Release bits, builds the ClickOnce installer and the winget.msix
9595
installer from `XmlNotepadPackage`, and the standalone .msi installer from `XmlNotepadSetup`, it zips these files so
96-
they can be available on the Github Release page then it creates the new github release for the current version. It
97-
also signs the assemblies and installers using the signing certificate specified by the environment variable
98-
`MYKEYFILE`.
96+
they can be available on the Github Release page then it creates the new github release for the current version. It also
97+
signs the assemblies and installers using the signing certificate specified by the environment variable `MYKEYFILE`.
9998
10099
The ClickOnce installed is uploaded to
101100
[lovettsoftware](https://lovettsoftwarestorage.blob.core.windows.net/downloads/XmlNotepad/XmlNotepad.application) using
102-
the environment variable LOVETTSOFTWARE_STORAGE_CONNECTION_STRING. Click once is convenient because it provides
101+
the environment variable LOVETTSOFTWARE_STORAGE_CONNECTION_STRING. Click once is convenient because it provides
103102
auto-updating whenever a new version is published.
104103
105104
### Build the setup .msi installer
106105
107-
After building the `Release` configuration of `XmlNotepad.sln` load the `XmlNotepadSetup.sln`. This
108-
solution uses the [WIX Toolset](https://wixtoolset.org/) to build a standalone windows .msi
109-
installer. To build that setup you will need to install the WIX toolset then the [Wix Toolset Visual
110-
Studio 2022
106+
After building the `Release` configuration of `XmlNotepad.sln` load the `XmlNotepadSetup.sln`. This solution uses the
107+
[WIX Toolset](https://wixtoolset.org/) to build a standalone windows .msi installer. To build that setup you will need
108+
to install the WIX toolset then the [Wix Toolset Visual Studio 2022
111109
Extension](https://marketplace.visualstudio.com/items?itemName=WixToolset.WixToolsetVisualStudio2022Extension).
112110
113-
Then right click the `XmlNotepadSetup` project and select "build". This will produce an .msi installer in the
114-
XmlNotepadSetup\bin\release folder. There is also a `sign.cmd` script invoked by this build that will try and sign the
115-
resulting .msi using the certificate installed by the author. This step will only work for the author who owns the
111+
Then right click the `XmlNotepadSetup` project and select "build". This will produce an .msi installer in the
112+
XmlNotepadSetup\bin\release folder. There is also a `sign.cmd` script invoked by this build that will try and sign the
113+
resulting .msi using the certificate installed by the author. This step will only work for the author who owns the
116114
certificate.
117115
118116
This `msi` installer gives folks the option to install XML Notepad on machines that are isolated from the internet and
119117
there are quite a few customers who have requested this, which is why it exists.
120118
121119
### Build the winget setup package
122120
123-
The `winget` setup package is built by the `XmlNotepadPackage` project in the `XmlNotepadSetup.sln`
124-
solution. Right click this project in the Solution Explorer and select `Publish` and `Create App
125-
Packages`. Choose Sideloading, and the package files will be written to the
126-
XmlNotepadPackage\AppPackages folder. These can then be uploaded to the server hosting these
127-
packages and you can then update the manifest in
121+
The `winget` setup package is built by the `XmlNotepadPackage` project in the `XmlNotepadSetup.sln` solution. Right
122+
click this project in the Solution Explorer and select `Publish` and `Create App Packages`. Choose Sideloading, and the
123+
package files will be written to the XmlNotepadPackage\AppPackages folder. These can then be uploaded to the server
124+
hosting these packages and you can then update the manifest in
128125
[winget-pkgs](https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/Microsoft/XMLNotepad).
129126
130127
This package provides the `winget install xmlnotepad` setup option.
131128
132129
### Publishing the bits to Azure Blob Store
133130
134-
The `publish.cmd` script uses the [AzurePublishClickOnce](https://github.com/clovett/tools/tree/master/AzurePublishClickOnce) tool
135-
which uses the environment variable named `LOVETTSOFTWARE_STORAGE_CONNECTION_STRING` to access the Azure storage account
136-
where it uploads the new clickonce installer, and removes the older versions so that the storage account does not
137-
keep growing and growing.
131+
The `publish.cmd` script uses the
132+
[AzurePublishClickOnce](https://github.com/clovett/tools/tree/master/AzurePublishClickOnce) tool which uses the
133+
environment variable named `LOVETTSOFTWARE_STORAGE_CONNECTION_STRING` to access the Azure storage account where it
134+
uploads the new clickonce installer, and removes the older versions so that the storage account does not keep growing
135+
and growing.
138136
139137
### Design
140138
@@ -143,5 +141,5 @@ See [XML Notepad Design ](design.md) for more detailed information about how thi
143141
### Issues
144142
145143
Feedback and suggestions are welcome, just use the [GitHub issues
146-
list](https://github.com/microsoft/XmlNotepad/issues). Pull requests are also welcome, in fact, a number of good pull
147-
requests have already been merged. Thanks to all who are helping to make XML notepad a great tool!
144+
list](https://github.com/microsoft/XmlNotepad/issues). Pull requests are also welcome, in fact, a number of good pull
145+
requests have already been merged. Thanks to all who are helping to make XML notepad a great tool!

0 commit comments

Comments
 (0)