lopsub.7.m4

   1 .\" groff -m man -Thtml <file>
   2 .\" See groff_www(7), groff(7) and groff_man(7)
   3
   4 .\" save current font, switch to monospace font, output, switch back
   5 .de MONO
   6 .nr mE \\n(.f
   7 .ft CW
   8 \\$*
   9 .ft \\n(mE
  10 ..
  11
  12 .\" make text on the same line appear alternately in monospace and roman
  13 .de MONO_ROMAN
  14 .  if \\n[.$] \{\
  15 .    ds an-result \&\f[CW]\\$1\f[R]\"
  16 .    shift
  17 .    while (\\n[.$] >= 2) \{\
  18 .      as an-result \/\\$1\f[CW]\,\\$2\f[R]\"
  19 .      shift 2
  20 .    \}
  21 .    if \\n[.$] .as an-result \/\\$1\"
  22 \\*[an-result]
  23 .    ft R
  24 .  \}
  25 ..
  26
  27 . if !'\*(.T'html' \
  28 . do ftr CW I
  29 . \}
  30
  31 .TH lopsub 7 "DATE()" GIT_VERSION()
  32 .SH NAME
  33 lopsub \- Long option parser for subcommands
  34
  35 .SH About
  36
  37 .B Lopsub
  38 is an open source library written in
  39 .B C
  40 which aims to ease the task of creating, documenting and parsing
  41 the options of Unix command line utilities. It is suitable for
  42 simple commands as well as complex command line utilities with many
  43 subcommands where each subcommand has its own set of options. Options
  44 and documentation are kept together in a single file which can be
  45 translated to
  46 .B C
  47 code (to be included in the application), or to a manual page.
  48 The library supports single-character short options and GNU-style
  49 long options. The public API is well documented and stable.
  50
  51 To make use of the library, the programmer provides a so-called
  52 .I suite file
  53 which describes the options of the application in an intuitive
  54 syntax. At build time the suite file is translated into
  55 .B C
  56 code by the
  57 .MONO lopsubgen
  58 utility which also ships with the
  59 .B lopsub
  60 package. The generated code defines an instance of an opaque
  61 .B C
  62 structure and exposes a reference to this structure which can be passed to
  63 the
  64 .I option parser
  65 at run time, together with the usual argument vector. The
  66 option parser is part of the
  67 .B lopsub
  68 .IR library ,
  69 so applications need to link with
  70 .MONO_ROMAN -llopsub .
  71 In addition to the option parser, the library offers many more
  72 features. For example, there is a function for merging two different
  73 .I parse results
  74 to generate an effective configuration. This is useful for applications
  75 which can be configured through command line options and via a
  76 config file.
  77
  78 The suite file can also be processed into roff format to create
  79 a manual page. Conversion into html can easily be performed with
  80 tools like
  81 .MONO grohtml
  82 (part of
  83 .BR "GNU roff" )
  84 or
  85 .MONO_ROMAN man2html .
  86
  87 .B Lopsub
  88 does not rely on the system's
  89 .MONO getopt()
  90 or
  91 .MONO getopt_long()
  92 functions of the C library and is thus portable across different
  93 flavors of Unix. It is known to work on
  94 .BR Linux ,
  95 .B NetBSD
  96 and
  97 .BR FreeBSD .
  98
  99 .SH License
 100 The
 101 .B lopsub library
 102 is licensed under the
 103 .B LGPLv3
 104 while the
 105 .MONO lopsubgen
 106 utility is licensed under the
 107 .BR GPLv3 .
 108 The examples and all code generated by the utilities, however, is
 109 licensed with a simple all-permissive license. You are free to do
 110 anything you like with the generated code, including incorporating
 111 it into or linking it with proprietary software.
 112
 113 .SH Installation
 114 Grab your copy with
 115 .IP
 116 .EX
 117 git clone git://git.tuebingen.mpg.de/lopsub.git
 118 .EE
 119 .PP
 120 Then build the package with
 121 .IP
 122 .EX
 123 make
 124 .EE
 125 .PP
 126 The suite parser and the config file parser of the
 127 .B lopsub
 128 library are both generated by running
 129 .MONO_ROMAN flex ,
 130 a tool for generating programs that perform pattern-matching on text. Hence the
 131 .B flex
 132 package must be installed for the build to succeed. Next, run
 133 .IP
 134 .EX
 135 sudo make install
 136 .EE
 137 .PP
 138 This will install the package in
 139 .MONO_ROMAN /usr/local .
 140 If you prefer to install as an unprivileged user in
 141 .MONO_ROMAN /somewhere/else ,
 142 run
 143 .IP
 144 .EX
 145 make PREFIX=/somewhere/else install
 146 .EE
 147 .PP
 148 instead. In this case, you need to specify
 149 .MONO -I/somewhere/else/include
 150 to compile the source files of your application and
 151 .MONO -L/somewhere/else/lib
 152 for linking. Alternatively, don't run
 153 .MONO make install
 154 at all and specify the path to the top level directory of the
 155 repository for both
 156 .MONO -I
 157 and
 158 .MONO_ROMAN -L .
 159
 160 .SH Quick Start
 161 Compile and run the minimal example included at the end of
 162 .UR ./lopsub-suite.5.html
 163 lopsub-suite(5)
 164 .UE .
 165 Examine
 166 .MONO lopsubex.c
 167 and
 168 .MONO lopsubex.suite
 169 in the source tree and run the
 170 .MONO lopsubex
 171 command.
 172
 173 .SH API documentation
 174 See
 175 .UR ./lopsub-api.html
 176 .UE .
 177 Alternatively, examine
 178 .MONO lopsub.h
 179 or
 180 .MONO_ROMAN lopsub.h.m4 .
 181
 182 .SH Contact
 183 Email:
 184 .MT maan@tuebingen.mpg.de
 185 Andre Noll
 186 .ME ,
 187 Homepage:
 188 .UR http://people.tuebingen.mpg.de/maan/
 189 .UE