Table of Contents

Name

pyk - format and publish logiweb page

Synopsis

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] [varinit=string] [varjail=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]

Description

The 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'.

Options 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.

Giving 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 --.

Options

bin=dirname
Directory for storing the binaries defined by the 'executables' aspect of a page. When empty (the default) no binaries are stored.

cache=dirname
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.

conf=filename
Name of main configuration file, e.g. /etc/logiweb/logiweb.conf. See also the FILES section below.

dest=string
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 a slash.

destmirror=string
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.

destresubmit=string
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' option.

destsubmit=string
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'.

desttemp=string
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 'submit'.

diagnose=Boolean
When yes: print pyk version of diagnose. Prints entire diagnose by default. Output may be limited by the spydepth and spylength options.

dump=filename
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 those pages.

dumpconf=filename
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.

exec=Boolean
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.

filter=list
Specifies 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
unicode-16-little-endian
ucs-4  unicode-32  unicode-32-big-endian
unicode-32-little-endian
utf-8  utf8
utf-16
utf-7
java
ascii
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
koi8-r
koi8-u
koi8-ru
jis_x0201
mac-arabic
mac-central-europe
mac-croatian
mac-cyrillic
mac-dingbat
mac-greek
mac-hebrew
mac-iceland
mac-roman  macintosh
mac-romania
mac-symbol
mac-thai
mac-turkish
mac-ukraine
cp437
cp437-ibm
cp737
cp775
cp850
cp852
cp852-ibm
cp855
cp857
cp860
cp860-ibm
cp861
cp861-ibm
cp862
cp862-ibm
cp863
cp863-ibm
cp864
cp864-ibm
cp865
cp865-ibm
cp866
cp869
cp869-ibm
cp874
cp874-ibm
windows-1250  cp1250
windows-1251  cp1251
windows-1252  cp1252
windows-1253  cp1253
windows-1254  cp1254
windows-1255  cp1255
windows-1256  cp1256
windows-1257  cp1257
windows-1258  cp1258
hp-roman8
nextstep
euc-jp
shift-jis
cp932
iso-2022-jp
iso-2022-jp-2
iso-2022-jp-1
euc-cn
hz
gbk
cp936
gb18030
euc-tw
big5
cp950
big5-hkscs
iso-2022-cn
iso-2022-cn-ext
euc-kr
cp949
iso-2022-kr
johab
armscii-8
georgian-academy
georgian-ps
tis-620
mulelao-1
cp1133
viscii
tcvn
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 spaces.

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.

gc=Boolean
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.

gcpatience=duration
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.

gcroots=list
A 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.

As mentioned 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).

grammar=integer
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|nowarn|suggest|html
When 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 text areas.

help=Boolean
When true: Print short help message and exit.

httphost=internet-address
Internet 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 is the default for the udphost parameter.

iterations=cardinal
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, if any.

jail=Boolean
(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.

keyword=list
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 BODY.

level=parse|compile|diagnose|body|codex|all|submit
Controls amount of generated output:
  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'.

lgw=url
Instead of reading a source file, fetch a compiled Logiweb page from the given url, then republish it locally. The option disables 'pyk='.

link=string
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.

linkresubmit=string
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.

linksubmit=string
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'.

linktemp=string
The 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'.

localconf=filename
Location of local configuration file. The local configuration file is relative to the current value of $PWD. See also the FILES section below.

localhome=directory
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:// ", httphost, localhome, and "doc/logiweb.png". The online documentation is expected to be rooted at the url formed by concatenating "http:// ", httphost, localhome, and "doc/". The default value of localhome is /logiweb/.

localrelay=directory
Uniform resource locator of a CGI-program which provides a user interface to the Logiweb server. The URL is relative to the value of httphost. The default value is /logiweb/server/relay/.

machine=filename
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'.

mirror=Boolean
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 page.

name=string
See 'post' option.

optidump=filename
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.

option=Boolean
When 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).

optionstr=name
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.

optionval=name
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.

org=string
See 'post' option.

pane1=string
See 'post' option.

pane2=string
See 'post' option.

patience=duration
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'.

parenthesize=Boolean
When true, add understood parentheses to body and expansion before rendering. May take time for large pages. This parameter is false by default.

post=string
Process 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.

pyk=filename:
Path of source file. See pyk(5) for the format.

quit=Boolean
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.

roots=association-list
The roots parameter indicates how external uniform resource locators (urls) map to local file names. See logiweb(1) for further information.

renderers=list
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.

spy=Boolean
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.

spydepth=integer
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'.

spylength=integer
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'.

src=url
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.

test=Boolean
Include 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.

tracecompile=list
Print 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.

udphost=internet-address
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.

udpport=port-number
Udp port number of Logiweb server to be used for locating referenced Logiweb pages and for submitting generated Logiweb pages.

unfit=Boolean
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 execution.

uninstall=Boolean
When yes: Uninstall Logiweb installation using the values of log, varbin, varconf, varhome, varhttp, varinit, varlgwping, 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.

url=...
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 'name' options).

varbin=directory
(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 varjail.

userconf=filename
Location of the user configuration file. The user configuration file is relative to the current value of $HOME. See also the FILES section below.

varconf=string
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.

varcreate=path
The path of the Logiwiki creation CGI-script. See the SECURITY CONSIDERATIONS section below before enabling this facility.

varhome=string
The directory which contains e.g. Logiweb web help pages.

varhttp=string
The location of the Logiweb Apache configuration file.

varinit=string
The location of the Logiweb server init script.

varjail=string
(Jails are not yet implemented) Master copy of the chroot jail in which lgwlatex, lgwbibtex, lgwmakeindex, and lgwdvipdfm run. See also options jail and varbin.

varlgwping=string
The location of the lgwping command.

varlgwrelay=string
The location of the lgwrelay command.

varlib=string
The location of the logiweb.so shared library.

varlogiweb=string
The location of logiweb command.

varman=string
The location of Logiweb man pages.

varpyk=string
The location of the pyk command.

varrelay=string
The location of the Logiweb relay CGI-script.

varscript=string
A ScriptAlias command which ends up in the Logiweb Apache configuration file.

varsubmit=path
The path of the Logiwiki submission CGI-script. See the SECURITY CONSIDERATIONS section below before enabling this facility.

verbose=0|1|2
If verbose=0: print few messages. If verbose=1: print more messages. If verbose=2: print even more messages.

version=Boolean
When true: Print version number and exit.

wikisubmit=url
Url of the wiki directory relative to the varhome option. See the SECURITY CONSIDERATIONS section below before enabling a logiwiki.

Files

A Pyk source file typically has extension .pyk.

Pyk reads 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 file.

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 option.

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.

Environment

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.

Examples

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 published.

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'.


<html>
<head><title>Online pyk compiler</title></head>
<body bgcolor=yellow>
<img alt="Logiweb", height="62", width="46",
align="right", hspace="30",
src="http://logiweb.eu/wiki/logiweb/doc/logiweb.png"/>
<h2>Online pyk compiler</h2>
<form action="http://logiweb.eu/wiki/logiweb/server/post"
method=post>
<input type="submit" value="Compile">
&nbsp;org=<input type="text" name="org" size=10>
&nbsp;name=<input type="text" name="name" size=10>
&nbsp;level=<select name="level">
<option> compile
<option> test
<option selected> body
<option> codex
<option> all
<option> submit
</select>
&nbsp;test=<select name="test">
<option> yes
<option> no
</select>
&nbsp;verbose=<select name="verbose">
<option> 0
<option> 1
<option> 2
</select>
&nbsp;<input type="reset" value="Reset / Clear">
<br><br>
<textarea name="pane1" rows=20 cols=80></textarea>
<textarea name="pane2" rows=20 cols=80></textarea>
</form>
</body>
</html>

Errors

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

Increase 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.

Goodbye

When 'Goodbye' 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.

Unrecognized introduction

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.

Security Considerations

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 wiki directory.

Author

Klaus Grue, http://logiweb.eu/

See Also

logiweb(1) , logiweb(7) , logiweb.conf(5) , lgwping(1) , lgwrelay(1) , pyk(5)


Table of Contents