Table of Contents
pyk - format and publish logiweb page
pyk --|filename [bin=dirname]
[cache=dirname] [conf=filename] [dest=string] [destmirror=string] [destresubmit=string]
[destsubmit=string] [desttemp=string] [diagnose=Boolean] [dump=filename]
[dumpconf=filename] [exec=Boolean] [filter=list] [gc=Boolean] [gcroots=list]
[grammar=integer] [header=warn|nowarn|suggest|html] [help=Boolean] [httphost=internet-address]
[iterations=cardinal] [jail=Boolean] [keyword=list] [keyphrase=list] [level=parse|compile|diagnose|body|codex|all|submit]
[lgw=url] [link=string] [linkresubmit=string] [linksubmit=string] [linktemp=string]
[localconf=filename] [machine=string] [mirror=string] [name=string] [optidump=filename]
[option=Boolean] [optionstr=name] [optionval=name] [org=string] [pane1=string]
[pane2=string] [patience=duration] [parenthesize=Boolean] [post=CGI-string]
[pyk=filename] [quit=Boolean] [relayurl=url] [renderers=list] [roots=association-list]
[spy=Boolean] [spydepth=integer] [spylength=integer] [src=url] [test=Boolean]
[tracecompile=list] [udphost=internet-address] [udpport=port-number] [unfit=Boolean]
[uninstall=Boolean] [url=url] [userconf=filename] [varbin=directory] [varconf=string]
[varcreate=string] [varhome=string] [varhttp=string]
[varlgwping=string] [varlgwrelay=string] [varlib=string] [varlogiweb=string]
[varman=string] [varpyk=string] [varrelay=string] [varscript=string] [varsubmit=string]
[verbose=0|1|2] [version=Boolean] [wikisubmit=string]
Pyk compiler translates pyk source files into Logiweb pages, tests the
pages for correctness, and renders the pages. For the format of pyk source
files see pyk(5)
Pyk is controlled by options. Pyk reads options from the
following locations listed in order of priority: the commmand line, environment
variables, a local configuration file, a user configuration file, a site
configuration file, and compiled in defaults. Pyk may also get options from
further sources, c.f. the 'post' and 'quit' options in the OPTIONS section. To
see the values of all options from all sources, including compiled in options,
issue the command 'logiweb -- -option'.
On the command line, options can be
given on the form 'OPTION=VALUE', '--OPTION VALUE' or '-OPTION VALUE'. Hence, 'level=submit',
'--level submit', and '-level submit' all set the 'level' option to 'submit'.
can be set to the empty string by the forms 'OPTION=', '--noOPTION', and '-noOPTION'.
As an example, 'quit=', '--noquit', and '-noquit' all set the 'quit' option to the
empty string. The 'quit' option is a Boolean, and the empty string happens
to be one of several strings that represent falsehood. For a description
of Booleans and of other types see logiweb.conf(5)
Options can be set to
'yes' by the forms 'OPTION=yes', '--OPTION', and '-OPTION'. As an example, 'quit=yes',
'--quit', and '-quit' (with no value after '--quit' and '-quit') all set the 'quit' option
to 'yes'. 'yes' happens to be one of several strings that represent truth.
a file name without a preceeding option as in 'pyk MYFILE' is equivalent
to 'pyk pyk=MYFILE'.
The first argument of pyk, if any, should be -- or should
be one which does not begin with a hyphen. Hence, e.g. 'pyk MYFILE' and 'pyk
-- -help' and 'pyk help=yes' are legal whereas e.g. 'pyk -help' gives the mystifying
error message 'GNU CLISP: invalid option' which is unrelated to Logiweb. It
is always safe to start the the argument list with --. As an example, 'pyk
myfile' and 'pyk -- myfile' give the same result. The initial -- is mandatory when
-noquit occurs later in the option list in the sense that -noquit behaves
strange without an initial --.
- Directory for storing
the binaries defined by the 'executables' aspect of a page. When empty (the
default) no binaries are stored.
- Store compiled versions of
all referenced Logiweb pages in the given directory. When loading a Logiweb
page, first consult the directory for a compiled version. This feature is
disabled if dirname is empty. Loading of cached pages is much faster than
loading of non-cached pages but still takes time. The time taken to load
a page can be eliminated using the dump option. Use the dump option to preload
very big pages that are used very often; rely on the cache for other pages.
- Name of main configuration file, e.g. /etc/logiweb/logiweb.conf.
See also the FILES section below.
- The destination of published
output relative to the publication directory (the location given by the
'url' option described later). The string may contain the following variables:
$PYK$, $PAGE$, $DATE$, $16$, $32$, and $64$. $PYK$ is the name of the pyk
file. $PAGE$ is the pyk name of the page symbol. $DATE$ is the time stamp
associated with the document and looks like this: GRD-2006-03-21-UTC-08-05-41-374485.
$16$ is the reference of the page in mixed endian hexadecimal. $32$ is the
reference of the page in little endian base 32. $64$ is the reference of
the document in little endian base 64. As an example, if the pyk name of
a page is 'base' and if dest=$PAGE$/xxx$DATE$ then the page is published
in a directory named something like base/xxxGRD-2006-03-21-UTC-08-05-41-374485.
The 'dest' option is required to define two directory levels separated by
- Destination of mirrored pages, c.f. the 'mirror'
option. For such pages, $PYK does not make sense because the name of the
pyk source file is unknown. For the difference between 'mirrorred' and 'resubmitted'
pages, see the 'mirror' option.
- The default value for
the 'dest' option above when the page being published is a resubmission of
a .lgw file generated elsewhere, c.f. the 'lgw' option. For such pages, $PYK
does not make sense because the name of the pyk source file is unknown.
For the difference between 'mirrorred' and 'resubmitted' pages, see the 'mirror'
- The default value for the 'dest' option above when
the page being published is a submission, i.e. not a resubmission and the
'level' option is set to 'submit'.
- The default value for the
'dest' option above when the page being published is a temporary one, i.e.
not a resubmission and the 'level' option is set to something different from
- When yes: print pyk version of diagnose. Prints
entire diagnose by default. Output may be limited by the spydepth and spylength
- Only read the PAGE and BIBLIOGRAPHY sections of the
source, then load all transitively referenced pages, then dump an executable
to the given file and exit. The executable is a new command whose behaviour
is identical to the pyk command except that all transitively referenced
pages are preloaded so that the new command does not spend any time loading
- Set the compiled in default of the 'conf' option
to the given file name when dumping an executable using the 'dump' option.
If dumpconf is the empty string then the compiled in default of the 'conf'
option is not changed.
- If the 'execute' aspect of the page symbol
of a Logiweb page is defined, then the associated Logiweb machine is executed
when the compilation ends. One may combine exec=yes with machine=filename
in which case the machine is both dumped and executed.
input processing to be done on pyk files. If empty (the default) then the
filter used is ',UTF-8,newline,10,space,9,ignore,13' which states that character
10 (line feed) is a line separator, character 9 (tabulation) is a space
character, and character 13 (carriage return) is ignored.
The filter option
is given as a list (c.f. logiweb.conf(5)
). The first element must be a filter
name. At the time of writing, the filter names below are valid. Names on
the same line are synonyms. Names are case insensitive.
ucs-2 unicode-16 unicode-16-big-endian
ucs-4 unicode-32 unicode-32-big-endian
iso-8859-1 8859-1 latin1 west
iso-8859-2 8859-2 latin2 east
iso-8859-3 8859-3 latin3 south
iso-8859-4 8859-4 latin4 north
iso-8859-5 8859-5 cyrillic
iso-8859-6 8859-6 arabic
iso-8859-7 8859-7 greek
iso-8859-8 8859-8 hebrew
iso-8859-9 8859-9 latin5 turkish
iso-8859-10 8859-10 latin6 nordic
iso-8859-11 8859-11 thai
iso-8859-13 8859-13 latin7 baltic
iso-8859-14 8859-14 latin8 celtic
iso-8859-15 8859-15 latin9 latin0
iso-8859-16 8859-16 latin10 southeast
binary (only for use in include directives)
bs (only for use in include directives)
Internally, Logiweb uses 'Logiweb-UTF-8' which differs from UTF-8 in two respects:
(1) Code 10 and only code 10 is used as newline separator. (2) The codes
0..9 and 11..31 are illegal.
The filter name may be followed by modifiers where
a modifier consists of a keyword and a value. The keywords may be 'newline',
'space', and 'ignore'. The associated values are UTF-8 byte values which should
be translated to Logiweb newline (code 10), Logiweb space (code 32) or
be ignored, respectively. As an example, ',latin1,newline,10,space,9,ignore,13'
translates an input file in latin1 to UTF-8 and then translates character
10 (newline) to a newline, character 9 (tab) to a space, and ignores character
13 (return). Pyk halts with an error if a character with code 0..8, 11, 12,
or 14..31 occurs in input. The codes 0..31, including code 10, are illegal in
input unless otherwise specified. The default filter ',UTF-8,newline,10,space,9,ignore,13'
permits code 9, 10, and 13 in input. Code 0 is always illegal in input and
cannot be mapped to space or newline or be ignored.
At the time of writing,
the input filter does no Unicode normalization and passes accents unmodified.
As an example, the input filter does no translation between a precomposes
German A umlaut (U+00C4) and a latin A (U+0041) followed by a combining
diaeresis (U+0308). If normalization is added later, it should probably
be done after translation to UTF-8. The 'space' modifier is intended for mapping
e.g. tabulation characters to spaces. It is useless for normalization of Unicode
The special encodings 'binary' and 'bs' (binary string) are for use
in include directives only. The 'binary' encoding reads a file and translates
each three input bytes to four BASE64 characters. The 'bs' encoding does the
same but also prefixes the bytes with ""/ and suffixes them by " such that
they become a pyk binary string.
- When true: perform garbage collection
of Logiweb pages. The pyk compiler prints a list of which directories it
intends to remove and asks for confirmation from the user. The garbage collector
only removes pages under the users publication directory, i.e. the directory
pointed out by the 'url' option.
- The garbage collector
does not touch directories younger than 'gcpatience'. This gives a limited
protection against race conditions in multi user environments. Note, however,
that if two users use the same publication directory, if one user works
on a not yet published Logiweb page, and if another user runs the garbage
collector, then pages referenced by the first users page may disappear.
This gives rise to no problems if all user consistently reference the latest
version of all pages and the garbage collector includes all latest versions
among the gc roots (c.f. the 'gcroots' option below). The garbage collector
only considers time stamps of files, so a young directories with no proper
files underneath run the risk of being garbage collected.
list of strings (c.f. logiweb.conf(5)
). Each string in the list must be a sign
(+ og -) followed by a pattern. Each pattern prepended by a plus sign indicates
directories which should not be considered for garbage collection. Such
directories are 'garbage collection roots' in the sense that the garbage
collector does not touch Logiweb pages under root directories or pages
transitively referenced by those pages (see note later on deficiencies
in the transitive closure). Each pattern prepended by a minus sign indicates
non-root directories which should be considered for garbage collection. All
directories not mentioned in the gcroots option are non-root directories.
Early elements of gcroots take precedence over later ones. The default value
is '!-lib/*!+*/latest', i.e. a list whose first element is '-lib/*' and whose second
element is '+*/latest'. This indicates that all directories (or symbolic links)
of name 'latest' one level below the publication directory are root directories
except that a directory named 'lib/latest' is a non-root directory.
above under the 'gc' option, the garbage collector only removes pages under
the users publication directory. The root directories need not lie under
the publication directory. When computing the transitive closure, the garbage
collector only considers pages under the publication directory. Hence, if
a Logiweb page under the publication directory references a page outside
the publication directory which in turn references back to a page in the
publication directory, then the last mentioned page may be garbage collected.
This gives rise to no problems if users consistently mirror all pages they
depend on (c.f. the 'mirror' option).
- When zero (the default)
do not measure the efficiency of the parsing process. If parsing of a page
takes suspiciously long time, try setting this parameter to a positive
number. Then the parser prints the number of times it visits each node of
the grammar. The parser only prints nodes that are visited at least 'grammar'
times, so grammar=500 prints all nodes that are visited at least 500 times.
A visit is not counted if the visit is successful in the sense that it
is on the path to an interpretation of the page. If a construct is visited
too often, the problem often lies in the surrounding constructs. For well
designed grammars, parsing time is linear in the length of the source,
for ill designed grammars, parsing time may be exponential.
header=warn (the default): Warn if there are constructs on referenced pages
which are not imported. When header=nowarn: Disable warning. When header=suggest:
Suggest a header which includes all constructs on all referenced pages.
header=html: Same as header=suggest but returns the suggestion in two html
- When true: Print short help message and exit.
address of http
server to be used for fetching Logiweb pages. The address
may be given as a domain name or a dotted ip. The value of httphost
default for the udphost parameter.
- Maximum number of
times a Logiweb page is macro expanded during codification. For iterations=1,
the page is macro expanded once. For iterations=2, the page is macro expanded,
harvested, compiled, and macro expanded again. For iterations=3 the page
is expanded, harvested, compiled, expanded a second time, harvested, compiled,
and expanded a third time. For iterations=0 there is no upper bound on the
number of times the page is macro expanded. Codification always terminates
when the result of an expansion is identical to the result of the previous
expansion. Note that macro definitions may change each time the page is
harvested (i.e. each time definitions are collected from the macro expanded
version of the page). This is why the result of an expansion may differ
from the result of the previous expansion. The 'iterations' keyword should
be used only for debugging of Logiweb pages. The 'iterations' keyword does
not affect referenced pages which are always iterated to the bitter end,
- (Jails are not yet implemented) When true (the default):
execute latex, bibtex, makeindex, and dvipdfm in a chroot jail. The jail
is forged by lgwmkjail (c.f. man lgwmkjail). See also options varbin and varjail.
- List of keywords used in pyk file, such as ,Pyk,Prio,PAGE,BIB,PRE,POST,BODY.
If this option is set to the empty string it defaults to the list containing
Pyk, Priority, PAGE, BIBLIOGRAPHY, PREASSOCIATIVE, POSTASSOCIATIVE, and
- Controls amount of generated
parse: stop after parsing
compile: parse, codify, and verify
diagnose: generate diagnose plus reference
body: above plus body, bibliography, and dictionary
codex: above plus codex and expansion
all: above plus vector
submit: above plus the actual Logiweb page
For level=parse, the parse tree is printed to standard output; the amount
of output can be controlled by spydepth and spylength. For level=parse and
level=compile, no rendering is done. For level=compile and up, verification
may be suppressed with 'test=no'.
- Instead of reading a source file,
fetch a compiled Logiweb page from the given url, then republish it locally.
The option disables 'pyk='.
- The path of a link to the published
output. The string may contain the following variables: $PYK$, $PAGE$, $DATE$,
$16$, $32$, and $64$ (c.f. the 'dest' option). When the link is the empty string,
no link is generated.
- The default value for the 'link'
option above when the page being published is a resubmission of a .lgw file
generated elsewhere. For such pages, $PYK does not make sense because the
name of the pyk source file is unknown.
- The default value
for the 'link' option above when the page being published is a submission,
i.e. not a resubmission and the 'level' option is set to 'submit'.
default value for the 'link' option above when the page being published is
a temporary one, i.e. not a resubmission and the 'level' option is set to something
different from 'submit'.
- Location of local configuration
file. The local configuration file is relative to the current value of $PWD.
See also the FILES section below.
- Base url of local
urls. The localhome option is relative to the value of httphost.
As an example,
the Logiweb logo is expected to be at the url formed by concatenating "http://
localhome, and "doc/logiweb.png". The online documentation is expected
to be rooted at the url formed by concatenating "http://
and "doc/". The default value of localhome is /logiweb/.
resource locator of a CGI-program which provides a user interface to the
Logiweb server. The URL is relative to the value of httphost.
value is /logiweb/server/relay/.
- If the 'execute' aspect
of the page symbol of a Logiweb page is defined, then the associated Logiweb
machine is dumped as an executable to the given filename. The machine may
be invoked by typing the filename followed by any command line options
the user wants to pass to the machine. Rendering of Logiweb pages may generate
an arbitrary number of Logiweb machines, but machines generated during
rendering are stored together with other output from the rendering process.
In contrast, the machine generated by the execute aspect may be placed
anywhere. To 'execute' a Logiweb page means 'to run the machine generated by
the execute aspect of the page symbol of the page'.
- The pyk
compiler can generate a Logiweb page in three ways: (1) It can translate
a pyk source file (c.f. the 'pyk' option), it can resubmit an lgw file (c.f.
the 'lgw' option) or it can translate a CGI-string (c.f. the 'post' option). In
addition, by turning on the 'mirror' flag, the pyk compiler can mirror all
transitively referenced pages of the page being generated. Mirrorring is
the same as resubmission except for the way the pages are selected: Mirrorred
pages are pages which are transitively referenced, resubmitted pages are
pointed out explicitly. Mirrorring can be combined with any of the three
ways of generating pages. Mirrorred pages are stored at the location pointed
out by the 'destmirror' option whereas generated pages are stored at the
location pointed out by the 'dest' option. When the 'dest' option is unset,
it defaults to the value of the 'destresubmit', 'destsubmit', or 'desttemp' option,
depending on various conditions. The 'destmirror' option is independent of
the 'dest', 'destresubmit', 'destsubmit', and 'desttemp' option. When mirrorring
a page, the pyk compiler first probes the destination of the mirrorred
lgw file. If a file exists on the destination, the pyk compiler assumes
the page is already mirrorred and suppresses the mirroring of that particular
- See 'post' option.
- When different from
the empty string: Dump all fingerprints to the given file. The resulting
file is useful as fingerprint.lisp in the sources of the pyk compiler.
true: Do not start the compiler but instead print all options from all
sources (i.e. command line options, environment variables, options from configuration
files, and compiled in options).
- When name is non-empty: Do
not start the compiler but instead print the option with the given name.
The option is printed exactly as it was given to the pyk compiler, including
leading and trailing spaces.
- As above, but the output reflects
the internal format to which the option is translated. For most options
there is little difference between optionstr and optionval, but try printing
the 'leap' option to see the difference.
- See 'post' option.
- See 'post' option.
- Amount of time
pyk waits for a response from each Logiweb server when resolving a Logiweb
reference. See pyk(5)
for the format of a 'duration'.
true, add understood parentheses to body and expansion before rendering.
May take time for large pages. This parameter is false by default.
the given string as a CGI-string (post method) with further options for
the pyk compiler. This is typically used when using the pyk compiler as
a CGI-program for implementing a Logiwiki. Options from the CGI-string take
precedence over options from configuration files and compiled in options
but are superseded by environment variables and command line options. For
security reasons, the CGI-string can only contain the options org, name,
level, date, test, verbose, pane1, and pane2. Of these options, the name,
org, pane1, and pane2 options only make sense to use when using Pyk as
a CGI-program. The name and org parameters allow a submitter to create Logiweb
pages in a private directory in that pages are created in directory org/name
under the publication directory (c.f. the 'url' and 'dest' options). Pyk concatenates
the text given as pane1 and pane2 to a single text and uses that as source
text instead of the source text pointed out by pyk=filename. See the EXAMPLES
section for an example of use.
- Path of source file. See pyk(5)
for the format.
- When true: Pyk exits when done. When false:
Pyk drops the user to a CLISP read-eval-print loop when done. When invoking
pyk with option -noquit or quit=no or quit=false or similar, you should
start the option list with -- as in 'pyk -- myfile -noquit'.
In the read-eval-print
loop one can start a new compilation by writing e.g. (pyk) or (pyk :pyk "myfile"
:level "compile") or (pyk "myfile" :level :submit). Options given in the
read-eval-print loop override all other options. A benefit of running pyk
from a CLISP read-eval-print loop is that once loaded Logiweb pages remain
in memory so they do not have to be loaded again. A drawback is that the
facility is poorly documented and the user is required to know Common Lisp.
To escape from the CLISP read-eval-print loop type (quit) including the parentheses.
In the read-eval-print loop one may write (unfit) to get a list of constructs
that are suspected to be mistakenly unfit, one may write (spy) to get the
lates 'spy' output, and one may write (state-ls) to get a list of all pages
in the in-memory cache of the pyk compiler (not to be confused with the
cache stored in the file system defined by the 'cache=' option).
In the read-eval-print
loop it is possible to query the *spy* variable which is set by the spy
construct during translation of a page, c.f. the spy option. The following
commands are available: (spy) prints the *spy* variable. (spycd fct) changes
the 'current path' so that e.g. (spycd car) followed by (spycd cdr) followed
by (spy) prints (cdr (car *spy*)). (spy/) sets the path to the empty list
such that a subsequent (spy) prints the entire *spy* variable. (spy..) discards
one element from the path. (spypwd) prints the path. (spy-set-depth depth)
overrides the spydepth option and controls how many levels of *spy* is
printed. (spy-set-length length) overrides spylength and controls how many
characters of each string is printed. For details, see pyk/optimize.lisp
in the sources of the Logiweb system.
- The roots parameter
indicates how external uniform resource locators (urls) map to local file
names. See logiweb(1)
for further information.
- List of permitted
rendering constructs. Default is /text/binary/tex/latex/bibtex/makeindex/dvipdfm.
As an example of use, change renderers to /text/binary/tex/latex/bibtex/makeindex/dvipdfm/mizf
to allow Logiweb to invoke Mizar. The renderers text, binary, makeindex,
dvipdfm, and mizf get special treatment (like redirecting stderr or creating
a dict subdirectory). All other renderers are invoked with redirection of
stdout and are supposed not to write to stderr to avoid cluttering up the
output from pyk.
- When yes: print spy messages. When no: suppress
spy messages. Spy messages are messages generated by the Logiweb spy write
facility. The spy write facility is implemented as an 'introduced' identity
function I(x) which has the side effect of writing x to standard output.
The spy write facility is highly unreliable and non-portable and should
only be used when debugging Logiweb programs. Logiweb may execute each spy
write zero, one or more times and in any, peculiar order. A particular use
is as follows: one may define a test case execution construct which writes
the test case to be tested to standard output before initiating the test.
If a test loops indefinitely, then that test will be the last one printed
to standard output by the spy writer. The amount of output can be controlled
by the spydepth and spylength options.
- Maximum number of
subtree levels printed by the 'spy' and 'diagnose' options. Default 10. A value
of -1 denotes infinity. A value of -2 denotes the default value which is 10
for 'spy' and -1 for 'diagnose'.
- Maximum number of characters
printed per string by the 'spy' and 'diagnose' options. A value of -1 denotes
infinity. A value of -2 denotes the default value which is 20 for 'spy' and
-1 for 'diagnose'.
- Url of pyk source for lgw page given by 'lgw='. When
the lgw option is given then Pyk republishes the given page. Pyk is able
to reconstruct everything from the lgw file except the source code used
for generating the lgw file. If one wants to make the source available (e.g.
for copy/paste) and if the source is available on the web, then one may
use src=url to point out the source. If src=url is given then the source
is fetched and republished without any processing. If src is set to the
emtpy string (e.g. by '-nosrc') then no source file is fetched. If src is set
to the special value 'yes' (e.g. by src=yes) then the value for source is taken
to be the value of 'lgw' with '.lgw' removed if present and '.pyk' added.
or omit testing. Pyk executes test cases before rendering the page so test=no
is useful if some test case loops indefinitely or takes very long time
and one just wants to typeset the page for inspection or debugging.
functions in a semi-readable format before compilation. Those functions whose
names contain one of the listed strings are printed. As an example, tracecompile=/or/and
prints all functions which contain 'or' or 'and' in their name. See logiweb.conf(5)
for the format of lists.
- Internet address of server
to be used for locating referenced Logiweb pages and for submitting generated
Logiweb pages. The address may be given as a domain name or a dotted ip.
If empty (the default), the value for httphost
is used for udphost.
port number of Logiweb server to be used for locating referenced Logiweb
pages and for submitting generated Logiweb pages.
- When yes:
Print names of all constructs that are suspected to be mistakenly unfit
for optimization. When no: Only print the number of suspects (or print the
suspect if there is only one suspect). A construct is suspected to be mistakenly
unfit if its definition is unfit for optimization but, at the same time,
the principal operator of the right hand side of the definition is fit
for optimization. To be fit for optimization a construct must be strict
and well-typed in a certain sense. Logiweb itself is unstrict and typeless
and the only problem with unfit operations is that they may be slow on
- When yes: Uninstall Logiweb installation using
the values of log, varbin, varconf, varhome, varhttp,
varlgwrelay, varlib, varlogiweb, varpyk, and varrelay which are typically
defined in the site configuration file. In typical installations where Logiweb
is installed by root, the uninstall also has to be done by root. Uninstallation
is done stepwise with the option to skip each step.
- Pyk translates
the given url to a directory and uses that directory as 'publication directory'.
Generated output is stored under that directory (c.f. the 'dest', 'org', and
- (Jails are not yet implemented) The location
of lgwlatex, lgwbibtex, lgwmakeindex, lgwdvipdfm, lgwmkjail, and lgwrmjail
for running tex, latex, etc. in a chroot jail. See also options jail and
- Location of the user configuration file. The user
configuration file is relative to the current value of $HOME. See also the
FILES section below.
- Compiled in default for the site configuration
file. Only used during installation. Only has effect if set in logiweb.conf
in the root of the source tree.
- The path of the Logiwiki
creation CGI-script. See the SECURITY CONSIDERATIONS section below before
enabling this facility.
- The directory which contains e.g. Logiweb
web help pages.
- The location of the Logiweb Apache configuration
- The location of the Logiweb server init script.
are not yet implemented) Master copy of the chroot jail in which lgwlatex,
lgwbibtex, lgwmakeindex, and lgwdvipdfm run. See also options jail and varbin.
- The location of the lgwping command.
location of the lgwrelay command.
- The location of the logiweb.so
- The location of logiweb command.
location of Logiweb man pages.
- The location of the pyk command.
- The location of the Logiweb relay CGI-script.
ScriptAlias command which ends up in the Logiweb Apache configuration file.
- The path of the Logiwiki submission CGI-script. See the SECURITY
CONSIDERATIONS section below before enabling this facility.
verbose=0: print few messages. If verbose=1: print more messages. If verbose=2:
print even more messages.
- When true: Print version number
- Url of the wiki directory relative to the varhome
option. See the SECURITY CONSIDERATIONS section below before enabling a
A Pyk source file typically has extension .pyk.
up to three configuration files, namely a 'site', a 'user', and a 'local' configuration
file. Pyk shares configuration files with the Logiweb server (logiweb(1)
The site configuration file is typically located in /etc/logiweb/logiweb.conf,
the user configuration file is typically located in $HOME/.logiweb/logiweb.conf,
and the local configuration file is typically located in $PWD/logiweb.conf.
The location of the site configuration file has a compiled in default
but may be overridden by the conf command line argument or the LOGIWEB_CONF
environment variable. Issue the command 'logiweb --option' to see the values
of compiled in defaults.
The location of the user configuration file is
typically set in the site configuration file but may be overridden by the
userconf command line argument or the LOGIWEB_USERCONF environment variable.
The location of the user configuration file is typically set to .logiweb/logiweb.conf
which indicates that the user configuration file is the .logiweb/logiweb.conf
file in the users home catalogue. Pyk issues no warnings if the user configuration
file does not exist so it is safe to set userconf to .logiweb/logiweb.conf
in the site configuration file even if some users do not have a user configuration
Pyk reads no user configuration file if userconf is set to the empty
string. The empty string happens to be the compiled in default for the userconf
The location of the local configuration file is typically set in
the user configuration file but may be overridden by the localconf command
line argument or the LOGIWEB_LOCALCONF environment variable. The location
of the local configuration file is typically set to logiweb.conf which indicates
that the local configuration file is ./logiweb.conf. The local configuration
file allows to specify particular options to be in effect when the user
cd's to a particular directory.
For each long option there
is an associated environment variable. The name of the environment variable
equals the name of the option prefixed by 'LOGIWEB_'. As an example, instead
of writing 'userconf=xyzzy' on the command line or in a configuration file,
one can set the environment variable LOGIWEB_USERCONF to xyzzy. Option names
are case insensitive whereas option values are case sensitive. So one may
instead set the environment variable Logiweb_UserConf to xyzzy and one
may write UserConf=xyzzy on the command line or in a configuration file.
The 'roots' option is typically set in the site configuration
file since it is used by the Logiweb server and defines the relationship
between urls and file names.
The 'url' option is typically set in the user
configuration file since this argument controls where Logiweb pages are
If dir/myfile.pyk contains a pyk file then one may translate
it to a Logiweb file by 'pyk dir/myfile' or 'cd dir; pyk pyk=myfile'. If one
adds a file dir/logiweb.conf which contains the text 'pyk=myfile', and if
the localconf option is set to 'logiweb.conf' in the site or user configuration
files, then one may translate myfile by 'cd dir; pyk' since the file name
is supplied by the local configuration file.
A Logiwiki consists of an
html formula published at one url and the pyk compiler published as a CGI-program
on another url. A sample html formula is given below. The html formula below
supposes that the pyk compiler is published at url http://logiweb.eu/wiki/logiweb/server/post.
A user may submit a Logiweb page by accessing the formula, placing the
source text in pane1 and pane2, selecting options, and pressing 'Compile'.
<head><title>Online pyk compiler</title></head>
<img alt="Logiweb", height="62", width="46",
<h2>Online pyk compiler</h2>
<input type="submit" value="Compile">
org=<input type="text" name="org" size=10>
name=<input type="text" name="name" size=10>
<option selected> body
<input type="reset" value="Reset / Clear">
<textarea name="pane1" rows=20 cols=80></textarea>
<textarea name="pane2" rows=20 cols=80></textarea>
GNU CLISP: invalid argument
You forgot to start the argument
list with either -- or a file name (where the file name is not allowed to
start with a hyphen). To pass a file name like -abc which starts with a hyphen,
use pyk pyk=-abc.
GNU CLISP: use '-h' for help
Don't trust this message if you
look for help on Logiweb. Use pyk -- -help instead.
Lisp stack overflow
the available stack size in the user shell. If using bash: add 'ulimit -s
unlimited' to .bashrc. If using csh: add 'limit stacksize ...' to .cshrc. If you
still get a Lisp stack overflow, you either translate very big pages or
do something that causes infinite looping. The latter may occur several
places such as during macro expansion or verification. To locate the problem,
try running with verbose=2 and/or spy=yes and/or quit=no. Also try to include
trace and spy constructs strategic places in your page.
occurs without reason: Internal error. Some process has raised an exception
without printing a reason. Rerunning with verbose=1 or verbose=2 may reveal
what pyk was doing when the uncaught exception occurred.
A construct has been defined using an 'introduction' (= 'optimizing definition'),
but the pyk compiler does not recognize the introduction. There are several
possible reactions: (1) Ignore the message. When the pyk compiler does not
recognize an optimizing definition, it treats the definition as an ordinary
definition. The construct being defined may then use more cpu-time and memory
than it would if it were recognized. (2) Change the definition from an optimizing
to an ordinary definition. This gives the same result as (1)
above but also
avoids the warning message. (3) Change the definition such that it is recognized
properly, e.g. by copying the definition from a page on which the definition
is stated correctly. (4) (for experienced users only) Modify and rebuild
the pyk compiler so that it learns about the construct in question. To do
so, modify optimize.lisp to define how new optimized function should be
treated and modify c-accept in codify.lisp if the optimized functions should
be compiled an unusual way. Then run pyk on the .pyk file containing introductions
(typically a base page) with -optidump=fingerprint.lisp to generate a new
fingerprint.lisp file. The fingerprint.lisp file must replace the fingerprint.lisp
file in the source of the pyk compiler. When dumping the new fingerprint
file, pyk tells which fingerprints have been added, removed, and renamed
compared to its currently compiled in fingerprints. Make sure no important
fingerprints have been removed and ensure the source code has been updated
to reflect name changes.
Setting the varsubmit
option to a non-empty string allows complete strangers to place arbitrary
files in the directory pointed out by the wiki option under the directory
pointed out by the varhome option and to run latex, bibtex, makeindex,
and dvipdfm on these files. Latex, bibtex, makeindex, and dvipdfm might
run as a user named something like 'apache' (look at the ownership of files
created in the wiki directory). The varsubmit option only has effect during
installation. Changing it later has no effect. To disable a Logiwiki after
installation, uninstall Logiweb, change varsubmit, and reinstall. Alternatively,
remove the CGI-scipt pointed out by varsubmit and remove the world writable
Klaus Grue, http://logiweb.eu/
Table of Contents