You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for [[/eggref/5/chickadee|the CHICKEN 5 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. == chickadee ''chickadee'' is a web interface to {{chicken-doc}}. === Quickstart # chicken-install chickadee $ chickadee serve This will start a chickadee server on [[http://localhost:8080]], using your global chicken-doc repository. [[toc:]] === Setting up a server Before using ''chickadee'', you need to download or create a [[chicken-doc]] repository. Next, fetch ''chickadee'' using {{chicken-install}}: # chicken-install chickadee This installs the chickadee library files, static web files, configuration files and a helper program called {{chickadee}} which simplifies running your own server. chickadee is usually ready to run without further configuration: $ chickadee serve This starts a server on port 8080, using the default configuration and data files that were installed via {{chicken-install}}. Access, debug and AJAX logs are disabled, and error logging is sent to ''stderr''. Therefore no special privileges are required to start the default config. You may sometimes need to customize the server settings -- for example to start on a different port. This is explained below. ==== Customization at the command-line The {{chickadee}} wrapper accepts options which override commonly-changed settings in the configuration file, so that you don't need to modify the config file for simple changes. usage: chickadee serve [options] [conf-file] options: -p --port NUM Port number -A --access-log FILE Access log file -E --error-log FILE Error log file -D --debug-log FILE Debug log file -J --ajax-log FILE AJAX access log FILE is a filename relative to the directory holding [conf-file]. It may be "-" to log to the console or "" to suppress logging. examples: chickadee serve -p 8081 Start a server on port 8081. chickadee serve -A - -D /tmp/debug.log -J /tmp/ajax.log -E "" Log accesses to stdout, debugging information to /tmp/debug.log, and AJAX accesses to /tmp/ajax.log. Error logging is suppressed. ==== Customization of the configuration file For permanent or complex configuration changes, the default configuration file can be modified, or the {{chickadee}} wrapper can be directed to use an alternate config file. Keep in mind that the defaults will be overwritten whenever the egg is upgraded. You can find the location of the default chickadee config file with: $ chickadee location conf: /usr/local/chicken-4/share/chicken/chickadee/config.scm base: /usr/local/chicken-4/share/chicken/chickadee {{conf}} is the configuration file and {{base}} is the base directory containing all chickadee's datafiles. At startup, chickadee changes to the {{base}} directory, and so all paths in the config file are relative to that location. Actually, {{base}} is always the directory containing {{conf}}, so you can copy the default base directory tree anywhere, point chickadee to that config file, and that copy will be used. $ cp -rp /usr/local/chicken-4/share/chicken/chickadee ~ $ chickadee serve ~/chickadee/config.scm You can also place multiple config files inside the same base directory, sharing the same datafiles with different configurations: $ cp ~/chickadee/config.scm ~/chickadee/config-prod.scm $ vi ~/chickadee/config-prod.scm $ chickadee serve ~/chickadee/config-prod.scm The actual path to chickadee's datafiles is controlled by the configuration options {{root-path}}, {{access-log}} and so on, which by default use relative paths (to the location of the config file). You can use absolute paths instead if you like; the "base directory" is just a matter of convenience. Configuration [[#Configuration|syntax]] and [[#Examples|examples]] are described later in this document. ==== Customization of look and feel The CSS and Javascript static files can be modified to customize the look and feel of chickadee. The recommended way to do this is to [[#Customization of the configuration file|make a copy]] of the chickadee base directory first. A further suggestion is to rename (or copy) the files you want to change and then update their paths in the configuration file: $ cp ~/chickadee/root/cdoc/chickadee.css \ ~/chickadee/root/cdoc/chickadee-mine.css # then in ~/chickadee/config.scm, change (chickadee-css-files (list (uri "/cdoc/chickadee.css"))) # to (chickadee-css-files (list (uri "/cdoc/chickadee-mine.css"))) Finally you might even want to change the configuration file name: $ mv ~/chickadee/config.scm ~/chickadee/config-mine.scm The rationale behind this is to allow you to copy datafile updates from the egg into your private copy without clobbering your changes. (A better solution to initialize and update a copy might be provided in the future.) Currently the page layout, and especially the root page, are not customizable without editing the source code. === API <procedure>(chickadee-start-server)</procedure> Start the Chickadee server. Server configuration is done via parameters and, as [[spiffy]] is used as the backend webserver, all of its configuration options also apply. === Configuration <parameter>chickadee-uri</parameter> Main access URI to Chickadee for users, as a URI object. Defaults to {{(uri-reference "/chickadee")}}, so that the node {{foreign types}} is accessible at {{/chickadee/foreign/types}}. <parameter>cdoc-uri</parameter> Internal URI for Chickadee, used to perform path and identifier lookup and searches. Although you can choose to make {{cdoc-uri}} a child of {{chickadee-uri}}, keep in mind it may conflict with an existing node name. Defaults to {{(uri-reference "/cdoc")}}. <parameter>incremental-search-uri</parameter> URI used to provide incremental search capability. This URI is arbitrary, but is typically a child of {{cdoc-uri}}. Due to AJAX limitations it must inhabit the same domain name as {{chickadee-uri}}. Defaults to {{(uri-reference "/cdoc/ajax/prefix")}}. <parameter>chickadee-css-files</parameter> List of URIs to CSS files for Chickadee. Defaults to {{(list (uri-reference "/cdoc/chickadee.css"))}}. <parameter>chickadee-early-js-files</parameter> List of URIs (uri-reference objects) to early Javascript files for Chickadee. These are inserted prior to the document body; for example, scripts such as Modernizr must be loaded prior to the body. <parameter>chickadee-js-files</parameter> List of URIs (uri-reference objects) to Javascript files for Chickadee. These are inserted after the document body, as most scripts should be. Any item may be a plain string instead, in which case it is inserted literally in the document as a Javascript snippet between script tags. For example, you might use this to implement a jQuery fallback. Defaults to {{(list (uri-reference "/cdoc/chickadee.js"))}}. <parameter>maximum-match-results</parameter> Maximum number of match results to return for a match query. Default: 250. <parameter>maximum-match-signatures</parameter> Maximum number of signatures to return for a match query, up to {{maximum-match-results}}. Default: 100. Obtaining signatures may increase disk load in the current implementation. <parameter>incremental-search</parameter> Number of incremental search results to display; 0 or #f to disable. Defaults to 0. <parameter>incremental-search-delay</parameter> Time in milliseconds to delay incremental search requests. Defaults to 50, which seems reasonable for WAN or LAN use. 20 will give even better interactive response on a fast network and CPU. <parameter>cache-nodes-for</parameter> Time in milliseconds to inform browsers that node pages should be cached for. Defaults to 300. If #f, no caching is done. <parameter>cache-static-content-for</parameter> Time in milliseconds to inform browsers that static content such as CSS and Javascript should be cached for. <parameter>last-modified</parameter> Base time used for node last-modified calculations, in seconds. Chickadee uses the overall repository modification time (updated whenever a reindex is done) to determine when a node was last modified. Browsers with a vaild cached copy will receive a "304 Not Modified" response. However, the value of {{last-modified}} will also be considered; the modification time is taken as the maximum of the two values. This is done because changes to program logic may change the rendering of the page even when the repository has not changed. For example, set {{last-modified}} to {{(current-seconds)}} to simply invalidate all pages when the server is restarted. Defaults to 0. <parameter>ajax-log</parameter> AJAX access log pathname. Separate from the usual {{access-log}} because this is potentially disk and CPU intensive. Set to {{#f}} to disable. === Debugging <parameter>%chickadee:debug-incremental-search-latency</parameter> Simulate network latency of N milliseconds for incremental search. Allows you to test estimated interactive response across the Internet on a local system. === Examples ==== Configuration examples An example local configuration file for the {{chickadee}} wrapper. If you add {{(chickadee-start-server)}} to the end, you can run this file as a standalone program. Also see [[https://raw.github.com/ursetto/chickadee/master/chickadee-config.scm|config.scm]], which is installed as the default config file, and is more up-to-date. <enscript lang="scheme"> (use chickadee spiffy uri-common) (define uri uri-reference) (root-path "root") (debug-log (current-error-port)) (server-port 8080) (access-log "logs/access.log") (max-connections 8) (ajax-log "/tmp/ajax.log") (cdoc-uri (uri "/cdoc")) (chickadee-uri (uri "/chickadee")) (incremental-search-uri (uri "/cdoc/ajax/prefix")) (chickadee-css-files (list (uri "/cdoc/chickadee.css"))) (chickadee-js-files (list (uri "http://code.jquery.com/jquery-1.4.2.min.js") (uri "/cdoc/jquery.metadata.2.1.min.js") (uri "/cdoc/chickadee-jquery.js"))) (maximum-match-results 250) (maximum-match-signatures 100) (incremental-search 15) (incremental-search-delay 50) (cache-nodes-for 300) (cache-static-content-for 1800) (last-modified (current-seconds)) </enscript> Configuration of the [[http://api.call-cc.org/doc/|primary chickadee server]] behind an nginx caching proxy. Also see [[https://raw.github.com/ursetto/chickadee/master/chickadee-config-nginx.scm|config-nginx.scm]], which is installed alongside the egg, and is more up-to-date. <enscript lang="scheme"> (use chickadee spiffy uri-common) (define uri uri-reference) (root-path "root") (debug-log (current-error-port)) (access-log "logs/access.log") (error-log "logs/error.log") (server-port 8383) (max-connections 8) (ajax-log #f) (cdoc-uri (uri "/cdoc")) (chickadee-uri (uri "/chickadee")) (incremental-search-uri (uri "/cdoc/ajax/prefix")) (chickadee-css-files (list (uri "/cdoc/chickadee.css?5"))) (chickadee-js-files (list (uri "http://code.jquery.com/jquery-1.4.2.min.js") (uri "/cdoc/jquery.metadata.2.1.min.js") (uri "/cdoc/chickadee-jquery.js?2"))) (maximum-match-results 250) (maximum-match-signatures 100) (incremental-search 15) (incremental-search-delay 50) (cache-nodes-for 600) (cache-static-content-for 1800) (last-modified (current-seconds)) (chickadee-start-server) </enscript> ==== Usage examples * [[http://conkeror.org/Webjumps#Chickadee|Webjump for Conkeror]] ==== AppArmor A [[https://raw.github.com/ursetto/chickadee/master/etc/usr.local.bin.chickadee-prod.sh|sample AppArmor profile]] is included in the egg source. It assumes the use of a dedicated [[https://raw.github.com/ursetto/chickadee/master/etc/chickadee-prod.sh|startup script]] for chickadee, so that the restrictions only apply when calling chickadee via the script. The sample also uses the {{config-nginx.scm}} built-in config file to run behind an nginx proxy. Generally, you just have to update {{CHICKEN}} in both files to reflect your installed Chicken, {{LOGDIR}} to specify your log directory, install the profile in {{/etc/apparmor.d}}, place the script in {{/usr/local/bin}}, and tweak the script and profile if necessary. A detailed explanation of AppArmor is beyond the scope of this document. === About this egg ==== Source [[https://github.com/ursetto/chickadee]] ==== Author Jim Ursetto ==== Version history ; 0.12.1 : Port to Chicken 5. Enhance signature readability. ; 0.11.2 : Add a second parameter to the last-modified header vector to comply with stricter header checking in intarweb 1.7. ; 0.11.1 : Correct a distribution error ; 0.11.0 : Decluttered appearance. Link and style definition identifiers and arguments that appear in verbatim plaintext, with new chicken-doc-html. ; 0.10.3 : Permit arbitrary JS snippets; fall back to local jQuery in production config ; 0.10.2 : Use local jquery for default config, improving offline usage ; 0.10.1 : Limit match result set size to prevent runaway memory usage during regexp search. Also added example AppArmor profile. ; 0.10.0 : Current version ; 0.9.8 : Add chickadee wrapper. ; 0.9.0 : Initial release. ==== License Copyright (c) 2010-2019 Jim Ursetto. License: 3-clause BSD. Description of your changes:

I would like to authenticate

Spam control

What do you get when you add 0 to 10?