Minor doc fixes by markcmiller86 · Pull Request #20860 · visit-dav/visit

markcmiller86 · 2026-03-11T22:43:42Z

Description

Uses Codex to fix various minor issues in docs. Each bullet below cooresponds to one of the commits here. I did examine very carefully spelling and mechanics changes and was fine with what Codex did. I spent less time evaluating the style changes Codex did. So, @biagas and @JustinPrivitera, I am fine if you choose to focus only on the style commits. Go to the Commits tab and then select the style commits page and you can add review comments specific to those changes.

Noe that the change from "plugin" to "plug-in" caused issues for example python code because plug-in in Python means the difference after subtractin in from plug variables and in is a python keyword. So, it took me a bit to track down some problems this was causing in CLI doc regen.

Spelling
Syntax, grammar, mechanics, punctuation
Consistent use of style (e.g. "matadata" vs "meta data", "plugin" vs "plug-in", etc.)

Type of change

~[ ] Bug fix~~
~[ ] New feature~~
Documentation update~~
~[ ] Other~~

How Has This Been Tested?

I examined all spelling changes closely and most of the syntax, mechanics changes but not all. The docs may fail a regen here due to possible diffs in Section underlining lengths. Will fix after I see what we get.

Reminders:

Please follow the style guidelines of this project.
Please perform a self-review of your code before submitting a PR and asking others to review it.
Please assign reviewers (see VisIt's PR procedures for more information).

Checklist:

~~[ ] I have commented my code where applicable.~~
~~[ ] I have updated the release notes.~~
I have made corresponding changes to the documentation.~~
~~[ ] I have added debugging support to my changes.~~
~~[ ] I have added tests that prove my fix is effective or that my feature works.~~
~~[ ] I have confirmed new and existing unit tests pass locally with my changes.~~
~~[ ] I have added new baselines for any new tests to the repo.~~
I have NOT made any changes to protocol or public interfaces in an RC branch.~~

…isit-dav/visit into doc-mcm86-11mar26-codex-spelling-fixes

cyrush

This is a nice pass to fix spelling and consistency issues.

I found some cases where file system paths where change from plugin to plug-in, which I don't think we want to change. I added those cases I found as suggestions that can be committed via this PR.

src/doc/dev_manual/OpenGL.rst

src/doc/dev_manual/test_suite.rst

cyrush · 2026-03-16T15:46:04Z

src/doc/python_scripting/functions.rst

    A dictionary containing a key/value mapping to set options needed by the
    database exporter.  The default values can be obtained in the appropriate
-    format using GetExportOptions('plugin').
+    format using GetExportOptions('plug-in').


I think this change is ok b/c it is notional?

If we are refererencing plugins in VisIt, I think we should consistently use plugin and not plug-in', as the latter has never been used and is not used within our code either.

Ok, I reverted this too. I also found a couple of other places in docs that "plugins" is used as a python dict key and so "plug-ins" won't do there either. Fixed now.

If we are refererencing plugins in VisIt, I think we should consistently use plugin and not plug-in', as the latter has never been used and is not used within our code either.

@biagas, I wasn't seeing this before...I understand your remark is targetted specifically at documentation about the python CLI or examples of CLI. But, I wonder now...should our prose in the main docs just use the un-hyphenated version too? Hmmm...I am wondering what that means for other terms that were adjusted for stylistic reasons here now too.

I just refreshed and am still seeing a lot of plug-in. Were you intending to revert it everywhere?

Well, no. Just where it is programmatically relevant in python CLI code examples.

Why is plug-in better than plugin? Should we also adjust all our comments (which is prose) in our code base to change use of plugin?

Well, Google's style guide uses "plugin". Microsoft uses "plug-in". So does Chicago manual of style. I think I am fine with either. But, not being an English major, I chose to trust what the AI believes is proper style.

But, more importantly, I think what we decide for one term like plugin shoud maybe then applied to all similar terms such as metadata, timestep, thirdparty, high-level, problem-sized, zone-centered? I worry it can get away from us quickly. That said, current docs are not consistent in usage of several of these terms.

I vote we use plugin universally if it means making less changes than switching to plug-in universally. There is nothing wrong with plugin and we use it extensively, both programmatically and in our documentation.

I am going to do another commit that deals with hyphenations. Here is a proposed accepted style list for common hyphenations...

plugin

metadata

timestep

timestamp

datatype

dataset

filesystem

workload

workflow

multidimensional

nonlinear

precompute

reopen, restart, rebuild, rewrite, redo

command-line

run-time

time-state

high-level

low-level

third-party

problem-sized

zone-centered, node-centered, edge-centered, face-centered, vertex-centered, point-centered, cell-centered

staggered-grid

block-structured

patch-based

multi-resolution, multi-block, multi-domain

Co-authored-by: Cyrus Harrison <cyrush@llnl.gov>

…isit-dav/visit into doc-mcm86-11mar26-codex-spelling-fixes

JustinPrivitera

We need to be careful about codex making changes that we don't want.

JustinPrivitera · 2026-03-16T22:26:03Z

src/doc/building_visit/BuildingOnMac/Setup.rst

           },
           {
-             "path": "VisIt.dmg/VisIt.app/Contents/MacOS/VisIt",
+             "path": "VisIt.dmg/VisIt.app/Contents/macOS/VisIt",


did this get caught by a previous review? Do we want to change the path here?

I missed this, -- lowercase start here is incorrect

So, on disk, Apple indeed uses MacOS in the pathnames. So, this needs to be fixed.

JustinPrivitera · 2026-03-16T22:27:59Z

src/doc/building_visit/Building_Directly_With_CMake.rst

+macOS only
 """""""""""


the ~~~ line needs one less ~ now that you removed the space.

JustinPrivitera · 2026-03-16T22:29:55Z

src/doc/data_into_visit/CreatingDatabasePlugin.rst

-Finally, ``xml2cmake`` created *CMakeLists.txt* file that CMake can use to generate a build system for your plug-in.
-If you run ``cmake .`` at the command prompt and you are on a UNIX system such as Linux or MacOS X, CMake will generate a Makefile for your plug-in.
+Finally, ``xml2cmake`` created a *CMakeLists.txt* file that CMake can use to generate a build system for your plug-in.
+If you run ``cmake .`` at the command prompt and you are on a UNIX system such as Linux or macOS, CMake will generate a Makefile for your plug-in.


Why make the change from MacOS X to macOS? Are we losing information here? Why change from Mac OS to macOS? Linux, Windows, and UNIX all start with capital letters. Why should macOS not be capitalized?

I think we should change to macOS, as that's Apple's name for OS.

However there are a few cases were changes keep the X (macOS X), which we don't want.
So we need to be careful.

@cyrush convinced me that macOS is the right way. So please ignore my comments about changing it for stylistic reasons. But any time we are changing a path or a URL we need to be careful. There are also many cases where we include the X still after codex made changes, like Cyrus pointed out.

JustinPrivitera · 2026-03-16T22:30:17Z

src/doc/data_into_visit/CreatingDatabasePlugin.rst

 If you type: ``find ~/.visit -name "*.so"`` into your command window, you will be able to locate the *libE*, *libI*, and *libM* files that make up your compiled plug-in (see :numref:`Figure %s <pluginbuildresults>`).

-If you develop for MacOS X, you should substitute ``*.dylib`` for ``*.so`` in the previous command because shared libraries on MacOS X have a *.dylib* file extension instead of a *.so* file extension.
+If you develop for macOS X, you should substitute ``*.dylib`` for ``*.so`` in the previous command because shared libraries on macOS X have a *.dylib* file extension instead of a *.so* file extension.


See my comment above.

Need to remove the X's

JustinPrivitera · 2026-03-16T22:31:00Z

src/doc/data_into_visit/CreatingDatabasePlugin.rst


 It is recommended that while you develop your plug-ins, you only install them in your *~/.visit*  directory so other VisIt_ users will not be affected.
-However, if you develop your plug-in on MacOS X, you will have to make sure that your plug-ins are installed publicly so that they can be loaded at runtime.
+However, if you develop your plug-in on macOS X, you will have to make sure that your plug-ins are installed publicly so that they can be loaded at runtime.


need to remove the X

src/doc/tutorials/RemoteUsage.rst

JustinPrivitera · 2026-03-16T22:47:44Z

src/doc/using_visit/Preferences/File_Locations.rst

-  * ``VUSER_HOME/<visit-version>/<visit-arch>/plugins/operators/``
-  * ``VUSER_HOME/<visit-version>/<visit-arch>/plugins/databases/``
-  * ``VUSER_HOME/<visit-version>/<visit-arch>/plugins/plots/``
+  * ``VUSER_HOME/<visit-version>/<visit-arch>/plug-ins/operators/``
+  * ``VUSER_HOME/<visit-version>/<visit-arch>/plug-ins/databases/``
+  * ``VUSER_HOME/<visit-version>/<visit-arch>/plug-ins/plots/``


this change needs to be reverted.

src/doc/using_visit/Preferences/How_to_Save_Settings.rst

JustinPrivitera · 2026-03-16T22:51:59Z

src/doc/using_visit/SavingPrinting/Saving_movies.rst

+Choosing email notification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~


remove a ~ from the line below

src/visitpy/common/MethodDoc.C

cyrush · 2026-03-16T22:57:53Z

src/doc/data_into_visit/CreatingDatabasePlugin.rst

 If you type: ``find ~/.visit -name "*.so"`` into your command window, you will be able to locate the *libE*, *libI*, and *libM* files that make up your compiled plug-in (see :numref:`Figure %s <pluginbuildresults>`).

-If you develop for MacOS X, you should substitute ``*.dylib`` for ``*.so`` in the previous command because shared libraries on MacOS X have a *.dylib* file extension instead of a *.so* file extension.
+If you develop for macOS X, you should substitute ``*.dylib`` for ``*.so`` in the previous command because shared libraries on macOS X have a *.dylib* file extension instead of a *.so* file extension.


If we change to macOS, we need to drop the X

My understanding is OSX is outdated. Its called macOS now.

…isit-dav/visit into doc-mcm86-11mar26-codex-spelling-fixes

markcmiller86 added 10 commits March 11, 2026 14:26

fix spelling

b0ba9b5

fix syntax, punctuation, capitalization, mechanics

e3cd0d5

fix consistency in style

ff0bfa9

regen

242d73c

fix "plug-in" when used in py code

9f07943

fix sync

1962e39

Merge branch 'develop' into doc-mcm86-11mar26-codex-spelling-fixes

4c2d551

fix RTD build warnings

4f05ceb

Merge branch 'doc-mcm86-11mar26-codex-spelling-fixes' of github.com:v…

e5ea0cb

…isit-dav/visit into doc-mcm86-11mar26-codex-spelling-fixes

fix duplicate line

1479809

cyrush approved these changes Mar 16, 2026

View reviewed changes

cyrush requested changes Mar 16, 2026

View reviewed changes

cyrush added this to the 3.5.0 milestone Mar 16, 2026

markcmiller86 and others added 7 commits March 16, 2026 13:57

Update src/doc/dev_manual/OpenGL.rst

e0f5300

Co-authored-by: Cyrus Harrison <cyrush@llnl.gov>

Update src/doc/dev_manual/OpenGL.rst

200a88e

Co-authored-by: Cyrus Harrison <cyrush@llnl.gov>

Update src/doc/dev_manual/test_suite.rst

5e826e8

Co-authored-by: Cyrus Harrison <cyrush@llnl.gov>

fix programmatic use of "plugins" key

0f35748

Merge branch 'doc-mcm86-11mar26-codex-spelling-fixes' of github.com:v…

9bf220c

…isit-dav/visit into doc-mcm86-11mar26-codex-spelling-fixes

Merge branch 'develop' into doc-mcm86-11mar26-codex-spelling-fixes

bd56812

Merge branch 'develop' into doc-mcm86-11mar26-codex-spelling-fixes

911e01f

JustinPrivitera requested changes Mar 16, 2026

View reviewed changes

cyrush reviewed Mar 16, 2026

View reviewed changes

markcmiller86 added 5 commits March 16, 2026 19:01

rm 2to3 in workflow

d919766

repl 2to3 ref w/ python -m

e29c630

address @JustinPrivitera review comments

0781906

Merge branch 'doc-mcm86-11mar26-codex-spelling-fixes' of github.com:v…

ee7fef6

…isit-dav/visit into doc-mcm86-11mar26-codex-spelling-fixes

fix py vers

53fc90c

Conversation

markcmiller86 commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Reminders:

Checklist:

Uh oh!

cyrush left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markcmiller86 Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JustinPrivitera left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

markcmiller86 commented Mar 11, 2026 •

edited

Loading

markcmiller86 Mar 16, 2026 •

edited

Loading