build: Compress man pages.
[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 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