Add CDM Section Specification documentation

Fixes #1528

Author: lesserwhirls

docs/src/site/_data/sidebars/netcdfJavaTutorial_sidebar.yml

@@ -159,6 +159,10 @@ entries:
               url: /arraystructures_ref.html
               output: web, pdf
 
+            - title: CDM Section Specification
+              url: /section_specification_ref.html
+              output: web, pdf
+
             - title: CDM Calendar Date Handling
               url: /cdm_calendar_date_time_ref.html
               output: web, pdf

docs/src/site/pages/netcdfJava/SectionSpecification.md

@@ -0,0 +1,61 @@
+---
+title: Section Specification
+last_updated: 2026-06-23
+sidebar: netcdfJavaTutorial_sidebar
+toc: false
+permalink: section_specification_ref.html
+---
+## CDM Section Specification
+
+### Syntax
+
+Array sections can be specified with Fortran 90 array section syntax, using zero-based indexing. For example:
+
+`/group1/group2/varName(12:22,0:100:2,:,17)`
+
+specifies an array section for a four-dimensional variable:
+
+1. `12:22` includes all the elements from 12 to 22 inclusive
+1. `0:100:2` includes the elements from 0 to 100 inclusive, with a stride of 2
+1. `:` includes all the elements
+1. `17` includes just the 18th element.
+
+For structures, you can specify nested selectors, e.g. `record(12).wind(1:20,:,3)` does a selection on the `wind` member variable of the `record` structure at index 12.
+If you don’t specify a section, it means read the entire variable, e.g. `record.wind` means all the data in all the wind variables in all the record structures.
+
+Formally:
+
+```
+sectionSpec := selector | selector '.' selector
+selector := varName ['(' sectionSpec ')']
+varName := STRING
+sectionSpec := dim | dim ',' sectionSpec
+dim := ':' | slice | start ':' end | start ':' end ':' stride
+
+
+slice := INTEGER
+start := INTEGER
+stride := INTEGER
+end := INTEGER
+STRING := String with escaped chars = '.', '/', '(', and ')'
+```
+
+where:
+
+* Nonterminals are in lower case, terminals are in upper case, and literals are in single quotes.
+* Optional components are enclosed between square braces `[` and `]`.
+
+TBD:
+
+* escape mechanism is currently %xx , mostly following opendap
+* not sure if any other chars need to be escaped.
+
+### Restrictions
+
+A Sequence is a one-dimensional Structure with a variable length, it cannot be subsetted.
+
+A variable long name must be used, that is with its group names: `/group1/group2/varName`
+
+### Use
+
+`public Array NetcdfFile.readSection(String variableSection);`

docs/src/site/pages/netcdfJava_tutorial/cdmdatasets/readingcdm.md

@@ -54,6 +54,7 @@ Note that you can edit the `Variable`'s ranges (`T(0:30:10, 1, 0:3)` in this exa
 These are expressed with Fortran 90 array section syntax, using zero-based indexing.
 For example, `varName( 12:22 , 0:100:2, :, 17)` specifies an array section for a four dimensional variable.
 The first dimension includes all the elements from 12 to 22 inclusive, the second dimension includes the elements from 0 to 100 inclusive with a stride of 2, the third includes all the elements in that dimension, and the fourth includes just the 18th element.
+The [CDM section specification](section_specification_ref.html) describes the section string syntax in more detail.
 
 The following code to dump data from your program is equivalent to the above ToolsUI actions:
 
@@ -98,20 +99,22 @@ Or suppose you want to loop over all time steps, and make it general to handle a
 In this case, we call reduce(0), to reduce dimension 0, which we know has length one, but leave the other two dimensions alone.
 
 Note that `varShape` holds the total number of elements that can be read from the variable; `origin` is the starting index, and `size` is the number of elements to read.
-This is different from the Fortran 90 array syntax, which uses the starting and ending array indices (inclusive):
+This is different from the section (Fortran 90) array syntax, which uses the starting and ending array indices (inclusive):
 
 {% capture rmd %}
 {% includecodeblock netcdf-java&docs/src/test/java/examples/cdmdatasets/ReadingCdmTutorial.java&readSubset %}
 {% endcapture %}
 {{ rmd | markdownify }}
 
-If you want strided access, you can use the Fortran 90 string routine:
+If you want strided access, you can use the section string method:
 
 {% capture rmd %}
 {% includecodeblock netcdf-java&docs/src/test/java/examples/cdmdatasets/ReadingCdmTutorial.java&readByStride %}
 {% endcapture %}
 {{ rmd | markdownify }}
 
+The [CDM section specification](section_specification_ref.html) describes the section string syntax in more detail.
+
 #### Reading with Range Objects
 
 For general programing, use the read method that takes a `List` of `ucar.ma2.Range` objects.