num_channels wording and updated github action to be able to view pdf…

…/html as an artifact (#319)

* num_channels wording

* Update additional_content.md

* Update generate_docs_pr.yml

* Update generate_docs_pr.yml

* Update README.md

* Update additional_content.md

* Update additional_content.md

* Update .github/workflows/generate_docs_pr.yml

Co-authored-by: Teque5 <[email protected]>

* Update README.md

Co-authored-by: Teque5 <[email protected]>

* Update generate_docs.yml

* Update generate_docs_pr.yml

* Update generate_docs.yml

* Update generate_docs_pr.yml

* Update generate_docs.yml

* Update generate_docs_pr.yml

---------

Co-authored-by: Teque5 <[email protected]>

.github/workflows/generate_docs.yml

@@ -46,10 +46,12 @@ jobs:
         run: pandoc -v
       - name: Rename to index.html
         run: mv sigmf-spec.html index.html
+      - name: Remove pandoc lib
+        run: rm -r pandoc*
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v3.0.1
         with:
           path: '.' # Upload entire repository for now, TODO ONLY UPLOAD THE HTML AND PDF IN THE LONG TERM
       - name: Deploy to GitHub Pages

.github/workflows/generate_docs_pr.yml

@@ -1,4 +1,4 @@
-name: Build docs to check for errors
+name: Build docs [PR]
 
 on:
   pull_request:
@@ -29,3 +29,10 @@ jobs:
         run: ls -la
       - name: Check pandoc version
         run: pandoc -v
+      - name: Remove pandoc lib
+        run: rm -r pandoc*
+      - name: Upload output as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: compiled_docs
+          path: '.'

README.md

@@ -93,6 +93,8 @@ The main pdf is generated using the following content:
 
 The script `docs-generator.py` uses Python, PyLaTeX, Pandoc, and Inkscape to create the specifications document in PDF and HTML formats.
 
+Instead of generating the docs locally, you can make your change (e.g., using GitHub's web interface), open up a PR, and then under GitHub's "Actions" menu at the top, click the run that corresponds to your PR, scroll down to "Artifacts", download the artifact named "compiled_docs", unzip it, and you should be able to see the html and pdf.
+
 ## Frequently Asked Questions
 
 ### Is this a GNU Radio effort?

additional_content.md

@@ -160,16 +160,9 @@ The samples SHOULD be written to the Dataset file without separation, and the
 Dataset file MUST NOT contain any other characters (e.g., delimiters,
 whitespace, line-endings, EOF characters).
 
-Complex samples MUST be interleaved, with the in-phase component first (i.e.,
-`I[0]` `Q[0]` `I[1]` `Q[1]` ... `I[n]` `Q[n]`). When `core:num_channels` in the
-Global Object (described below) indicates that the Recording contains more than one channel,
-samples from those channels MUST be interleaved in the same manner, with
-the same index from each channel's sample serially in the Recording. For
-example, a Recording with two channels of `ri16_le` representing real-valued
-audio data from a stereo Recording and here labeled `L` for left and `R` for
-right, the data MUST appear as `L[0]` `R[0]` `L[1]` `R[1]` ... `L[n]` `R[n]`.
-The data type specified by `core:data_type` applies to all channels of data
-both real and imaginary parts.
+Complex samples MUST be interleaved, with the in-phase component first (i.e., `I[0]` `Q[0]` `I[1]` `Q[1]` ... `I[n]` `Q[n]`). 
+
+When `core:num_channels` in the Global Object (described below) indicates that the Recording contains more than one channel, samples from those channels MUST be interleaved in the same manner with the same index from each channel's sample serially in the Recording. This is intended for use in situations where the native SigMF datatypes are not appropriate, such as audio or oscilloscope channels. For best compatibility, is RECOMMENDED that native complex type datatypes be used whenever possible (e.g.: RF data).  The data type specified by core:data_type applies to all channels of data.  For multiple channels of IQ data (e.g., array processing), it is RECOMMENDED to use SigMF Collections.
 
 \subsection{SigMF Metadata Format}
 

sigmf-schema.json

@@ -65,7 +65,7 @@
           "type": "string"
         },
         "core:num_channels": {
-          "description": "Total number of interleaved channels in the Dataset file; if omitted this is implied to be 1. For multiple channels of IQ data, it is RECOMMENDED to use SigMF Collections instead of num_channels for widest application support.",
+          "description": "Number of interleaved channels in the Dataset file, if omitted this is implied to be 1, for multiple channels of IQ data, it is RECOMMENDED to use SigMF Collections instead of num_channels for widest application support.",
           "default": 1,
           "minimum": 1,
           "maximum": 1000,
@@ -124,7 +124,7 @@
           }
         },
         "core:extensions": {
-          "description": "The `core:extensions` field in the Global Object is an array of extension objects that describe SigMF extensions. Extension Objects MUST contain the three key/value pairs defined below, and MUST NOT contain any other fields. \\rowcolors{1}{}{lightblue}\\begin{center}\\begin{tabular}{lllp{3.8in}} \\toprule \\textbf{Name} & \\textbf{Required} & \\textbf{Type} & \\textbf{Description} \\\\ \\midrule name & true & string & The name of the SigMF extension namespace. \\\\ version & true & string & The version of the extension namespace specification used. \\\\ optional & true & boolean & If this field is `false`, then the application MUST support this extension in order to parse the Recording; if the application does not support this extension, it SHOULD report an error. \\\\ \\bottomrule \\end{tabular} \\end{center} In the example below, `extension-01` is optional, so the application may ignore it if it does not support `extension-01`. But `extension-02` is not optional, so the application must support `extension-02` in order to parse the Recording.  \\begin{verbatim}\"global\": {\n     ...\n     \"core:extensions\" : [\n         {\n         \"name\": \"extension-01\",\n         \"version\": \"0.0.5\",\n         \"optional\": true\n         },\n         {\n         \"name\": \"extension-02\",\n         \"version\": \"1.2.3\",\n         \"optional\": false\n         }\n     ]\n     ...\n }\\end{verbatim}",
+          "description": "The `core:extensions` field in the Global Object is an array of extension objects that describe SigMF extensions. Extension Objects MUST contain the three key/value pairs defined below, and MUST NOT contain any other fields. \\rowcolors{1}{}{lightblue}\\begin{center}\\begin{tabular}{lllp{3.8in}} \\toprule \\textbf{Name} & \\textbf{Required} & \\textbf{Type} & \\textbf{Description} \\\\ \\midrule name & true & string & The name of the SigMF extension namespace. \\\\ version & true & string & The version of the extension namespace specification used. \\\\ optional & true & boolean & If this field is `false`, then the application MUST support this extension in order to parse the Recording; if the application does not support this extension, it SHOULD report an error. \\\\ \\bottomrule \\end{tabular} \\end{center} \\\\ In the example below, `extension-01` is optional, so the application may ignore it if it does not support `extension-01`. But `extension-02` is not optional, so the application must support `extension-02` in order to parse the Recording.  \\begin{verbatim}\"global\": {\n     ...\n     \"core:extensions\" : [\n         {\n         \"name\": \"extension-01\",\n         \"version\": \"0.0.5\",\n         \"optional\": true\n         },\n         {\n         \"name\": \"extension-02\",\n         \"version\": \"1.2.3\",\n         \"optional\": false\n         }\n     ]\n     ...\n }\\end{verbatim}",
           "type": "array",
           "default": [],
           "additionalItems": false,