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 elinkskeys (5)"
 234 }
 235
 236 print_elinksconf_description_end()
 237 {
 238         if test -n "$parse_int_option";
 239         then
 240                 echo ".PD"
 241                 echo ".RE"
 242         fi
 243 }
 244
 245 print_elinksconf_description_line()
 246 {
 247         line="$1"
 248         number="$2"
 249         if test -n "$number";
 250         then
 251                 if test "$parse_int_option" = "1";
 252                 then
 253                         echo ".RS"
 254                         echo ".PD 0"
 255                         parse_int_option=2
 256                 fi
 257
 258                 echo ".TP"
 259                 echo ".B $number"
 260         fi
 261
 262         echo "$line"
 263 }
 264
 265 print_elinksconf_option_tree()
 266 {
 267         title="$1"
 268         path="$2"
 269         echo ".SS $title ($path)"
 270 }
 271
 272 print_elinksconf_option_type()
 273 {
 274         path="$1"
 275         typeid="$2"
 276         default="$3"
 277         echo ".TP"
 278         echo "\\f3$path\\f2 $typeid\\f1 ($default)"
 279 }
 280
 281 # The main loop {{{1
 282
 283 # State variables
 284 parse_description=
 285 parse_int_option=
 286 use_log=
 287
 288 $print_header
 289
 290 $command | $filter | while read line
 291 do
 292         if test -n "$parse_description"
 293         then
 294                 # If the line is empty it is our clue that
 295                 # the desciption is over.
 296                 if test -z "$line"
 297                 then
 298                         $print_description_end
 299                         parse_description=
 300                         parse_int_option=
 301                         continue
 302                 fi
 303
 304                 line=`echo "$line" | sed -e "s/[ ]*(DISABLED)//"`
 305                 number=
 306                 if test -n "$parse_int_option";
 307                 then
 308                         case "$line" in
 309                                 -[0-9]*)
 310                                         number="`echo $line | sed -e 's/\(-[0-9-]*\).*/\1/'`"
 311                                         line=`echo "$line" | sed -e "s/$number[ ]*//"`
 312                                 ;;
 313
 314                                 [0-9]*)
 315                                         number="`echo $line | sed -e 's/\([0-9-]*\).*/\1/'`"
 316                                         line=`echo "$line" | sed -e "s/$number[ ]*//"`
 317                                 ;;
 318                         esac
 319                 fi
 320
 321                 $print_description_line "$line" "$number"
 322                 continue
 323         fi
 324
 325         case "$line" in
 326                 Features:*)
 327                 ;;
 328                 [A-Z]*:" ("*[a-z]*)
 329                         parse_description=1
 330                         title="`echo $line | sed -e 's/\([A-Z]*\):.*/\1/'`"
 331                         path="`echo $line | sed -e 's/.*: (\([a-z_].*\))/\1/'`"
 332                         $print_option_tree "$title" "$path"
 333                 ;;
 334
 335                 [a-z_-]*[.a-z_-]*)
 336                         parse_description=1
 337                         path="`echo $line | sed -e 's/\([a-z-][^ ]*\).*/\1/'`"
 338                         typeid="`echo $line | sed -e 's/[ ]*[a-z-][^ ]* \([^ ]*\).*/\1/'`"
 339                         default="`echo \"$line\" | sed -e 's/[^(]*(\(.*\))/\1/'`"
 340                         $print_option_type "$path" "$typeid" "$default"
 341                         if test "$typeid" = "<num>";
 342                         then
 343                                 parse_int_option=1
 344                         fi
 345                 ;;
 346
 347                 *)
 348                 ;;
 349         esac
 350 done
 351
 352 $print_footer
 353
 354 # vim: tabstop=4 shiftwidth=4