elinks/doc/tools/help2doc

#!/bin/sh
#
#
# Script used to generate doc/book/config/cmdoptions.xml
# and hopefully other in the future.

# Updated by option handlind via --elinks=path/to/elinks option
elinks="elinks"

# Utility functions {{{1

usage()
{
	msg="$1"
	echo "$msg" >&2
	echo "`basename $0` ($script_version)" >&2
	echo "Usage: $0 [ --cmdoptions | --elinksconf | - | --elinks=path/to/elinks ]" >&2
	cat >&2 <<END_OF_USAGE
	--cmdoptions	Print asciidoc markup with summary of the command options
	--elinksconf	Print the elinks.conf.5 manpage
	-           	Read option info (elinks --config-help) from stdin
	--elinks=path	Use the elinks program with the given path
END_OF_USAGE
	exit -1
}

# Option handling {{{1

command=
filter=cat
prev_option=

for option
do
	# If the previous option needs an argument, assign it.
	if test -n "$prev_option"; then
		eval "$prev_option=\$option"
		prev_option=
		continue
	fi

	case "$option" in
		--cmdoptions)
			command="$elinks -long-help"
			filter="sed 0,/^Options:/d"
			backend="cmdoptions"
		;;
		--elinksconf)
			command="$elinks -config-help"
			filter="sed 0,/^Configuration/d"
			backend="elinksconf"
		;;
		-)
			command="cat /dev/stdin"
		;;
		--elinks=*)
			elinks="`echo $option | sed -e 's/.*=//'`"
		;;
		*)
			usage "Unknown option"
		;;
	esac
done

if test -z "$backend";
then
	usage "No backend defined"
fi

date_string=`date -I`
script_version=`echo "\\$Revision: 1.19 $" | sed -e 's/\\$\(.*\) \\$/\1/'`
elinks_version="`$elinks -version | head -n 1 | sed -e 's/ELinks \([0-9][^ ]*\).*/\1/'`"
script_info="Generated by `basename $0` ($script_version) on $date_string"
script_info="$script_info using output from ELinks version $elinks_version."
dist_info="`basename $0` is distributed with ELinks under the terms of the GPL."

# Backends {{{1

print_header="print_${backend}_header"
print_footer="print_${backend}_footer"
print_description_end="print_${backend}_description_end"
print_description_line="print_${backend}_description_line"
print_option_tree="print_${backend}_option_tree"
print_option_type="print_${backend}_option_type"

# --cmdoptions backend {{{2

print_cmdoptions_header()
{
	echo
}

print_cmdoptions_footer()
{
	echo
}

print_cmdoptions_description_end()
{
	echo
}

print_cmdoptions_description_line()
{
	line="$1"
	number="$2"

	case "$line" in
	-eval*)
		echo
		;;
	*)
		line="$(echo $line | sed 's,\(-touch-files\|-no-connect\|-session-ring\|-dump\|-default-mime-type\|text/html\|~/\.elinks\),\`\1\`,g')"
		line=$(echo $line | sed "s,'\([^']*\)',\\\'\1\\\',")
		line=$(echo $line | sed "s,ELinks,'ELinks',g")
		line=$(echo $line | sed "s,HOME,'HOME',g")
		line="$(echo $line | sed 's/^\([a-zA-Z]*([^)]*)\).*:/- \`\1\`:/')"

		if test -n "$number";
		then
			echo -n "	- $number:"
		fi
	esac
	echo "	$line"
}

print_cmdoptions_option_tree()
{
	parse_description=
}

print_cmdoptions_option_type()
{
	path="$1"
	typeid="$2"
	default="$3"
	typestring="$path"
	if test -n "$typeid" && test "$typeid" != "$path";
	then
		if test "$typeid" = "(alias";
		then
			typestring="$typestring ($default)"
			default=
		else
			typestring="$typestring $typeid"
		fi
	fi
	if test -n "$default" && test "$default" != "$path";
	then
		typestring="$typestring ($default)"
	fi
	if test "$default" = "-?, -h, -help";
	then
		typestring="$default"
	fi
	echo "$typestring::"
}

# --elinksconf backend {{{2

print_elinksconf_header()
{
	cat << __END__
.\" elinks.conf.5
.\"
.\" $script_info
.\"
.\" Copyleft (c) 2002-2004 The ELinks project
.\"
.\" This file may be distributed under the terms of the GNU
.\" General Public License. <www.gnu.org/licenses/gpl.html>
.\"
.\" Process this file with groff -man -Tascii elinks.conf.5
.TH ELINKS.CONF 5 "ELinks configuration file" "$date_string" "ELinks configuration file" 

.SH NAME
elinks.conf \- ELinks configuration file

.SH DESCRIPTION
.PP
The
.B elinks.conf
file contains configuration information for ELinks.  It can be used to configure
the behaviour of ELinks in a wide variety of ways: protocol behaviour,
keybindings, colors used for rendering and for the user interface.
.PP
It is read at startup and saved only when requested. All options described in
this document can be fully configured from within ELinks so no editing of
elinks.conf is needed.
.PP
Note that MIME-related options used for specifying handlers of various MIME
types are NOT described in this document. Documentation for these options can be
found at the ELinks homepage. Keybindings can also be specified in elinks.conf.
This is described in the elinkskeys(5) man page.

.SH SYNTAX
.PP
The syntax of the configuration file is very simple. The elinks.conf file is a
free-form ASCII text file. The file may contain extra tabs and newlines for
formatting purposes. Keywords in the file are case-sensitive. Comments may be
placed anywhere within the file (except within quotes). Comments begin with the
# character and end at the end of the line.

.SH EXAMPLES
.PP
Some sample settings:
.IP
.nf
# Use asynchronous DNS resolver?
set connection.async_dns = 1
# horizontal text margin.
set document.browse.margin_width = 3
# Default document codepage.
set document.codepage.assume = "ISO-8859-1"
# User defined protocol handlers
set protocol.user.mailto.unix = "mutt %h -s \e\*(lq%s\e\*(rq"

.SH OPTIONS
__END__
}

elinks=

print_elinksconf_footer()
{
	version="$1"
	echo ".SH \"DOCUMENT INFO\""
	echo ".PP"
	echo "$script_info"
	echo "$dist_info"
	echo ".SH \"SEE ALSO\""
	echo ".BR elinks (1),"
	echo ".BR elinkskeys (5)"
}

print_elinksconf_description_end()
{
	if test -n "$parse_int_option";
	then
		echo ".PD"
		echo ".RE"
	fi
}

print_elinksconf_description_line()
{
	line="$1"
	number="$2"
	if test -n "$number";
	then
		if test "$parse_int_option" = "1";
		then
			echo ".RS"
			echo ".PD 0"
			parse_int_option=2
		fi

		echo ".TP"
		echo ".B $number"
	fi

	echo "$line"
}

print_elinksconf_option_tree()
{
	title="$1"
	path="$2"
	echo ".SS $title ($path)"
}

print_elinksconf_option_type()
{
	path="$1"
	typeid="$2"
	default="$3"
	echo ".TP"
	echo "\\f3$path\\f2 $typeid\\f1 ($default)"
}

# The main loop {{{1

# State variables
parse_description=
parse_int_option=
use_log=

$print_header

$command | $filter | while read line
do
	if test -n "$parse_description"
	then
		# If the line is empty it is our clue that
		# the desciption is over.
		if test -z "$line"
		then
			$print_description_end
			parse_description=
			parse_int_option=
			continue
		fi

		line=`echo "$line" | sed -e "s/[ ]*(DISABLED)//"`
		number=
		if test -n "$parse_int_option";
		then
			case "$line" in
				-[0-9]*)
					number="`echo $line | sed -e 's/\(-[0-9-]*\).*/\1/'`"
					line=`echo "$line" | sed -e "s/$number[ ]*//"`
				;;

				[0-9]*)
					number="`echo $line | sed -e 's/\([0-9-]*\).*/\1/'`"
					line=`echo "$line" | sed -e "s/$number[ ]*//"`
				;;
			esac
		fi

		$print_description_line "$line" "$number"
		continue
	fi

	case "$line" in
		Features:*)
		;;
		[A-Z]*:" ("*[a-z]*)
			parse_description=1
			title="`echo $line | sed -e 's/\([A-Z]*\):.*/\1/'`"
			path="`echo $line | sed -e 's/.*: (\([a-z_].*\))/\1/'`"
			$print_option_tree "$title" "$path"
		;;

		[a-z_-]*[.a-z_-]*)
			parse_description=1
			path="`echo $line | sed -e 's/\([a-z-][^ ]*\).*/\1/'`"
			typeid="`echo $line | sed -e 's/[ ]*[a-z-][^ ]* \([^ ]*\).*/\1/'`"
			default="`echo \"$line\" | sed -e 's/[^(]*(\(.*\))/\1/'`"
			$print_option_type "$path" "$typeid" "$default"
			if test "$typeid" = "<num>";
			then
				parse_int_option=1
			fi
		;;

		*)
		;;
	esac
done

$print_footer

# vim: tabstop=4 shiftwidth=4