doc/tools/help2doc

   1 #!/bin/sh
   2 #
   3 #
   4 # Script used to generate doc/book/config/cmdoptions.xml
   5 # and hopefully other in the future.
   6
   7 # Updated by option handlind via --elinks=path/to/elinks option
   8 elinks="elinks"
   9
  10 # Utility functions {{{1
  11
  12 usage()
  13 {
  14         msg="$1"
  15         echo "$msg" >&2
  16         echo "`basename $0` ($script_version)" >&2
  17         echo "Usage: $0 [ --cmdoptions | --elinksconf | - | --elinks=path/to/elinks ]" >&2
  18         cat >&2 <<END_OF_USAGE
  19         --cmdoptions    Print asciidoc markup with summary of the command options
  20         --elinksconf    Print the elinks.conf.5 manpage
  21         -               Read option info (elinks --config-help) from stdin
  22         --elinks=path   Use the elinks program with the given path
  23 END_OF_USAGE
  24         exit -1
  25 }
  26
  27 # Option handling {{{1
  28
  29 command=
  30 filter=cat
  31 prev_option=
  32
  33 for option
  34 do
  35         # If the previous option needs an argument, assign it.
  36         if test -n "$prev_option"; then
  37                 eval "$prev_option=\$option"
  38                 prev_option=
  39                 continue
  40         fi
  41
  42         case "$option" in
  43                 --cmdoptions)
  44                         command="$elinks -long-help"
  45                         filter="sed 0,/^Options:/d"
  46                         backend="cmdoptions"
  47                 ;;
  48                 --elinksconf)
  49                         command="$elinks -config-help"
  50                         filter="sed 0,/^Configuration/d"
  51                         backend="elinksconf"
  52                 ;;
  53                 -)
  54                         command="cat /dev/stdin"
  55                 ;;
  56                 --elinks=*)
  57                         elinks="`echo $option | sed -e 's/.*=//'`"
  58                 ;;
  59                 *)
  60                         usage "Unknown option"
  61                 ;;
  62         esac
  63 done
  64
  65 if test -z "$backend";
  66 then
  67         usage "No backend defined"
  68 fi
  69
  70 date_string=`date -I`
  71 script_version=`echo "\\$Revision: 1.19 $" | sed -e 's/\\$\(.*\) \\$/\1/'`
  72 elinks_version="`$elinks -version | head -n 1 | sed -e 's/ELinks \([0-9][^ ]*\).*/\1/'`"
  73 script_info="Generated by `basename $0` ($script_version) on $date_string"
  74 script_info="$script_info using output from ELinks version $elinks_version."
  75 dist_info="`basename $0` is distributed with ELinks under the terms of the GPL."
  76
  77 # Backends {{{1
  78
  79 print_header="print_${backend}_header"
  80 print_footer="print_${backend}_footer"
  81 print_description_end="print_${backend}_description_end"
  82 print_description_line="print_${backend}_description_line"
  83 print_option_tree="print_${backend}_option_tree"
  84 print_option_type="print_${backend}_option_type"
  85
  86 # --cmdoptions backend {{{2
  87
  88 print_cmdoptions_header()
  89 {
  90         echo
  91 }
  92
  93 print_cmdoptions_footer()
  94 {
  95         echo
  96 }
  97
  98 print_cmdoptions_description_end()
  99 {
 100         echo
 101 }
 102
 103 print_cmdoptions_description_line()
 104 {
 105         line="$1"
 106         number="$2"
 107
 108         case "$line" in
 109         -eval*)
 110                 echo
 111                 ;;
 112         *)
 113                 line="$(echo $line | sed 's,\(-touch-files\|-no-connect\|-session-ring\|-dump\|-default-mime-type\|text/html\|~/\.elinks\),\`\1\`,g')"
 114                 line=$(echo $line | sed "s,'\([^']*\)',\\\'\1\\\',")
 115                 line=$(echo $line | sed "s,ELinks,'ELinks',g")
 116                 line=$(echo $line | sed "s,HOME,'HOME',g")
 117                 line="$(echo $line | sed 's/^\([a-zA-Z]*([^)]*)\).*:/- \`\1\`:/')"
 118
 119                 if test -n "$number";
 120                 then
 121                         echo -n "       - $number:"
 122                 fi
 123         esac
 124         echo "  $line"
 125 }
 126
 127 print_cmdoptions_option_tree()
 128 {
 129         parse_description=
 130 }
 131
 132 print_cmdoptions_option_type()
 133 {
 134         path="$1"
 135         typeid="$2"
 136         default="$3"
 137         typestring="$path"
 138         if test -n "$typeid" && test "$typeid" != "$path";
 139         then
 140                 if test "$typeid" = "(alias";
 141                 then
 142                         typestring="$typestring ($default)"
 143                         default=
 144                 else
 145                         typestring="$typestring $typeid"
 146                 fi
 147         fi
 148         if test -n "$default" && test "$default" != "$path";
 149         then
 150                 typestring="$typestring ($default)"
 151         fi
 152         if test "$default" = "-?, -h, -help";
 153         then
 154                 typestring="$default"
 155         fi
 156         echo "$typestring::"
 157 }
 158
 159 # --elinksconf backend {{{2
 160
 161 print_elinksconf_header()
 162 {
 163         cat << __END__
 164 .\" elinks.conf.5
 165 .\"
 166 .\" $script_info
 167 .\"
 168 .\" Copyleft (c) 2002-2004 The ELinks project
 169 .\"
 170 .\" This file may be distributed under the terms of the GNU
 171 .\" General Public License. <www.gnu.org/licenses/gpl.html>
 172 .\"
 173 .\" Process this file with groff -man -Tascii elinks.conf.5
 174 .TH ELINKS.CONF 5 "ELinks configuration file" "$date_string" "ELinks configuration file"
 175
 176 .SH NAME
 177 elinks.conf \- ELinks configuration file
 178
 179 .SH DESCRIPTION
 180 .PP
 181 The
 182 .B elinks.conf
 183 file contains configuration information for ELinks.  It can be used to configure
 184 the behaviour of ELinks in a wide variety of ways: protocol behaviour,
 185 keybindings, colors used for rendering and for the user interface.
 186 .PP
 187 It is read at startup and saved only when requested. All options described in
 188 this document can be fully configured from within ELinks so no editing of
 189 elinks.conf is needed.
 190 .PP
 191 Note that MIME-related options used for specifying handlers of various MIME
 192 types are NOT described in this document. Documentation for these options can be
 193 found at the ELinks homepage. Keybindings can also be specified in elinks.conf.
 194 This is described in the elinkskeys(5) man page.
 195
 196 .SH SYNTAX
 197 .PP
 198 The syntax of the configuration file is very simple. The elinks.conf file is a
 199 free-form ASCII text file. The file may contain extra tabs and newlines for
 200 formatting purposes. Keywords in the file are case-sensitive. Comments may be
 201 placed anywhere within the file (except within quotes). Comments begin with the
 202 # character and end at the end of the line.
 203
 204 .SH EXAMPLES
 205 .PP
 206 Some sample settings:
 207 .IP
 208 .nf
 209 # Use asynchronous DNS resolver?
 210 set connection.async_dns = 1
 211 # horizontal text margin.
 212 set document.browse.margin_width = 3
 213 # Default document codepage.
 214 set document.codepage.assume = "ISO-8859-1"
 215 # User defined protocol handlers
 216 set protocol.user.mailto.unix = "mutt %h -s \e\*(lq%s\e\*(rq"
 217
 218 .SH OPTIONS
 219 __END__
 220 }
 221
 222 elinks=
 223
 224 print_elinksconf_footer()
 225 {
 226         version="$1"
 227         echo ".SH \"DOCUMENT INFO\""
 228         echo ".PP"
 229         echo "$script_info"
 230         echo "$dist_info"
 231         echo ".SH \"SEE ALSO\""
 232         echo ".BR elinks (1),"
 233         echo ".BR elinksmanual (1),"
 234         echo ".BR elinkskeys (5)"
 235 }
 236
 237 print_elinksconf_description_end()
 238 {
 239         if test -n "$parse_int_option";
 240         then
 241                 echo ".PD"
 242                 echo ".RE"
 243         fi
 244 }
 245
 246 print_elinksconf_description_line()
 247 {
 248         line="$1"
 249         number="$2"
 250         if test -n "$number";
 251         then
 252                 if test "$parse_int_option" = "1";
 253                 then
 254                         echo ".RS"
 255                         echo ".PD 0"
 256                         parse_int_option=2
 257                 fi
 258
 259                 echo ".TP"
 260                 echo ".B $number"
 261         fi
 262
 263         echo "$line"
 264 }
 265
 266 print_elinksconf_option_tree()
 267 {
 268         title="$1"
 269         path="$2"
 270         echo ".SS $title ($path)"
 271 }
 272
 273 print_elinksconf_option_type()
 274 {
 275         path="$1"
 276         typeid="$2"
 277         default="$3"
 278         echo ".TP"
 279         echo "\\f3$path\\f2 $typeid\\f1 ($default)"
 280 }
 281
 282 # The main loop {{{1
 283
 284 # State variables
 285 parse_description=
 286 parse_int_option=
 287 use_log=
 288
 289 $print_header
 290
 291 $command | $filter | while read line
 292 do
 293         if test -n "$parse_description"
 294         then
 295                 # If the line is empty it is our clue that
 296                 # the desciption is over.
 297                 if test -z "$line"
 298                 then
 299                         $print_description_end
 300                         parse_description=
 301                         parse_int_option=
 302                         continue
 303                 fi
 304
 305                 line=`echo "$line" | sed -e "s/[ ]*(DISABLED)//"`
 306                 number=
 307                 if test -n "$parse_int_option";
 308                 then
 309                         case "$line" in
 310                                 -[0-9]*)
 311                                         number="`echo $line | sed -e 's/\(-[0-9-]*\).*/\1/'`"
 312                                         line=`echo "$line" | sed -e "s/$number[ ]*//"`
 313                                 ;;
 314
 315                                 [0-9]*)
 316                                         number="`echo $line | sed -e 's/\([0-9-]*\).*/\1/'`"
 317                                         line=`echo "$line" | sed -e "s/$number[ ]*//"`
 318                                 ;;
 319                         esac
 320                 fi
 321
 322                 $print_description_line "$line" "$number"
 323                 continue
 324         fi
 325
 326         case "$line" in
 327                 Features:*)
 328                 ;;
 329                 [A-Z]*:" ("*[a-z]*)
 330                         parse_description=1
 331                         title="`echo $line | sed -e 's/\([A-Z]*\):.*/\1/'`"
 332                         path="`echo $line | sed -e 's/.*: (\([a-z_].*\))/\1/'`"
 333                         $print_option_tree "$title" "$path"
 334                 ;;
 335
 336                 [a-z_-]*[.a-z_-]*)
 337                         parse_description=1
 338                         path="`echo $line | sed -e 's/\([a-z-][^ ]*\).*/\1/'`"
 339                         typeid="`echo $line | sed -e 's/[ ]*[a-z-][^ ]* \([^ ]*\).*/\1/'`"
 340                         default="`echo \"$line\" | sed -e 's/[^(]*(\(.*\))/\1/'`"
 341                         $print_option_type "$path" "$typeid" "$default"
 342                         if test "$typeid" = "<num>";
 343                         then
 344                                 parse_int_option=1
 345                         fi
 346                 ;;
 347
 348                 *)
 349                 ;;
 350         esac
 351 done
 352
 353 $print_footer
 354
 355 # vim: tabstop=4 shiftwidth=4