Update site docs with improved Windows install info

Resolves #723
NASA-PDS · Oct 5, 2023 · 4154574 · 4154574
1 parent 97be0b7
commit 4154574
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 138 deletions.
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
@@ -1,37 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!--
-Copyright © 2019, California Institute of Technology ("Caltech").
-U.S. Government sponsorship acknowledged.
-
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-• Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimer.
-• Redistributions must reproduce the above copyright notice, this list of
-  conditions and the following disclaimer in the documentation and/or other
-  materials provided with the distribution.
-• Neither the name of Caltech nor its operating division, the Jet Propulsion
-  Laboratory, nor the names of its contributors may be used to endorse or
-  promote products derived from this software without specific prior written
-  permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
--->
-
-<document>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
   <properties>
     <title>About Validate Tool</title>
   </properties>
@@ -42,15 +12,13 @@ POSSIBILITY OF SUCH DAMAGE.
       </p>
 
       <ul>
-        <li><a href="#Tool_Overview">Tool Overview</a></li>
-        <li><a href="#Support">Support</a></li>
+        <li><a href="#tool-overview">Tool Overview</a></li>
+        <li><a href="#support">Support</a></li>
       </ul>
 
     </section>
-
-    <hr />
 
-    <section name="Tool Overview">
+    <section name="Tool Overview" id="tool-overview">
       <p>The Validate Tool currently supports the following features:
       </p>
 
@@ -108,14 +76,12 @@ POSSIBILITY OF SUCH DAMAGE.
       </ul>
     </section>
 
-    <hr />
-
-    <section name="Support">
+    <section name="Support" id="support">
       <p><b><i>Found a bug?</i></b> Or <b><i>want a new feature?</i></b> We would love your feedback and contributions. Here are some links to our public Github repository for source code and submitting issues:</p>
 
       <ul>
-        <li>Submit for a New Feature: <a href="https://github.com/NASA-PDS/validate/issues/new?template=feature_request.md">https://github.com/NASA-PDS/validate/issues/new?template=feature_request.md</a></li>
-        <li>Submit a Bug: <a href="https://github.com/NASA-PDS/validate/issues/new?template=bug_report.md">https://github.com/NASA-PDS/validate/issues/new?template=bug_report.md</a></li>
+        <li>Submit for a New Feature: <a href="https://github.com/NASA-PDS/validate/issues/new?template=feature_request.yml">https://github.com/NASA-PDS/validate/issues/new?template=feature_request.yml</a></li>
+        <li>Submit a Bug: <a href="https://github.com/NASA-PDS/validate/issues/new?template=bug_report.yml">https://github.com/NASA-PDS/validate/issues/new?template=bug_report.yml</a></li>
         <li>Source Code: <a href="https://github.com/NASA-PDS/validate/">https://github.com/NASA-PDS/validate</a></li>
       </ul>
 

diff --git a/src/site/xdoc/install/index.xml.vm b/src/site/xdoc/install/index.xml.vm
@@ -1,38 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<!--
-Copyright © 2019, California Institute of Technology ("Caltech").
-U.S. Government sponsorship acknowledged.
-
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-• Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimer.
-• Redistributions must reproduce the above copyright notice, this list of
-  conditions and the following disclaimer in the documentation and/or other
-  materials provided with the distribution.
-• Neither the name of Caltech nor its operating division, the Jet Propulsion
-  Laboratory, nor the names of its contributors may be used to endorse or
-  promote products derived from this software without specific prior written
-  permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
--->
-
-<document>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
   <properties>
     <title>Installation</title>
   </properties>
@@ -41,17 +10,17 @@ POSSIBILITY OF SUCH DAMAGE.
     <section name="Installation">
       <p>This document describes how to install the Validate Tool software contained in the <i>${project.artifactId}</i> package. The following topics can be found in this document:
       </p>
-
+      
       <ul>
-        <li><a href="#Getting_Started">Getting Started</a></li>
-        <li><a href="#Unpacking_the_Package">Unpacking the Package</a></li>
-        <li><a href="#System_Requirements">System Requirements</a></li>
-        <li><a href="#Configuring_the_Environment">Configuring the Environment</a></li>
-        <li><a href="../index.html#Support">Tool Support</a></li>
+        <li><a href="#quick-start">Quick Start</a></li>
+        <li><a href="#system-requirements">System Requirements</a></li>
+        <li><a href="#unpacking-the-package">Unpacking the Package</a></li>
+        <li><a href="#configuring-the-environment">Configuring the Environment</a></li>
       </ul>
+
     </section>
 
-    <section name="Quick Start">
+    <section name="Quick Start" id="quick-start">
       <p>Initially, Validate Tool works out of the box without needing to perform any additional function:</p>
 
       <ul>
@@ -66,7 +35,7 @@ POSSIBILITY OF SUCH DAMAGE.
       </ul>
     </section>
 
-    <section name="Unpacking the Package">
+    <section name="Unpacking the Package" id="unpacking-the-package">
       <p>Download the <i>${project.artifactId}</i> package from <a href="https://github.com/NASA-PDS/${project.artifactId}/releases/v${project.version}" target="_blank">Github</a>. The binary distribution is available in identical zip or tar/gzip packages. The installation directory may vary from environment to environment but in UNIX-based environments it is typical to install software packages in the <i>/usr/local</i> directory and in Windows-based environments it is typical to install software packages in the <i>C:\Program Files</i> directory. Unpack the selected binary distribution file with one of the following commands:
       </p>
 
@@ -110,7 +79,7 @@ or
       </ul>
     </section>
 
-    <section name="System Requirements">
+    <section name="System Requirements" id="system-requirements">
       <p>If you run into issues attempting to run Validate out of the box, this section details the system requirements for installing and operating the Validate Tool.
       </p>
 
@@ -128,14 +97,16 @@ OpenJDK Runtime Environment (build 15.0.1+9)
 OpenJDK 64-Bit Server VM (build 15.0.1+9, mixed mode, sharing)
         </source>
 
-        <p><i>NOTE: Validate requires 64-bit Java in order to enable Java Virtual Machine memory requirements. In version output above, note the line <b>Java HotSpot(TM) 64-Bit Server VM</b></i></p>
+        <p><i>NOTE: Validate requires 64-bit Java in order to enable Java Virtual Machine memory requirements. In version output above, note the line <b>Java HotSpot(TM) 64-Bit Server VM</b></i>.</p>
+
+        <p><i><b>For Windows Users:</b> The 32-bit JRE is the default on Windows, and even the the online installer for Windows on the <a href="https://www.java.com/en/download/manual.jsp">Java Download All Operating Systems page</a> only installs the 32-bit JRE. If you see an error like that described under <a href="/validate/operate/errors.html#invalid-heap">this common error</a>, you have the wrong JRE installed.</i></p>
 
         <p>If the either of these commands fail, it indicates Java is not installed or the version is not at least 1.9. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, the Java software can be downloaded from the <a href="https://openjdk.java.net/install/" target="_blank">Java Download</a> page.
         </p>
       </subsection>
     </section>
 
-    <section name="Configuring the Environment">
+    <section name="Configuring the Environment" id="configuring-the-environment">
       <p>If you want to run Validate from anywhere on your system, you will need to configure your PATH to know where Validate is located. This section describes how to setup the user environment on UNIX-based and Windows machines.
       </p>
 
@@ -179,14 +150,17 @@ OpenJDK 64-Bit Server VM (build 15.0.1+9, mixed mode, sharing)
         </p>
 
         <source>
-C:\&gt; set PATH = %PATH%;C:\Program Files\\${project.artifactId}-${project.version}\bin
+C:\&gt; set Path=%Path%;C:\Program Files\\${project.artifactId}-${project.version}\bin
         </source>
 
         <p>In addition, the batch scripts require that the <i>JAVA_HOME</i> environment variable be set to the appropriate location of the Java installation on the local machine. This may have already been set when Java was installed. However, if it hasn't, then run the following command to set the <i>JAVA_HOME</i> environment variable:
         </p>
 
         <source>
-C:\&gt; set JAVA_HOME = C:\path\to\java\home
+C:\&gt; set JAVA_HOME=C:\path\to\java\home
+
+# For example
+C:\&gt; set JAVA_HOME=C:\Program Files\Java\some-jre-version
         </source>
 
         <p>The system administrator for the local machine may need to be consulted for this location. The path specified should have a <i>bin</i> sub-directory that contains the <i>java</i> executable. This variable may also be defined within the scripts. Edit the scripts (files with the .bat extension) and change the line in the example above to represent the local Java installation. Additional methods for setting Windows environment variables can be found in the <a href="index-win.html">Windows System Properties</a> document.

diff --git a/src/site/xdoc/operate/errors.xml.vm b/src/site/xdoc/operate/errors.xml.vm
@@ -1,41 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<!--
-Copyright © 2019, California Institute of Technology ("Caltech").
-U.S. Government sponsorship acknowledged.
-
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-• Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimer.
-• Redistributions must reproduce the above copyright notice, this list of
-  conditions and the following disclaimer in the documentation and/or other
-  materials provided with the distribution.
-• Neither the name of Caltech nor its operating division, the Jet Propulsion
-  Laboratory, nor the names of its contributors may be used to endorse or
-  promote products derived from this software without specific prior written
-  permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
--->
-
-<document>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
   <properties>
     <title>Common Errors</title>
-    <author email="[email protected]">Jordan Padams</author>
   </properties>
 
   <body>
@@ -48,17 +16,19 @@ POSSIBILITY OF SUCH DAMAGE.
         If you would like to contribute to this page, please create a pull request or issue on our <a href="https://github.com/NASA-PDS/validate/">GitHub</a> 
         repository or email the <a href="mailto:[email protected]">PDS Operator</a> with input. Thanks in advance for helping your fellow users.
       </p>
-
+      
       <ul>
-        <li><a href="#White_spaces_are_required_error">White spaces are required error</a></li>
-        <li><a href="#java.lang.OutOfMemoryError">java.lang.OutOfMemoryError</a></li>
-        <li><a href="#No_checksum_found_in_the_manifest_errors">No checksum found in the manifest errors</a></li>
-        <li><a href="#error.table.fields_mismatch">error.table.fields_mismatch</a></li>
-        <li><a href="#error.label.context_ref_mismatch">error.label.context_ref_mismatch</a></li>
+        <li><a href="#whitespace">White spaces are required error</a></li>
+        <li><a href="#outofmemory">java.lang.OutOfMemoryError</a></li>
+        <li><a href="#nochecksum">No checksum found in the manifest errors</a></li>
+        <li><a href="#fields-mismatch">error.table.fields_mismatch</a></li>
+        <li><a href="#context-ref-mismatch">error.label.context_ref_mismatch</a></li>
+        <li><a href="#invalid-heap">Invalid maximum heap size</a></li>
+        <li><a href="#pdfa-issues">PDF/A Issues</a></li>
       </ul>
     </section>
 
-    <section name="White spaces are required error">
+    <section name="White spaces are required error" id="whitespace">
 
       <p>Execution of the Validate Tool may result in the following message appearing in the log:
       </p>
@@ -72,7 +42,7 @@ FAIL: file:/Users/.../hi0173794441_9080000_001_r.xml
       </p>
     </section>
 
-    <section name="java.lang.OutOfMemoryError">
+    <section name="java.lang.OutOfMemoryError" id="outofmemory">
       <p><b><i>Exception in thread "main" java.lang.OutOfMemoryError: GC overhead limit exceeded</i></b></p>
 
       <p>Running the tool against a large bundle may result in an OutOfMemoryError exception appearing in the standard error similar to the following:
@@ -113,7 +83,7 @@ Exception in thread "main" java.lang.OutOfMemoryError: GC overhead limit exceede
 
     </section>
 
-    <section name="No checksum found in the manifest errors">
+    <section name="No checksum found in the manifest errors" id="nochecksum">
 
       <p>When performing Checksum Manifest file validation, having the wrong base path setting will result in multiple errors like the following:
       </p>
@@ -128,7 +98,7 @@ FAIL: file:/home/pds4/dph_example_archive_VG2PLS/browse/Collection_browse.xml
 
     </section>
 
-    <section name="error.table.fields_mismatch">
+    <section name="error.table.fields_mismatch" id="fields-mismatch">
       <p><b>Debugging</b></p>
       <p>The error indicates the fields do not match the table defined in the label. Here are some things you can check to find out where it is failing:</p>
       <ul>
@@ -138,7 +108,7 @@ FAIL: file:/home/pds4/dph_example_archive_VG2PLS/browse/Collection_browse.xml
       </ul>
     </section>
 
-    <section name="error.label.context_ref_mismatch">
+    <section name="error.label.context_ref_mismatch" id="context-ref-mismatch">
       <p><b>Description</b></p>
       <p>
         New to Validate 1.16.0, this feature does a performs a check of the <i>name</i> and <i>type</i> values associated with
@@ -155,7 +125,7 @@ FAIL: file:/home/pds4/dph_example_archive_VG2PLS/browse/Collection_browse.xml
       </ul>
     </section>
 
-    <section name="Invalid maximum heap size">
+    <section name="Invalid maximum heap size" id="invalid-heap">
       <p><b>Description</b></p>
       <p>
         When attempting to run validate, you get the following error:
@@ -178,7 +148,7 @@ OpenJDK 64-Bit Server VM (build 15.0.1+9, mixed mode, sharing)
       </source>
     </section>
 
-    <section name="PDF/A Issues">
+    <section name="PDF/A Issues" id="pdfa-issues">
       <p><b>Description</b></p>
       <p>
         When attempting to validate a Document product as PDF/A, you get an error like: