mkdocktb - brltty - Git at Google

 #!/bin/bash -p
 ###############################################################################
 # BRLTTY - A background process providing access to the console screen (when in
 #          text mode) for a blind person using a refreshable braille display.
 #
 # Copyright (C) 1995-2023 by The BRLTTY Developers.
 #
 # BRLTTY comes with ABSOLUTELY NO WARRANTY.
 #
 # This is free software, placed under the terms of the
 # GNU Lesser General Public License, as published by the Free Software
 # Foundation; either version 2.1 of the License, or (at your option) any
 # later version. Please see the file LICENSE-LGPL for details.
 #
 # Web Page: http://brltty.app/
 #
 # This software is maintained by Dave Mielke <dave@mielke.cc>.
 ###############################################################################

 defaultOutputRoot="doc-ktb"

 . "`dirname "${0}"`/brltty-prologue.sh"
 addProgramOption s string.directory sourceRoot "top-level directory of source tree" "the location of this script"
 addProgramOption b string.directory buildRoot "top-level directory of build tree" "the source tree"
 addProgramOption o string.directory outputRoot "top-level directory of output tree" "${defaultOutputRoot}"
 addProgramOption k flag keepFiles "don't remove intermediate files"
 parseProgramArguments "${@}"

 set -e
 umask 022
 shopt -s nullglob

 [ -n "${sourceRoot}" ] || sourceRoot="$(dirname "${0}")"
 verifyInputDirectory "${sourceRoot}"
 sourceRoot="$(cd "${sourceRoot}" && pwd)"

 [ -n "${buildRoot}" ] || buildRoot="${sourceRoot}"
 buildRoot="$(cd "${buildRoot}" && pwd)"

 [ -n "${outputRoot}" ] || outputRoot="${defaultOutputRoot}"
 verifyOutputDirectory "${outputRoot}"

 unset HOME
 export XDG_CONFIG_HOME=/
 export XDG_CONFIG_DIRS=/

 readonly newLine=$'\n'

 lineGroups=()
 newLineGroup() {
    local variable="${1}"

    local group="lineGroup${#lineGroups[*]}"
    lineGroups+=("${group}")
    setVariable "${variable}" "${group}"

    declare -g -a "${group}"
    eval "${group}=()"
 }

 addLineToGroup() {
    local group="${1}"
    local line="${2}"

    eval "${group}+="'("${line}")'
 }

 newDocLines() {
    newLineGroup docLines
 }

 beginTocEntries() {
    local variable="${1}"

    newLineGroup "${variable}"
    newDocLines

    addLineToGroup "${!variable}" "<ul>"
 }

 endTocEntries() {
    local group="${1}"

    addLineToGroup "${group}" "</ul>"
 }

 addTocEntry() {
    local group="${1}"
    local title="${2}"
    local anchor="${3}"

    addLineToGroup "${group}" "<li><a href=\"#${anchor}\">${title}</a></li>"
 }

 addDocLine() {
    local line="${1}"

    addLineToGroup "${docLines}" "${line}"
 }

 addSectionTerminator() {
    addDocLine "<hr />"
 }

 addAnchor() {
    local anchor="${1}"

    addDocLine "<a name=\"${anchor}\"></a>"
 }

 beginDocument() {
    local title="${1}"

    newDocLines
    headerLevel=0

    addDocLine "<?xml version=\"1.0\" encoding=\"utf-8\" ?>"
    addDocLine "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">"

    addDocLine "<html xmlns=\"http://www.w3.org/1999/xhtml\" lang=\"en\" xml:lang=\"en\">"
    addDocLine "<head>"
    addDocLine "<title>${title}</title>"
    addDocLine "</head>"
    addDocLine "<body>"
 }

 endDocument() {
    local file="${1}"

    addDocLine "</body>"
    addDocLine "</html>"

    exec 3>"${file}"
       local group

       for group in "${lineGroups[@]}"
       do
          eval set -- '"${'"${group}"'[@]}"'
          local line

          for line
          do
             echo >&3 "${line}"
          done
       done
    exec 3>&-
 }

 beginSection() {
    local title="${1}"

    local anchor="${title,,?}"
    anchor="${anchor//[^a-zA-Z_0-9]/-}"
    addAnchor "${anchor}"

    headerLevel=$((headerLevel + 1))
    addDocLine "<h${headerLevel}>${title}</h${headerLevel}>"

    if ((headerLevel == 1))
    then
       beginTocEntries tocSections
       addSectionTerminator
    else
       addTocEntry "${tocSections}" "${title}" "${anchor}"
    fi
 }

 endSection() {
    if ((headerLevel == 1))
    then
       endTocEntries "${tocSections}"
    else
       addSectionTerminator
    fi

    headerLevel=$((headerLevel - 1))
 }

 beginLayoutList() {
    layoutListed=false
 }

 endLayoutList() {
    ! "${layoutListed}" || {
       addDocLine "</ul>"
    }
 }

 beginLayoutEntry() {
    local prefix="${1}"
    local outputExtension="${2}"

    local layout="${inputFile##*/}"
    layout="${layout%.*}"

    outputFile="${outputRoot}/${prefix}-${layout}.${outputExtension}"
 }

 endLayoutEntry() {
    local category="${1}"

    exec 4<"${outputFile%.*}.${plainTextExtension}"
    local description
    read -r -u 4 description
    exec 4<&-

    description="${description} "
    description="${description#*: }"
    [ -z "${category}" ] || description="${description#${category} }"
    description="${description% }"

    local prefix="All Models"
    [ -z "${description}" ] || {
       if [ "${description}" = "${description#(}" ]
       then
          prefix=""
       else
          prefix="${prefix} "
       fi
    }
    description="${prefix}${description}"

    "${layoutListed}" || {
       layoutListed=true
       addDocLine "<ul>"
    }

    addDocLine "<li><a href=\"${outputFile##*/}\">${description}</a></li>"
 }

 listKeyTable() {
    local driver="${1}"

    local input="${inputFile##*/}"
    local output="${outputFile%.*}"
    local name="${output##*/}"

    local command=( "${keyTableLister}" -D"${buildRoot}/lib" -T"${sourceRoot}/${tablesSubdirectory}" )
    [ -n "${driver}" ] && command+=( -b "${driver}" )
    "${command[@]}" -l "${input}" >"${output}.${plainTextExtension}" || {
       rm -f "${output}.${plainTextExtension}"
       return 1
    }

    "${command[@]}" -r "${input}" >"${output}.${reStructuredTextExtension}"
    sed -e "2a\\${newLine}* \`Help Screen Version <${name}.${plainTextExtension}>\`_" -i "${output}.${reStructuredTextExtension}"

    rst2html --config "${sourceRoot}/docutils.conf" "${output}.${reStructuredTextExtension}" "${output}.${hypertextExtension}"
    "${keepFiles}" || rm "${output}.${reStructuredTextExtension}"
 }

 listBrailleKeyTables() {
    beginSection "Braille Device Key Bindings"
    addDocLine "The driver automatically selects the appropriate key table for the device model being used."
    addDocLine "Click on the driver's name for general information about it."
    addDocLine "Click on the device model for its key bindings."

    local tocDrivers
    beginTocEntries tocDrivers

    addDocLine "<dl>"
    local driverDirectory

    for driverDirectory in "${driversDirectory}/"*
    do
       [ -d "${driverDirectory}" ] || continue

       local driverName="${driverDirectory##*/}"
       local driverCode="$(sed -n '/^DRIVER_CODE *=/s/^.*= *\([^ ]*\).*$/\1/p' "${driverDirectory}/Makefile.in")"

       local header="${driverName}"
       local inputFile="${driverDirectory}/README"

       [ ! -f "${inputFile}" ] || {
          local outputFile="${outputRoot}/${braillePrefix}-${driverCode}.${plainTextExtension}"
          cp -a -- "${inputFile}" "${outputFile}"
          header="<a href=\"${outputFile##*/}\">${header}</a>"
       }

       local anchor="${braillePrefix}-${driverCode}"
       addTocEntry "${tocDrivers}" "${driverName}" "${anchor}"

       addDocLine "<dt>"
       addAnchor "${anchor}"
       addDocLine "${header}"
       addDocLine "</dt><dd>"

       beginLayoutList
       set -- "${tablesDirectory}/${brailleSubdirectory}/${driverCode}/"*".${keyTableExtension}"

       if [ "${#}" -gt 0 ]
       then
          for inputFile
          do
             beginLayoutEntry "${braillePrefix}-${driverCode}" "${hypertextExtension}"
             listKeyTable "${driverCode}" || continue
             endLayoutEntry "${driverName}"
          done
       else
          set -- "${tablesDirectory}/${brailleSubdirectory}/${driverCode}/"*".${plainTextExtension}"

          for inputFile
          do
             beginLayoutEntry "${braillePrefix}-${driverCode}" "${plainTextExtension}"
             cp -a -- "${inputFile}" "${outputFile}"
             endLayoutEntry "${driverName}"
          done
       fi

       endLayoutList
       addDocLine "</dd>"
    done

    addDocLine "</dl>"
    endTocEntries "${tocDrivers}"
    endSection
 }

 listKeyboardKeyTables() {
    beginSection "Keyboard Key Tables"
    addDocLine "In order to use one of these keyboard tables,"
    addDocLine "you need to explicitly specify it in one of the following ways:"

    addDocLine "<ul>"
    addDocLine "<li>Use BRLTTY's <tt>-k</tt> (or <tt>--keyboard-table=</tt>) command line option.</li>"
    addDocLine "<li>Use the <tt>keyboard-table</tt> configuration file (<tt>brltty.conf</tt>) directive.</li>"
    addDocLine "</ul>"

    beginLayoutList
    set -- "${tablesDirectory}/${keyboardSubdirectory}/"*".${keyTableExtension}"

    local inputFile
    for inputFile
    do
       beginLayoutEntry "${keyboardPrefix}" "${hypertextExtension}"
       listKeyTable || continue
       endLayoutEntry
    done

    endLayoutList
    endSection
 }

 driversSubdirectory="Drivers/Braille"
 driversDirectory="${sourceRoot}/${driversSubdirectory}"

 tablesSubdirectory="Tables"
 tablesDirectory="${sourceRoot}/${tablesSubdirectory}"

 brailleSubdirectory="Input"
 keyboardSubdirectory="Keyboard"

 braillePrefix="brl"
 keyboardPrefix="kbd"

 plainTextExtension="txt"
 reStructuredTextExtension="rst"
 hypertextExtension="html"
 keyTableExtension="ktb"

 keyTableLister="${buildRoot}/Programs/brltty-ktb"
 make -C "${keyTableLister%/*}" -s "${keyTableLister##*/}"

 documentTitle="Key Binding Lists"
 beginDocument "${documentTitle}"

 beginSection "${documentTitle}"
 listBrailleKeyTables
 listKeyboardKeyTables
 endSection

 endDocument "${outputRoot}/index.${hypertextExtension}"
 exit 0
	#!/bin/bash -p
	###############################################################################
	# BRLTTY - A background process providing access to the console screen (when in
	# text mode) for a blind person using a refreshable braille display.
	#
	# Copyright (C) 1995-2023 by The BRLTTY Developers.
	#
	# BRLTTY comes with ABSOLUTELY NO WARRANTY.
	#
	# This is free software, placed under the terms of the
	# GNU Lesser General Public License, as published by the Free Software
	# Foundation; either version 2.1 of the License, or (at your option) any
	# later version. Please see the file LICENSE-LGPL for details.
	#
	# Web Page: http://brltty.app/
	#
	# This software is maintained by Dave Mielke <dave@mielke.cc>.
	###############################################################################

	defaultOutputRoot="doc-ktb"

	. "`dirname "${0}"`/brltty-prologue.sh"
	addProgramOption s string.directory sourceRoot "top-level directory of source tree" "the location of this script"
	addProgramOption b string.directory buildRoot "top-level directory of build tree" "the source tree"
	addProgramOption o string.directory outputRoot "top-level directory of output tree" "${defaultOutputRoot}"
	addProgramOption k flag keepFiles "don't remove intermediate files"
	parseProgramArguments "${@}"

	set -e
	umask 022
	shopt -s nullglob

	[ -n "${sourceRoot}" ] \|\| sourceRoot="$(dirname "${0}")"
	verifyInputDirectory "${sourceRoot}"
	sourceRoot="$(cd "${sourceRoot}" && pwd)"

	[ -n "${buildRoot}" ] \|\| buildRoot="${sourceRoot}"
	buildRoot="$(cd "${buildRoot}" && pwd)"

	[ -n "${outputRoot}" ] \|\| outputRoot="${defaultOutputRoot}"
	verifyOutputDirectory "${outputRoot}"

	unset HOME
	export XDG_CONFIG_HOME=/
	export XDG_CONFIG_DIRS=/

	readonly newLine=$'\n'

	lineGroups=()
	newLineGroup() {
	local variable="${1}"

	local group="lineGroup${#lineGroups[*]}"
	lineGroups+=("${group}")
	setVariable "${variable}" "${group}"

	declare -g -a "${group}"
	eval "${group}=()"
	}

	addLineToGroup() {
	local group="${1}"
	local line="${2}"

	eval "${group}+="'("${line}")'
	}

	newDocLines() {
	newLineGroup docLines
	}

	beginTocEntries() {
	local variable="${1}"

	newLineGroup "${variable}"
	newDocLines

	addLineToGroup "${!variable}" "<ul>"
	}

	endTocEntries() {
	local group="${1}"

	addLineToGroup "${group}" "</ul>"
	}

	addTocEntry() {
	local group="${1}"
	local title="${2}"
	local anchor="${3}"

	addLineToGroup "${group}" "<li><a href=\"#${anchor}\">${title}</a></li>"
	}

	addDocLine() {
	local line="${1}"

	addLineToGroup "${docLines}" "${line}"
	}

	addSectionTerminator() {
	addDocLine "<hr />"
	}

	addAnchor() {
	local anchor="${1}"

	addDocLine "<a name=\"${anchor}\"></a>"
	}

	beginDocument() {
	local title="${1}"

	newDocLines
	headerLevel=0

	addDocLine "<?xml version=\"1.0\" encoding=\"utf-8\" ?>"
	addDocLine "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">"

	addDocLine "<html xmlns=\"http://www.w3.org/1999/xhtml\" lang=\"en\" xml:lang=\"en\">"
	addDocLine "<head>"
	addDocLine "<title>${title}</title>"
	addDocLine "</head>"
	addDocLine "<body>"
	}

	endDocument() {
	local file="${1}"

	addDocLine "</body>"
	addDocLine "</html>"

	exec 3>"${file}"
	local group

	for group in "${lineGroups[@]}"
	do
	eval set -- '"${'"${group}"'[@]}"'
	local line

	for line
	do
	echo >&3 "${line}"
	done
	done
	exec 3>&-
	}

	beginSection() {
	local title="${1}"

	local anchor="${title,,?}"
	anchor="${anchor//[^a-zA-Z_0-9]/-}"
	addAnchor "${anchor}"

	headerLevel=$((headerLevel + 1))
	addDocLine "<h${headerLevel}>${title}</h${headerLevel}>"

	if ((headerLevel == 1))
	then
	beginTocEntries tocSections
	addSectionTerminator
	else
	addTocEntry "${tocSections}" "${title}" "${anchor}"
	fi
	}

	endSection() {
	if ((headerLevel == 1))
	then
	endTocEntries "${tocSections}"
	else
	addSectionTerminator
	fi

	headerLevel=$((headerLevel - 1))
	}

	beginLayoutList() {
	layoutListed=false
	}

	endLayoutList() {
	! "${layoutListed}" \|\| {
	addDocLine "</ul>"
	}
	}

	beginLayoutEntry() {
	local prefix="${1}"
	local outputExtension="${2}"

	local layout="${inputFile##*/}"
	layout="${layout%.*}"

	outputFile="${outputRoot}/${prefix}-${layout}.${outputExtension}"
	}

	endLayoutEntry() {
	local category="${1}"

	exec 4<"${outputFile%.*}.${plainTextExtension}"
	local description
	read -r -u 4 description
	exec 4<&-

	description="${description} "
	description="${description#*: }"
	[ -z "${category}" ] \|\| description="${description#${category} }"
	description="${description% }"

	local prefix="All Models"
	[ -z "${description}" ] \|\| {
	if [ "${description}" = "${description#(}" ]
	then
	prefix=""
	else
	prefix="${prefix} "
	fi
	}
	description="${prefix}${description}"

	"${layoutListed}" \|\| {
	layoutListed=true
	addDocLine "<ul>"
	}

	addDocLine "<li><a href=\"${outputFile##*/}\">${description}</a></li>"
	}

	listKeyTable() {
	local driver="${1}"

	local input="${inputFile##*/}"
	local output="${outputFile%.*}"
	local name="${output##*/}"

	local command=( "${keyTableLister}" -D"${buildRoot}/lib" -T"${sourceRoot}/${tablesSubdirectory}" )
	[ -n "${driver}" ] && command+=( -b "${driver}" )
	"${command[@]}" -l "${input}" >"${output}.${plainTextExtension}" \|\| {
	rm -f "${output}.${plainTextExtension}"
	return 1
	}

	"${command[@]}" -r "${input}" >"${output}.${reStructuredTextExtension}"
	sed -e "2a\\${newLine}* \`Help Screen Version <${name}.${plainTextExtension}>\`_" -i "${output}.${reStructuredTextExtension}"

	rst2html --config "${sourceRoot}/docutils.conf" "${output}.${reStructuredTextExtension}" "${output}.${hypertextExtension}"
	"${keepFiles}" \|\| rm "${output}.${reStructuredTextExtension}"
	}

	listBrailleKeyTables() {
	beginSection "Braille Device Key Bindings"
	addDocLine "The driver automatically selects the appropriate key table for the device model being used."
	addDocLine "Click on the driver's name for general information about it."
	addDocLine "Click on the device model for its key bindings."

	local tocDrivers
	beginTocEntries tocDrivers

	addDocLine "<dl>"
	local driverDirectory

	for driverDirectory in "${driversDirectory}/"*
	do
	[ -d "${driverDirectory}" ] \|\| continue

	local driverName="${driverDirectory##*/}"
	local driverCode="$(sed -n '/^DRIVER_CODE =/s/^.= \([^ ]\).*$/\1/p' "${driverDirectory}/Makefile.in")"

	local header="${driverName}"
	local inputFile="${driverDirectory}/README"

	[ ! -f "${inputFile}" ] \|\| {
	local outputFile="${outputRoot}/${braillePrefix}-${driverCode}.${plainTextExtension}"
	cp -a -- "${inputFile}" "${outputFile}"
	header="<a href=\"${outputFile##*/}\">${header}</a>"
	}

	local anchor="${braillePrefix}-${driverCode}"
	addTocEntry "${tocDrivers}" "${driverName}" "${anchor}"

	addDocLine "<dt>"
	addAnchor "${anchor}"
	addDocLine "${header}"
	addDocLine "</dt><dd>"

	beginLayoutList
	set -- "${tablesDirectory}/${brailleSubdirectory}/${driverCode}/"*".${keyTableExtension}"

	if [ "${#}" -gt 0 ]
	then
	for inputFile
	do
	beginLayoutEntry "${braillePrefix}-${driverCode}" "${hypertextExtension}"
	listKeyTable "${driverCode}" \|\| continue
	endLayoutEntry "${driverName}"
	done
	else
	set -- "${tablesDirectory}/${brailleSubdirectory}/${driverCode}/"*".${plainTextExtension}"

	for inputFile
	do
	beginLayoutEntry "${braillePrefix}-${driverCode}" "${plainTextExtension}"
	cp -a -- "${inputFile}" "${outputFile}"
	endLayoutEntry "${driverName}"
	done
	fi

	endLayoutList
	addDocLine "</dd>"
	done

	addDocLine "</dl>"
	endTocEntries "${tocDrivers}"
	endSection
	}

	listKeyboardKeyTables() {
	beginSection "Keyboard Key Tables"
	addDocLine "In order to use one of these keyboard tables,"
	addDocLine "you need to explicitly specify it in one of the following ways:"

	addDocLine "<ul>"
	addDocLine "<li>Use BRLTTY's <tt>-k</tt> (or <tt>--keyboard-table=</tt>) command line option.</li>"
	addDocLine "<li>Use the <tt>keyboard-table</tt> configuration file (<tt>brltty.conf</tt>) directive.</li>"
	addDocLine "</ul>"

	beginLayoutList
	set -- "${tablesDirectory}/${keyboardSubdirectory}/"*".${keyTableExtension}"

	local inputFile
	for inputFile
	do
	beginLayoutEntry "${keyboardPrefix}" "${hypertextExtension}"
	listKeyTable \|\| continue
	endLayoutEntry
	done

	endLayoutList
	endSection
	}

	driversSubdirectory="Drivers/Braille"
	driversDirectory="${sourceRoot}/${driversSubdirectory}"

	tablesSubdirectory="Tables"
	tablesDirectory="${sourceRoot}/${tablesSubdirectory}"

	brailleSubdirectory="Input"
	keyboardSubdirectory="Keyboard"

	braillePrefix="brl"
	keyboardPrefix="kbd"

	plainTextExtension="txt"
	reStructuredTextExtension="rst"
	hypertextExtension="html"
	keyTableExtension="ktb"

	keyTableLister="${buildRoot}/Programs/brltty-ktb"
	make -C "${keyTableLister%/}" -s "${keyTableLister##/}"

	documentTitle="Key Binding Lists"
	beginDocument "${documentTitle}"

	beginSection "${documentTitle}"
	listBrailleKeyTables
	listKeyboardKeyTables
	endSection

	endDocument "${outputRoot}/index.${hypertextExtension}"
	exit 0