updating documentation

brightdigit · Apr 29, 2024 · bd44d30 · bd44d30
1 parent b53cada
commit bd44d30
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -26,18 +26,15 @@ More powerful options for `Enum` and `OptionSet` types.
 
 # Table of Contents
 
-   * [**Introduction**](#introduction)
-   * [**Features**](#features)
-   * [**Installation**](#installation)
-   * [**Usage**](#usage)
-      * [Setting up a **`MappedValueRepresentable`** Enum](#setting-up-a-mappedvaluerepresentable-enum)
-      * [Using **`MappedValueCollectionRepresented`**](#using-mappedvaluecollectionrepresented)
-      * [Codable Enums using a **`MappedEnum`** Type](#codable-enums-using-a-mappedenum-type)
-      * [Using Enums in OptionSets with **`EnumSet`**](#using-enums-in-optionsets-with-enumset)
-      * [Converting **`EnumSet`** to Enum Array](#converting-enumset-to-enum-array)
-      * [Codable **`EnumSet`** using a **`MappedValueRepresentable`** Enum](#codable-enumset-using-a-mappedvaluerepresentable-enum)
-      * [Further Code Documentation](#further-code-documentation)
-   * [**License**](#license)
+  * [Introduction](#introduction)
+  * [Requirements](#requirements)
+  * [Installation](#installation)
+  * [Usage](#usage)
+    * [Versatile Options with Enums and OptionSets](#versatile-options-with-enums-and-optionsets)
+    * [Multiple Value Types](#multiple-value-types)
+    * [Creating an OptionSet](#creating-an-optionset)
+  * [Further Code Documentation](#further-code-documentation)
+  * [License](#license)
 
 # Introduction
 
@@ -72,7 +69,7 @@ Use version up to `1.0`.
 
 # Usage 
 
-## Versatile Options with Enums and OptionSets
+## Versatile Options
 
 Let's say we are using an `Enum` for a list of popular social media networks:
 

diff --git a/Scripts/gh-md-toc b/Scripts/gh-md-toc
@@ -23,7 +23,7 @@
 #       substr($0, match($0, "href=\"[^\"]+?\" ")+6, RLENGTH-8)
 #
 
-gh_toc_version="0.8.0"
+gh_toc_version="0.10.0"
 
 gh_user_agent="gh-md-toc v$gh_toc_version"
 
@@ -55,24 +55,24 @@ gh_toc_md2html() {
 
     URL=https://api.github.com/markdown/raw
 
-    if [ ! -z "$GH_TOC_TOKEN" ]; then
+    if [ -n "$GH_TOC_TOKEN" ]; then
         TOKEN=$GH_TOC_TOKEN
     else
         TOKEN_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/token.txt"
         if [ -f "$TOKEN_FILE" ]; then
-            TOKEN="$(cat $TOKEN_FILE)"
+            TOKEN="$(cat "$TOKEN_FILE")"
         fi
     fi
-    if [ ! -z "${TOKEN}" ]; then
+    if [ -n "${TOKEN}" ]; then
         AUTHORIZATION="Authorization: token ${TOKEN}"
     fi
 
     local gh_tmp_file_md=$gh_file_md
     if [ "$skip_header" = "yes" ]; then
-        if grep -Fxq "<!--te-->" $gh_src; then
+        if grep -Fxq "<!--te-->" "$gh_src"; then
           # cut everything before the toc
           gh_tmp_file_md=$gh_file_md~~
-          sed '1,/<!--te-->/d' $gh_file_md > $gh_tmp_file_md
+          sed '1,/<!--te-->/d' "$gh_file_md" > "$gh_tmp_file_md"
         fi
     fi
 
@@ -84,7 +84,7 @@ gh_toc_md2html() {
         -H "$AUTHORIZATION" \
         "$URL")
 
-    rm -f $gh_file_md~~
+    rm -f "${gh_file_md}~~"
 
     if [ "$?" != "0" ]; then
         echo "XXNetworkErrorXX"
@@ -152,7 +152,8 @@ gh_toc(){
             echo
         fi
     else
-        local rawhtml=$(gh_toc_md2html "$gh_src" "$skip_header")
+        local rawhtml
+        rawhtml=$(gh_toc_md2html "$gh_src" "$skip_header")
         if [ "$rawhtml" == "XXNetworkErrorXX" ]; then
              echo "Parsing local markdown file requires access to github API"
              echo "Please make sure curl is installed and check your network connectivity"
@@ -165,25 +166,28 @@ gh_toc(){
              echo "or place GitHub auth token here: ${TOKEN_FILE}"
              exit 1
         fi
-        local toc=`echo "$rawhtml" | gh_toc_grab "$gh_src_copy" "$indent"`
+        local toc
+        toc=`echo "$rawhtml" | gh_toc_grab "$gh_src_copy" "$indent"`
         echo "$toc"
         if [ "$need_replace" = "yes" ]; then
-            if grep -Fxq "<!--ts-->" $gh_src && grep -Fxq "<!--te-->" $gh_src; then
+            if grep -Fxq "<!--ts-->" "$gh_src" && grep -Fxq "<!--te-->" "$gh_src"; then
                 echo "Found markers"
             else
                 echo "You don't have <!--ts--> or <!--te--> in your file...exiting"
                 exit 1
             fi
             local ts="<\!--ts-->"
             local te="<\!--te-->"
-            local dt=`date +'%F_%H%M%S'`
+            local dt
+            dt=$(date +'%F_%H%M%S')
             local ext=".orig.${dt}"
             local toc_path="${gh_src}.toc.${dt}"
             local toc_createdby="<!-- Created by https://github.com/ekalinin/github-markdown-toc -->"
-            local toc_footer="<!-- Added by: `whoami`, at: `date` -->"
+            local toc_footer
+            toc_footer="<!-- Added by: `whoami`, at: `date` -->"
             # http://fahdshariff.blogspot.ru/2012/12/sed-mutli-line-replacement-between-two.html
             # clear old TOC
-            sed -i${ext} "/${ts}/,/${te}/{//!d;}" "$gh_src"
+            sed -i"${ext}" "/${ts}/,/${te}/{//!d;}" "$gh_src"
             # create toc file
             echo "${toc}" > "${toc_path}"
             if [ "${no_footer}" != "yes" ]; then
@@ -198,7 +202,7 @@ gh_toc(){
             fi
             echo
             if [ "${no_backup}" = "yes" ]; then
-                rm ${toc_path} ${gh_src}${ext}
+                rm "$toc_path" "$gh_src$ext"
             fi
             echo "!! TOC was added into: '$gh_src'"
             if [ -z "${no_backup}" ]; then
@@ -218,6 +222,8 @@ gh_toc(){
 # $2 - number of spaces used to indent.
 #
 gh_toc_grab() {
+
+    href_regex="/href=\"[^\"]+?\"/"
     common_awk_script='
                      modified_href = ""
                      split(href, chars, "")
@@ -237,26 +243,25 @@ gh_toc_grab() {
                     }
                     print sprintf("%*s", (level-1)*'"$2"', "") "* [" text "](" gh_url  modified_href ")"
                     '
-    if [ `uname -s` == "OS/390" ]; then
+    if [ "`uname -s`" == "OS/390" ]; then
         grepcmd="pcregrep -o"
         echoargs=""
         awkscript='{
-                     level = substr($0, length($0), 1)
-                     text = substr($0, match($0, /a>.*<\/h/)+2, RLENGTH-5)
-                     href = substr($0, match($0, "href=\"([^\"]+)?\"")+6, RLENGTH-7)
+                     level = substr($0, 3, 1)
+                     text = substr($0, match($0, /<\/span><\/a>[^<]*<\/h/)+11, RLENGTH-14)
+                     href = substr($0, match($0, '$href_regex')+6, RLENGTH-7)
                      '"$common_awk_script"'
                 }'
     else
         grepcmd="grep -Eo"
         echoargs="-e"
         awkscript='{
-                     level = substr($0, length($0), 1)
-                     text = substr($0, match($0, /a>.*<\/h/)+2, RLENGTH-5)
-                     href = substr($0, match($0, "href=\"[^\"]+?\"")+6, RLENGTH-7)
+                     level = substr($0, 3, 1)
+                     text = substr($0, match($0, /">.*<\/h/)+2, RLENGTH-5)
+                     href = substr($0, match($0, '$href_regex')+6, RLENGTH-7)
                      '"$common_awk_script"'
                 }'
     fi
-    href_regex='href=\"[^\"]+?\"'
 
     # if closed <h[1-6]> is on the new line, then move it on the prev line
     # for example:
@@ -265,8 +270,11 @@ gh_toc_grab() {
     #   became: The command <code>foo1</code></h1>
     sed -e ':a' -e 'N' -e '$!ba' -e 's/\n<\/h/<\/h/g' |
 
+    # Sometimes a line can start with <span>. Fix that.
+    sed -e ':a' -e 'N' -e '$!ba' -e 's/\n<span/<span/g' |
+
     # find strings that corresponds to template
-    $grepcmd '<a.*id="user-content-[^"]*".*</h[1-6]' |
+    $grepcmd '<h.*class="heading-element".*</a' |
 
     # remove code tags
     sed 's/<code>//g' | sed 's/<\/code>//g' |
@@ -275,7 +283,7 @@ gh_toc_grab() {
     sed 's/<g-emoji[^>]*[^<]*<\/g-emoji> //g' |
 
     # now all rows are like:
-    #   <a id="user-content-..." href="..."><span ...></span></a> ... </h1
+    #   <h1 class="heading-element">title</h1><a href="..."><span>..</span></a>
     # format result line
     #   * $0 - whole string
     #   * last element of each row: "</hN" where N in (1,2,3,...)
@@ -301,16 +309,17 @@ show_version() {
     echo
     for tool in curl wget grep awk sed; do
         printf "%-5s: " $tool
-        if `type $tool &>/dev/null`; then
-            echo `$tool --version | head -n 1`
+        if type $tool &>/dev/null; then
+            $tool --version | head -n 1
         else
             echo "not installed"
         fi
     done
 }
 
 show_help() {
-    local app_name=$(basename "$0")
+    local app_name
+    app_name=$(basename "$0")
     echo "GitHub TOC generator ($app_name): $gh_toc_version"
     echo ""
     echo "Usage:"
@@ -355,17 +364,18 @@ gh_toc_app() {
     if [ "$1" = "-" ]; then
         if [ -z "$TMPDIR" ]; then
             TMPDIR="/tmp"
-        elif [ -n "$TMPDIR" -a ! -d "$TMPDIR" ]; then
+        elif [ -n "$TMPDIR" ] && [ ! -d "$TMPDIR" ]; then
             mkdir -p "$TMPDIR"
         fi
         local gh_tmp_md
-        if [ `uname -s` == "OS/390" ]; then
-            local timestamp=$(date +%m%d%Y%H%M%S)
+        if [ "`uname -s`" == "OS/390" ]; then
+            local timestamp
+            timestamp=$(date +%m%d%Y%H%M%S)
             gh_tmp_md="$TMPDIR/tmp.$timestamp"
         else
-            gh_tmp_md=$(mktemp $TMPDIR/tmp.XXXXXX)
+            gh_tmp_md=$(mktemp "$TMPDIR/tmp.XXXXXX")
         fi
-        while read input; do
+        while read -r input; do
             echo "$input" >> "$gh_tmp_md"
         done
         gh_toc_md2html "$gh_tmp_md" | gh_toc_grab "" "$indent"
@@ -408,4 +418,4 @@ gh_toc_app() {
 #
 # Entry point
 #
-gh_toc_app "$@"
+gh_toc_app "$@"
diff --git a/Sources/Options/Documentation.docc/Documentation.md b/Sources/Options/Documentation.docc/Documentation.md
@@ -1,6 +1,6 @@
 # ``Options``
 
-Swift Package for more powerful `Enum` types.
+More powerful options for `Enum` and `OptionSet` types.
 
 ## Overview
 
@@ -33,7 +33,7 @@ https://github.com/brightdigit/Options.git
 
 Use version up to `1.0`.
 
-### Versatile Options with Enums and OptionSets
+### Versatile Options
 
 Let's say we are using an `Enum` for a list of popular social media networks: