lopsub.7: Add NAME section.
[lopsub.git] / 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