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