1LGC(1) User Commands LGC(1)
2
6 lgc - translate and publish logiweb page
7
9 lgc [OPTION]... [SOURCE]
10
12 The Logiweb compiler translates Logiweb pages from source format to a
13 number of machine and human readable formats.
14 Pages may contain free text mixed with machine intelligible objects
16 like computer programs, testsuites, and formal proofs. The compiler can
17 compile embedded computer programs, run testsuites, and check the cor‐
18 rectness of formal proofs.
19 The compiler takes a source file as input and produces a 'vector', a
21 'rack', and a 'rendering' as output. Source, vector, rack, and render‐
22 ing all represent the same Logiweb page. The source format is suited
23 for authoring of Logiweb pages using an ordinary text editor. The vec‐
24 tor is a condensed representation suited for transmission over the
25 Internet. The rack is a comprehensive representation suited for storing
26 on a local disk. The rendering is a human readable representation
27 suited for reading in a web browser.
28 The compiler assigns a world-wide unique 'reference' to each page it
30 translates. A reference comprises around 30 bytes. Having the reference
31 of a page one may retrieve the vector of the page via an untrusted net‐
32 work from an untrusted repository. This is so since the reference con‐
33 tains a RIPEMD-160 hash code which allows to verify the authenticity of
34 the page.
35 References are expressed in 'mixed endian hexadecimal': Each byte is
37 written with the most significant hex digit first, bytes are given in
38 network byte order, and capital letters are used for the hex digits A
39 to F.
40
42 -h, --help
43 Print help on frequently used options.
44 -H, --help2
46 Print help on less frequent options.
47 --help3
49 Print help on configuration options.
50 -l location, --link=location
52 Store a symbolic link at the given location to the rendering
53 output. The rightmost colon (if any) in the location is replaced
54 by the name of the source file (without the .lgs extension). An
55 opening tilde (if any) is replaced by $HOME. The default values
56 are ~/.logiweb/name/:/ and : so that two links are produced by
57 default. See LIST OPTIONS below on how to give this option more
58 than once.
59 --license
61 Print the license (i.e. GNU/GPL) of the lgc compiler.
62 -n location, --namepath=location
64 Read pages given by name from given location. The rightmost
65 colon (if any) in the location is replaced by the given name.
66 Such names may be given in the source file being translated,
67 c.f. lgc(5). An opening tilde in the location (if any) is
68 replaced by $HOME. The default value of NAMEPATH is ~/.logi‐
69 web/name/:/rack.lgr. See LIST OPTIONS below on how to give this
70 option more than once.
71 -o name, --option=name
73 Process all configuration files, environment variables, and com‐
74 mand line options. Then print the value of the option with the
75 given name.
76 --options
78 Like -o above, but prints all options.
79 -p location, --path location
81 Read referenced pages from given location. The rightmost colon
82 (if any) in the location is replaced by the reference of the
83 page expressed in mixed endian hexadecimal. Such references may
84 come from the source file, c.f. lgc(5), or may be used for
85 locating transitively referenced pages, i.e. pages referenced
86 from referenced pages. An opening tilde in the location (if any)
87 is replaced by $HOME. The default value of PATH is ~/.logi‐
88 web/logiweb/:/rack.lgr. See LIST OPTIONS below on how to give
89 this option more than once.
90 -r location, --rendering=location
92 Store rendering at the given location. The rightmost colon (if
93 any) in the location is replaced by the reference of the page.
94 An opening tilde (if any) is replaced by $HOME. The default
95 value is ~/.logiweb/logiweb/:/. The vector and rack produced by
96 lgc are stored as vector.lgw and rack.lgr at the given location.
97 -s file, --siteconfig=file
99 Read options from given file, c.f. CONFIGURATION FILES below. An
100 opening tilde (if any) is replaced by $HOME. The default value
101 is /etc/logiweb/lgc.conf.
102 -u file, --userconfig=file
104 Read options from given file, c.f. CONFIGURATION FILES below. An
105 opening tilde (if any) is replaced by $HOME. The default value
106 is ~/.logiweb/lgc.conf.
107 --source=file
109 Translate given file. 'lgc --source=X' is like 'lgc X'.
110 -v verbosity, --verbose=verbosity
112 Set verbosity to given level. Levels are: 1. Print error mes‐
113 sages. 2. Also print warning message. 3. Also print progress
114 messages. 4. Print more progress messages. 5. Print debugging
115 information. Level 0 is reserved for silence. Default level is
116 3.
117 --version
119 Print the version of the lgc compiler.
120
122 While it is possible to give the following options on the command line,
123 they are intended to be used in configuration files.
124 --leap=leapspec
126 Tell lgc that a leap second occurred or will occur at the given
127 point in time. A leapspec has format
128 GRD-<year>-<month>-<day>[+1|-1].
130 The year, month, and day are given as a Gregorian date. Days go
132 from UTC midnight to UTC midnight. The month and day have two
133 digits. The year has four until year 9999. A leapspec indicates
134 that the length of the given day is altered by the given amount
135 (+1 second or -1 second). The leap affects the last minute of
136 the last hour of the given UTC day. See LIST OPTIONS below on
137 how to give this option more than once.
138 --newline=value
140 Tell lgc what host newline convention to use. Possible values
141 are CR, LF, CRLF, or LFCR. For the sake of portability, Logiweb
142 always uses LF internally.
143 --script=headline
145 Tell lgc what line to start with when emitting an executable.
146 Default is '#!/usr/bin/lgwam script'
147
149 The value of each option is a list of strings. Each command line option
150 transforms the value of some option. The available transformations are:
151 (1) Discard the current value and set the given option to a one element
152 list containing the given string. (2) Add the given string in front of
153 the given option. (3) Add the given string at the end of the given
154 option. (4) Set the given option to the empty list. These four possi‐
155 bilities are illustrated in the following using the PATH variable as an
156 example.
157 -p xyzzy, --path=xyzzy
159 Set PATH to a one element list containing xyzzy.
160 +p foo, --path+foo
162 Add foo in front of PATH. If given after the option above, the
163 PATH now has value foo;xyzzy.
164 ++p bar, --path++bar
166 Add bar at end of PATH. If given after the options above, the
167 PATH now has value foo;xyzzy;bar.
168 --path Set path to the empty list
170 Options like HELP, VERSION, and so on have default value 'no'. Such
172 options take effect when they differ from 'no'. As an example, -h
173 translates to --help which sets HELP to the empty list which differs
174 from 'no'.
175 Options like SITECONFIG, USERCONFIG, and RENDERING only use the first
177 string in the list. As an example, '-s file' translates to '--sitecon‐
178 fig=file' which sets the first (and only) element of SITECONFIG to
179 file.
180 A source file foo given on the command line translate to --source=foo.
182 The compiler only uses the first string of the SOURCE option.
183 The compiler processes the command line left to right. Long options are
185 case insensitive. Short options are case sensitive. Short options are
186 translated to long options before processing.
187
189 The compiler processes options from the following sources in the order
190 given.
191 Compiled in defaults
193 These are the default values which can only be changed by recom‐
194 piling lgc.
195 Script defaults
197 The compiler is itself a Logiweb script and may look like this:
198 > more /usr/bin/lgc
200 #!/usr/bin/lgwam script
201 string
202 015F43BE4A17DAD915936B7A773154A80946AEC82EFBEECDA4A7D7B80806
203 lgc
204 execute
205 siteconfig=/etc/logiweb/lgc.conf
206 The first five lines identify the lgc compiler. The remaining
208 lines define options exactly like long options do on the command
209 line except that the leading two hyphens are omitted. Blank
210 lines and lines starting with a hashmark (#) are ignored. Lines
211 may be ended by an arbitrary sequence of CR and LF characters.
212 Site configuration file
214 The site configuration file is treated like the option part of
215 the script.
216 User configuration file
218 The user configuration file is treated like the site configura‐
219 tion file. The only difference between the two is that the site
220 file is processed before the user file.
221 Environment variables
223 Environment options like LGC_FOO=xyzzy are treated as
224 --FOO=xyzzy. Environment options can only be used for setting
225 options to one-element lists of strings. As a special case, the
226 environment variable HOME=xyzzy is treated as --HOME=xyzzy.
227 Command line options
229 These were treated in great detail earlier in this man page.
230 Options from the six sources above are treated as one long list of
232 option transformations. As an example, --path+foo on the command line
233 adds foo in front of whatever the five other sources have defined PATH
234 to be.
235 The compiler reads options once but process them three times: First for
237 finding the value of SITECONFIG ignoring the site and user configura‐
238 tion files. Second for finding the value of USERCONFIG ignoring the
239 user configuration file. And finally for finding the value of all the
240 other options.
241 The compiler does not restrict the set of possible options to those it
243 knows itself. Hence, 'lgc --foo=bar source' will define the FOO option
244 to equal 'bar'. Such user defined options can be picked up by user
245 defined rendering functions in the source and may affect the outcome of
246 rendering. Note that if the rendering is put on WWW this may expose the
247 options used to the outside world. This includes the environment vari‐
248 able HOME and variables starting with LGC_. Use 'lgc --options' to see
249 what might get exposed to the outside world.
250
252 When looking up a page by name or reference, lgc considers the loca‐
253 tions in NAMEPATH and PATH, respectively, one at a time as follows.
254 (1) If the item does not start with "file:" or "http:", then "file:" is
256 prepended.
257 (2) The item is divided in scheme and contents at the leftmost colon
259 character. Hence, the scheme is either "file" or "http".
260 (3) If the scheme is "file" and the contents starts with a tilde, then
262 the tilde is replaced by the value of $HOME.
263 (4) The rightmost colon character (if any) is replaced by the name (for
265 NAMEPATH) or reference (for PATH) of the page. The reference is
266 expressed in mixed endian hexadecimal.
267 (5) The page is looked up as a file or using http depending on the
269 scheme. A page with extension .lgr is treated as a Logiweb rack. A page
270 with extension .lgw is treated as a Logiweb vector. A page with exten‐
271 sion .lgu is treated as an URL which points at the page to be fetched.
272 That URL is supposed to have extension .lgr or .lgw or .lgu. The .lgu
273 extension is intended for future uses involving CGI scripts.
274 As an example, if the item is ~/.logiweb/cache/:/page.lgr and the ref‐
276 erenced page has reference 01AB then .logiweb/cache/01AB/page.lgr under
277 the users home catalogue is retrieved and is interpretted as a Logiweb
278 rack.
279
281 The site configuration file typically resides in /etc/logiweb/lgc.conf.
282 It is considered to be blank if it does not exist.
283 The user configuration file typically resides in ~/.logiweb/lgc.conf.
285 It is considered to be blank if it does not exist.
286 Example source files typically reside in /usr/share/doc/logiweb/exam‐
288 ples.
289 Source files should have extension .lgs (this may become mandatory in
291 the future).
292 Links to rendering output typically have no extension.
294 Logiweb vectors (compact representations of Logiweb pages suited for
296 transmission over the internet) have extension .lgw.
297 Logiweb racks (precompiled representations of Logiweb pages suited for
299 fast loading) have extension .lgr.
300 Logiweb pointers (page references in mixed endian hexadecimal) have
302 extension .lgp.
303 Logiweb URL indirections have extension .lgu.
305
307 For each long option there is an associated environment variable, c.f.
308 CONFIGURATION FILES above. Furthermore, lgc may use the HOME environ‐
309 ment variable.
310
312 The HOME environment variable and environment variables starting with
313 LGC_ may get exposed if rendering output is made available via WWW.
314 All transitively referenced pages are rendered locally. Local rendering
316 may involve invokation of latex, bibtex, makeindex, and dvipdfm. Local
317 rendering should occur in a chroot jail, but this has not yet been
318 implemented. Thus: only reference trusted pages.
319 All pages may define executable code. Executables end up under the ren‐
321 dering directory. Such executables can do anything if they are invoked.
322 The lgc compiler never itself invokes an executable, but an attacker
323 could either persuade or fool you to run it or could exploit security
324 holes in latex to do so. Thus: only reference trusted pages.
325 When loading a Logiweb vector, lgc uses the RIPEMD-160 hash function to
327 verify the authenticity of the received vector. lgc makes no check of
328 racks. Thus, only load racks from trusted places (typically your own
329 harddisk and nowhere else).
330 Feel free to include locations like http://untrusted.com/:/vector.lgw
332 in PATH. RIPEMD-160 will protect you. But never include .lgr references
333 to untrusted places and never include references to untrusted places in
334 NAMEPATH.
335
337 Klaus Grue, http://logiweb.eu/
338
340 lgwam(1), lgc(5), lgc.conf(5), logiweb(5)
341Logiweb JULY 2009 LGC(1)