Online Amateur Radio Community Wiki

This is an old revision of the document!
#!/bin/bash
##################################
# by Jason M0MZF (not a programmer!)
# bash / awk / hammer / nail etc.
# License - MIT. Crack on people.
# 
# Script to parse Paula G8PZT's Xrouter MAN and HLP files into DocuWiki
# "some simple markup language" (SSML). DocuWiki ML syntax is here:
# https://www.dokuwiki.org/wiki:syntax
#
# The intention is to parse all MAN / HLP files within the folders and
# write them with appropriate formatting to files which can then be
# pasted directly into the wiki.
#
# This could also be done with groff > HTML > pandoc > ssml but pandoc's
# output format for SSML doesn't sort out proper ====headers==== and I 
# don't know Lua. Yet. Maybe something like this with a custom output formatter:
# cat ${manpage} | groff -Thtml -P -l -mmandoc 2>/dev/null | pandoc -f html -t dokuwiki -o "$manpage".txt
# But when all you've got is awk, everything looks like a record / field... ;)
#
##################################
# Instructions (destructions?)
#
# - This script does not take any arguments
# - The only required configuration is to set the wiki namespace
NAMESPACE="packet:xrouter:docs:"
#   and the working folder for the script
BASEPATH=/home/jason/radio/packet/xrouter/Xrouter
# This folder should contain the two directories "XRouter Help Files"
# and "XRouter Manual Files". A new directory will be created here
# called "docuwiki-date" and contains two directories for the 
# concatenated and reformatted files. These files should be pasted into
# wiki pages created by the index file.
#
# The index file created contains a list of all files parsed by this
# script with docuwiki-formatted links to each command. This index file
# should be pasted into the namespace to update the index.
#
# The file structure we're working with currently is
# BASEPATH/MANPAGES/SECTION1/ENTRY1.MAN
#			    /ENTRY2.MAN ...
# 		    SECTION2/ENTRY1.MAN
# 		    	    /ENTRY2.MAN ...
# BASEPATH/HLPFILES/SECTION1/ENTRY1.HLP
#			    /ENTRY2.HLP
# 		    SECTION2/ENTRY1.HLP
#			    /ENTRY2.HLP ...
#
# and the output structure is
# OUTPUTDIR/index.docuwiki
# OUTPUTDIR/MAN/SECTION1.docuwiki
#  		SECTION2.docuwiki ...
# OUTPUTDIR/HLP/SECTION1.docuwiki
#  		SECTION2.docuwiki ...
##################################
# Changelog
# 20250418 - Implemented MAN page parsing
# 20250419 - Implemented HLP page parsing
# 20250419 - Tidy up, more awk less bash, remove .MAN / .HLP from outputted headers
# 20250422 - Tidy up, create an index of commands and create links to sections
##################################
 
# Globals
DATE=$(date +"%Y%m%d-%H%M%S")
MAN="$BASEPATH/XRouter Manual Files"
HLP="$BASEPATH/XRouter Help Files"
OUTPUTDIR="$BASEPATH/docuwiki-$DATE"
INDEXFILE="${OUTPUTDIR}"/index.docuwiki
 
# Wiki MANPAGE namespace structure. We pass this into awk later but define it here
 
 
# Handy functions
echoRed () {
	echo -e "\e[1;31m----$1----\e[0m"
}
echoGreen () {
	echo -e "\e[1;32m----$1----\e[0m"
}
checkRoot () {
	if [[ $UID -eq 0 ]]; then
		echoRed "Don't run this as root please"
		exit
	fi
}
 
# Use awk to:
#  strip whitespace out of the folder structure to make a docuwiki-compatible namespace
#  and ouput a #link to one of the headers created by the later parsing
awkFormatIndexTitle='
{
	gsub(" ", "")
	print "[[" ns $0 "#" ti "|" ti  "]]"
}
'
 
# Use awk to:
#  strip out comment lines and remove any <CR> from <CR><LF> lines
#  turn the MAN page header into a code block, it contains a revision date
#  find every subsequent MAN page header and turn it into a docuwiki header and
#   terminate the previous code block before the header, then
#   create a new code block after the header, thus encapsulating the subsection
# (the final encapsulation is done using "echo" in the bash script below)
awkParseMan='
{
	if (NR==1 || NR==2)				# For the first two lines
	{
		gsub("\r", "")				# remove all carriage return chars
		if (/^;/ || NF==0) {next}		# skip the subsequent print function for comment or empty lines
		print "<code>" $0			# annd output the line prepended with a code block start
	}
 
	if (NR>=3)					# For the other lines
	{
		if (/^[A-Z]/) 				# If the line begins with a character
		{
			starthead="</code> **"		# end previous code block
			endhead="** <code>"		# set bold and start code block
			gsub("\r", "")			# remove all carriage return chars
			print starthead $0 endhead 	# and output the line
		}
		else 					# else for all other lines
		{
			if (/^;/) {next}		# skip comment lines
			gsub("\r", "")			# remove all carriage return chars
			print $0			# and output the line
		}
	}
}
'
# Use awk to:
#  strip out comment lines (this is always line 1, sometime 2 and 3) and remove any <CR> from <CR><LF> lines
#  insert a start code block in place of the now-empty line 1
# (the final encapsulation is done using "echo" in the bash script below)
awkParseHlp='
{
	endhead="<code>"
	gsub("\r", "")					# remove all carriage return chars
	if (NR==1) {print endhead}			# start code block on first line
	if (/^;/ || NF==0) {next}			# skip comment / empty lines
	print $0					# output the refined line
}
'
 
parseFiles () {
	mkdir "${OUTPUTDIR}/$1"
	echo "==== $1 Files ====" >> "$INDEXFILE"
	# Traverse folders, skipping files in base directory
	for folder in "${!1}"/*/
	do
		# Get the penultimate field in file path, i.e. the section (folder) name
		local section=$(echo $folder | awk  -F/ '{print $(NF-1)}')
		# Use the section name to generate a file foreach section
		local outputpath="${OUTPUTDIR}"/"$1"/"${section}".docuwiki
		# Create formatted section for wiki index page
		echo "== $section ==" >> "$INDEXFILE"
		# and create a formatted header for the wiki content
		echo "====== $section ======" >> "$outputpath"
		# Spit some stuff out to the shell
		echoRed "$section"
		# Traverse through files
		for file in "$folder"*
		do
			# Get file name from last filed file path        | and strip file extension
			local title=$(echo $file | awk -F/ '{print $NF}' | awk -F. '{print $1}')
			# Begin by writing a docuwiki header containing file name
			echo "==== $title ====" >> "$outputpath"
			# and write a path into the index file
			echo "$section" | awk -v ns="$NAMESPACE" -v ti="$title" "$awkFormatIndexTitle" >> "$INDEXFILE"
			case "$1" in
			# For MAN files, after awk has done it's job we need to remove the last line; this last line breaks
			# the following <code> statement and is just an EOF message, so we don't lose anything.
			MAN)	awk "$awkParseMan" "$file" | head -n -1 >> "$outputpath"
				echo -e "</code>\n----" >> "$outputpath"
			;;
			# For HLP files we don't want to remove the last line because that truly is real content
			HLP)	awk "$awkParseHlp" "$file" >> "$outputpath"
				echo "</code>" >> "$outputpath"
			;;
#			DOC)	echoRed "No code to parse docs yet"
#			;;
			esac
		done
	done
}
 
#Let's go!
checkRoot
mkdir "$OUTPUTDIR"
echo "======= XRouter Documentation =======" >> "$INDEXFILE"
echo "The content below is auto-generated from the XRouter documentation using [[$NAMESPACE:parsing|this bash / awk script]] to parse MAN / HLP files into docuWiki some simple markup language" >> "$INDEXFILE"
echoGreen "Parsing MAN files from $MANFILES"
parseFiles MAN
echoGreen "Parsing HLP files from $HLPFILES"
parseFiles HLP
#echoGreen "Parsing DOC files from $DOCFILES"
#parseFiles DOC