cas February 2009

cas@lists.stg.fedorahosted.org

1 participants
2 discussions

doc/_images doc/index.html doc/searchindex.js doc/_sources
by Adam Stokes 11 Feb '09

11 Feb '09

doc/_images/cas_logo.png |binary doc/_sources/index.txt | 152 +++++++++++++++++++++++++++++++++++++++++++++-- doc/index.html | 140 +++++++++++++++++++++++++++++++++++++++++-- doc/searchindex.js | 2 4 files changed, 282 insertions(+), 12 deletions(-) New commits: commit d065bc0f844853d7d7dffd5b96a63a2da5e137ee Author: Adam Stokes <uzr(a)rambos.knife> Date: Wed Feb 11 09:34:06 2009 -0500 - Updated documentation to provide analyzing and troubleshooting sections diff --git a/doc/_images/cas_logo.png b/doc/_images/cas_logo.png new file mode 100644 index 0000000..39e2302 Binary files /dev/null and b/doc/_images/cas_logo.png differ diff --git a/doc/_sources/index.txt b/doc/_sources/index.txt index aac3fcb..418e0ab 100644 --- a/doc/_sources/index.txt +++ b/doc/_sources/index.txt @@ -1,5 +1,7 @@ -Core Analysis System (CAS) -========================== +.. image:: cas_logo.png + +Core Analysis System +==================== Introduction ------------ @@ -92,8 +94,8 @@ version of crash is installed this directive can be set to the crash binary and CAS will automatically process x86 cores on a x86_64 machine. ``Note`` this is only available if the CAS server is a x86_64 machine. -Setup ------ +Setup & Execution +----------------- Preparing CAS Server ^^^^^^^^^^^^^^^^^^^^ @@ -192,10 +194,152 @@ initial analysis to the specified email address. From there further instructions are provided in either the email or the ``process log`` on how to access and analyze the core. +Analyzing +--------- + +Continuing with the previous example the results of CAS processing should be emailed +and look something similar to:: + + Subject: CAS results for 12345 + Date: Wed, 11 Feb 2009 08:44:37 -0500 + + Location: /cores/processed/12345/02.11.09.08.44.19 + Server: test-2.gss.redhat.com + Output data: + PID: 0 TASK: ffffffff803e9b80 CPU: 0 COMMAND: "swapper" + #0 [ffffffff8047a0a0] smp_call_function_interrupt at ffffffff8011d191 + #1 [ffffffff8047a0b0] call_function_interrupt at ffffffff80110bf5 + --- <IRQ stack> --- + #2 [ffffffff80529f08] call_function_interrupt at ffffffff80110bf5 + [exception RIP: default_idle+32] + RIP: ffffffff8010e7a9 RSP: ffffffff80529fb8 RFLAGS: 00000246 + RAX: 0000000000000000 RBX: 0000000000000000 RCX: 0000000000000018 + RDX: ffffffff8010e789 RSI: ffffffff803e9b80 RDI: 0000010008001780 + RBP: 0000000000000000 R8: ffffffff80528000 R9: 0000000000000080 + R10: 0000000000000100 R11: 0000000000000004 R12: 0000000000000000 + R13: 0000000000000000 R14: 0000000000000000 R15: 0000000000000000 + ORIG_RAX: fffffffffffffffa CS: 0010 SS: 0018 + #3 [ffffffff80529fb8] cpu_idle at ffffffff8010e81c + + PID: 0 TASK: 100f57cb030 CPU: 1 COMMAND: "swapper" + #0 [1000107bfa0] smp_call_function_interrupt at ffffffff8011d191 + #1 [1000107bfb0] call_function_interrupt at ffffffff80110bf5 + --- <IRQ stack> --- + #2 [10001073e98] call_function_interrupt at ffffffff80110bf5 + [exception RIP: default_idle+32] + RIP: ffffffff8010e7a9 RSP: 0000010001073f48 RFLAGS: 00000246 + RAX: 0000000000000000 RBX: 0000000000000e86 RCX: 0000000000000018 + RDX: ffffffff8010e789 RSI: 00000100f57cb030 RDI: 00000102000a4780 + RBP: 0000000000000001 R8: 0000010001072000 R9: 0000000000000040 + R10: 0000000000000000 R11: 0000000000000008 R12: 0000000000000000 + R13: 0000000000000000 R14: 0000000000000000 R15: 0000000000000000 + ORIG_RAX: fffffffffffffffa CS: 0010 SS: 0018 + #3 [10001073f48] cpu_idle at ffffffff8010e81c + + PID: 6122 TASK: 101f3658030 CPU: 2 COMMAND: "gfs_quotad" + #0 [101f21efb20] start_disk_dump at ffffffffa03183ff + #1 [101f21efb50] try_crashdump at ffffffff8014cc1d + #2 [101f21efb60] die at ffffffff80111c90 + #3 [101f21efb80] do_invalid_op at ffffffff80112058 + #4 [101f21efc40] error_exit at ffffffff80110e1d + [exception RIP: do_dlm_lock+366] + + ... snip ... + +From this email a ``location`` is provided ``/cores/processed/12345/02.11.09.08.44.19`` +and the server in which further analyzation can be continued ``test-2.gss.redhat.com``. + +Normally from a support perspective this email should contain enough information +for a kernel engineer to begin debugging the problem. Assuming more is needed +the information provided previously will prove beneficial for anyone wishing +to access this data. + +Logging into the stated server and changing into the directory defined several +files are presented:: + + $ pwd + /cores/processed/12345/02.11.09.08.44.19 + $ ls + 12345.log crash crash.in crash.out usr vmcore.12345 + +``12345.log``: contains any informational messages presented during the processing +of the core. Everything from informational to debug statements are provided here. + +``crash``: a script autogenerated to provide an automated way of gathering intial +data from the coredump. ``Note`` if wanting to use this crash wrapper in a more +manual approach some alterations to the script need to occur. + +crash wrapper in its original form:: + + #!/bin/sh + /usr/bin/crash /cores/processed/12345/02.11.09.08.44.19/vmcore.12345 /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux -s < /cores/processed/12345/02.11.09.08.44.19/crash.in + +In order to remove automation the redirect from crash.in needs to be removed:: + + #!/bin/sh + /usr/bin/crash /cores/processed/12345/02.11.09.08.44.19/vmcore.12345 /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux + +**Alternative to using the crash wrapper** + +It is possible to specify the vmlinux and corefile with crash on the command line:: + + $ crash /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux /cores/processed/12345/02.11.09.08.44.19/vmcore.12345 + +``crash.in``: a list of commands to be read into crash during the automated +analysis:: + + bt -a >>/cores/processed/12345/02.11.09.08.44.19/crash.out + sys >>/cores/processed/12345/02.11.09.08.44.19/crash.out + log >>/cores/processed/12345/02.11.09.08.44.19/crash.out + mod >>/cores/processed/12345/02.11.09.08.44.19/crash.out + exit + +``crash.out``: output of initial crash analysis and the same data which +is sent in an email if defined. + +``usr``: directory structure from the extraction of the vmlinux file +from the associated kernel-debuginfo rpm for use within crash:: + + /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux + +``vmcore.12345``: corefile from which was either defined or extracted from +a compressed archive during CAS initialization. + +Troubleshooting +--------------- + +Some of the major problems that arise when using CAS usually boils down to some +improper usage of the compression and archiving tools. + +When compressing a core which may need to be sent over the network to a CAS server +one of the proper ways to do so is:: + + $ tar cvjf vmcore.12345.tar.bz2 vmcore.12345 + +Other various ways of compressing archive are as follows:: + + $ tar cvzf vmcore.tar.gz vmcore + $ gzip vmcore + $ bzip2 vmcore + +``Note``: please do not double compress or CAS will fail. + +Another issue, which isn't primarily a fault of CAS, are +incomplete or corrupted cores. If either of these occur +there is a chance that CAS will not be able to process +the data needed to associate a debug kernel or do any +sort of automated analysis. Unfortunately, there is not +much that can be done to resolve these sort of issues +other than verifying that the process which happens when +a system coredump and when that dump reaches the +system specified for retrieval is solid and are seeing +no errors. + Resources ========= * `CAS Wiki <http://fedorahosted.org/cas>`_ +* `CAS FAQ <https://fedorahosted.org/cas/wiki/CasFAQ>`_ * `Mailing list <https://fedorahosted.org/mailman/listinfo/cas>`_ * `Upstream releases <https://fedorahosted.org/releases/c/a/cas/>`_ * Checkout latest from Git, ``git clone git://git.fedorahosted.org/cas.git`` diff --git a/doc/index.html b/doc/index.html index 5ee6297..72522e1 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,7 +3,7 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - <title>Core Analysis System (CAS) — CAS v0.13-118 documentation</title> + <title>Core Analysis System — CAS v0.13-118 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> @@ -37,8 +37,9 @@ <div class="body"> - <div class="section" id="core-analysis-system-cas"> -<h1>Core Analysis System (CAS)<a class="headerlink" href="#core-analysis-system-cas" title="Permalink to this headline">¶</a></h1> + <img alt="_images/cas_logo.png" src="_images/cas_logo.png" /> +<div class="section" id="core-analysis-system"> +<h1>Core Analysis System<a class="headerlink" href="#core-analysis-system" title="Permalink to this headline">¶</a></h1> <div class="section" id="introduction"> <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> <div class="section" id="description"> @@ -113,8 +114,8 @@ and CAS will automatically process x86 cores on a x86_64 machine. <tt class="doc is only available if the CAS server is a x86_64 machine.</p> </div> </div> -<div class="section" id="setup"> -<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2> +<div class="section" id="setup-execution"> +<h2>Setup & Execution<a class="headerlink" href="#setup-execution" title="Permalink to this headline">¶</a></h2> <div class="section" id="preparing-cas-server"> <h3>Preparing CAS Server<a class="headerlink" href="#preparing-cas-server" title="Permalink to this headline">¶</a></h3> <p>To install the CAS package simply type:</p> @@ -199,11 +200,134 @@ are provided in either the email or the <tt class="docutils literal"><span class the core.</p> </div> </div> +<div class="section" id="analyzing"> +<h2>Analyzing<a class="headerlink" href="#analyzing" title="Permalink to this headline">¶</a></h2> +<p>Continuing with the previous example the results of CAS processing should be emailed +and look something similar to:</p> +<div class="highlight-python"><pre>Subject: CAS results for 12345 +Date: Wed, 11 Feb 2009 08:44:37 -0500 + +Location: /cores/processed/12345/02.11.09.08.44.19 +Server: test-2.gss.redhat.com +Output data: +PID: 0 TASK: ffffffff803e9b80 CPU: 0 COMMAND: "swapper" + #0 [ffffffff8047a0a0] smp_call_function_interrupt at ffffffff8011d191 + #1 [ffffffff8047a0b0] call_function_interrupt at ffffffff80110bf5 +--- <IRQ stack> --- + #2 [ffffffff80529f08] call_function_interrupt at ffffffff80110bf5 + [exception RIP: default_idle+32] + RIP: ffffffff8010e7a9 RSP: ffffffff80529fb8 RFLAGS: 00000246 + RAX: 0000000000000000 RBX: 0000000000000000 RCX: 0000000000000018 + RDX: ffffffff8010e789 RSI: ffffffff803e9b80 RDI: 0000010008001780 + RBP: 0000000000000000 R8: ffffffff80528000 R9: 0000000000000080 + R10: 0000000000000100 R11: 0000000000000004 R12: 0000000000000000 + R13: 0000000000000000 R14: 0000000000000000 R15: 0000000000000000 + ORIG_RAX: fffffffffffffffa CS: 0010 SS: 0018 + #3 [ffffffff80529fb8] cpu_idle at ffffffff8010e81c + +PID: 0 TASK: 100f57cb030 CPU: 1 COMMAND: "swapper" + #0 [1000107bfa0] smp_call_function_interrupt at ffffffff8011d191 + #1 [1000107bfb0] call_function_interrupt at ffffffff80110bf5 +--- <IRQ stack> --- + #2 [10001073e98] call_function_interrupt at ffffffff80110bf5 + [exception RIP: default_idle+32] + RIP: ffffffff8010e7a9 RSP: 0000010001073f48 RFLAGS: 00000246 + RAX: 0000000000000000 RBX: 0000000000000e86 RCX: 0000000000000018 + RDX: ffffffff8010e789 RSI: 00000100f57cb030 RDI: 00000102000a4780 + RBP: 0000000000000001 R8: 0000010001072000 R9: 0000000000000040 + R10: 0000000000000000 R11: 0000000000000008 R12: 0000000000000000 + R13: 0000000000000000 R14: 0000000000000000 R15: 0000000000000000 + ORIG_RAX: fffffffffffffffa CS: 0010 SS: 0018 + #3 [10001073f48] cpu_idle at ffffffff8010e81c + +PID: 6122 TASK: 101f3658030 CPU: 2 COMMAND: "gfs_quotad" + #0 [101f21efb20] start_disk_dump at ffffffffa03183ff + #1 [101f21efb50] try_crashdump at ffffffff8014cc1d + #2 [101f21efb60] die at ffffffff80111c90 + #3 [101f21efb80] do_invalid_op at ffffffff80112058 + #4 [101f21efc40] error_exit at ffffffff80110e1d + [exception RIP: do_dlm_lock+366] + +... snip ...</pre> +</div> +<p>From this email a <tt class="docutils literal"><span class="pre">location</span></tt> is provided <tt class="docutils literal"><span class="pre">/cores/processed/12345/02.11.09.08.44.19</span></tt> +and the server in which further analyzation can be continued <tt class="docutils literal"><span class="pre">test-2.gss.redhat.com</span></tt>.</p> +<p>Normally from a support perspective this email should contain enough information +for a kernel engineer to begin debugging the problem. Assuming more is needed +the information provided previously will prove beneficial for anyone wishing +to access this data.</p> +<p>Logging into the stated server and changing into the directory defined several +files are presented:</p> +<div class="highlight-python"><pre>$ pwd +/cores/processed/12345/02.11.09.08.44.19 +$ ls +12345.log crash crash.in crash.out usr vmcore.12345</pre> +</div> +<p><tt class="docutils literal"><span class="pre">12345.log</span></tt>: contains any informational messages presented during the processing +of the core. Everything from informational to debug statements are provided here.</p> +<p><tt class="docutils literal"><span class="pre">crash</span></tt>: a script autogenerated to provide an automated way of gathering intial +data from the coredump. <tt class="docutils literal"><span class="pre">Note</span></tt> if wanting to use this crash wrapper in a more +manual approach some alterations to the script need to occur.</p> +<p>crash wrapper in its original form:</p> +<div class="highlight-python"><pre>#!/bin/sh +/usr/bin/crash /cores/processed/12345/02.11.09.08.44.19/vmcore.12345 /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux -s < /cores/processed/12345/02.11.09.08.44.19/crash.in</pre> +</div> +<p>In order to remove automation the redirect from crash.in needs to be removed:</p> +<div class="highlight-python"><pre>#!/bin/sh +/usr/bin/crash /cores/processed/12345/02.11.09.08.44.19/vmcore.12345 /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux</pre> +</div> +<p><strong>Alternative to using the crash wrapper</strong></p> +<p>It is possible to specify the vmlinux and corefile with crash on the command line:</p> +<div class="highlight-python"><pre>$ crash /cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux /cores/processed/12345/02.11.09.08.44.19/vmcore.12345</pre> +</div> +<p><tt class="docutils literal"><span class="pre">crash.in</span></tt>: a list of commands to be read into crash during the automated +analysis:</p> +<div class="highlight-python"><pre>bt -a >>/cores/processed/12345/02.11.09.08.44.19/crash.out +sys >>/cores/processed/12345/02.11.09.08.44.19/crash.out +log >>/cores/processed/12345/02.11.09.08.44.19/crash.out +mod >>/cores/processed/12345/02.11.09.08.44.19/crash.out +exit</pre> +</div> +<p><tt class="docutils literal"><span class="pre">crash.out</span></tt>: output of initial crash analysis and the same data which +is sent in an email if defined.</p> +<p><tt class="docutils literal"><span class="pre">usr</span></tt>: directory structure from the extraction of the vmlinux file +from the associated kernel-debuginfo rpm for use within crash:</p> +<div class="highlight-python"><pre>/cores/processed/12345/02.11.09.08.44.19/usr/lib/debug/lib/modules/2.6.9-78.18.ELlargesmp/vmlinux</pre> +</div> +<p><tt class="docutils literal"><span class="pre">vmcore.12345</span></tt>: corefile from which was either defined or extracted from +a compressed archive during CAS initialization.</p> +</div> +<div class="section" id="troubleshooting"> +<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2> +<p>Some of the major problems that arise when using CAS usually boils down to some +improper usage of the compression and archiving tools.</p> +<p>When compressing a core which may need to be sent over the network to a CAS server +one of the proper ways to do so is:</p> +<div class="highlight-python"><pre>$ tar cvjf vmcore.12345.tar.bz2 vmcore.12345</pre> +</div> +<p>Other various ways of compressing archive are as follows:</p> +<div class="highlight-python"><pre>$ tar cvzf vmcore.tar.gz vmcore +$ gzip vmcore +$ bzip2 vmcore</pre> +</div> +<p><tt class="docutils literal"><span class="pre">Note</span></tt>: please do not double compress or CAS will fail.</p> +<p>Another issue, which isn’t primarily a fault of CAS, are +incomplete or corrupted cores. If either of these occur +there is a chance that CAS will not be able to process +the data needed to associate a debug kernel or do any +sort of automated analysis. Unfortunately, there is not +much that can be done to resolve these sort of issues +other than verifying that the process which happens when +a system coredump and when that dump reaches the +system specified for retrieval is solid and are seeing +no errors.</p> +</div> </div> <div class="section" id="resources"> <h1>Resources<a class="headerlink" href="#resources" title="Permalink to this headline">¶</a></h1> <ul class="simple"> <li><a class="reference external" href="http://fedorahosted.org/cas">CAS Wiki</a></li> +<li><a class="reference external" href="https://fedorahosted.org/cas/wiki/CasFAQ">CAS FAQ</a></li> <li><a class="reference external" href="https://fedorahosted.org/mailman/listinfo/cas">Mailing list</a></li> <li><a class="reference external" href="https://fedorahosted.org/releases/c/a/cas/">Upstream releases</a></li> <li>Checkout latest from Git, <tt class="docutils literal"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">git://git.fedorahosted.org/cas.git</span></tt></li> @@ -218,18 +342,20 @@ the core.</p> <div class="sphinxsidebarwrapper"> <h3><a href="">Table Of Contents</a></h3> <ul> -<li><a class="reference external" href="">Core Analysis System (CAS)</a><ul> +<li><a class="reference external" href="">Core Analysis System</a><ul> <li><a class="reference external" href="#introduction">Introduction</a><ul> <li><a class="reference external" href="#description">Description</a></li> <li><a class="reference external" href="#prerequisites">Prerequisites</a></li> <li><a class="reference external" href="#configuration">Configuration</a></li> </ul> </li> -<li><a class="reference external" href="#setup">Setup</a><ul> +<li><a class="reference external" href="#setup-execution">Setup & Execution</a><ul> <li><a class="reference external" href="#preparing-cas-server">Preparing CAS Server</a></li> <li><a class="reference external" href="#running-cas">Running CAS</a></li> </ul> </li> +<li><a class="reference external" href="#analyzing">Analyzing</a></li> +<li><a class="reference external" href="#troubleshooting">Troubleshooting</a></li> </ul> </li> <li><a class="reference external" href="#resources">Resources</a></li> diff --git a/doc/searchindex.js b/doc/searchindex.js index 6096119..5fd6ed0 100644 --- a/doc/searchindex.js +++ b/doc/searchindex.js @@ -1 +1 @@ -Search.setIndex({desctypes:{},terms:{all:0,identifi:0,help:0,execut:0,show:0,text:0,mnt:0,workdirectori:0,i386:0,abil:0,heavili:0,hierarchi:0,follow:0,disk:0,find:0,paramet:0,content:0,onli:0,samba:0,locat:0,system:0,kernel:0,also:0,configur:0,solut:0,specif:0,should:0,other:0,analyz:0,mail:0,tell:0,main:0,local:0,worth:0,match:0,depend:0,opt:0,crash:0,variou:0,python:0,timestamp:0,overal:0,initi:0,"break":0,mention:0,vmcore:0,upstream:0,ticket:0,now:0,relev:0,requir:0,introduct:0,like:0,organ:0,level:0,edit:0,list:0,authent:0,server:0,easili:0,necessari:0,either:0,have:0,contain:0,debug:0,output:0,architectur:0,where:0,mount:0,mean:0,wiki:0,x86_64:0,set:0,dump:0,some:0,direct:0,emac:0,result:0,pass:0,download:0,further:0,extract:0,tmp:0,shown:0,detect:0,mailserv:0,collect:0,databas:0,section:0,access:0,version:0,listinfo:[],debuglevel:0,determin:0,email:0,machin:0,core:0,assumpt:0,run:0,advanc:0,gener:0,each:0,usag:0,given:0,here:0,job:0,base:0,prerequisit:0,address:0,releas:0,org:0,come:0,sinc:0,valu:0,popul:0,sub:0,last:0,"500gb":0,admin:0,current:0,http:[],keep:0,vmlinux:0,etc:0,instanc:0,yum:0,includ:0,mani:0,typic:0,com:0,assign:0,first:0,load:0,rang:0,via:0,simpli:0,repositori:0,primarili:0,point:0,onc:0,modul:0,within:0,prefer:0,number:0,automat:0,crash_32:0,down:0,filenam:0,instruct:0,least:0,path:0,instal:0,next:0,storag:0,size:0,differ:0,git:0,mailman:[],describ:0,would:0,area:0,associ:0,question:0,two:0,messag:0,mark:0,avail:0,few:0,editor:0,rpm:0,recommend:0,hassl:0,addit:0,type:0,"final":0,store:0,rhel:0,files:0,media:0,from:0,properli:0,option:0,name:0,debuginfo:0,smtp:0,suit:0,thei:0,specifi:0,ani:0,administr:0,"var":0,"1tb":0,func:0,exactli:0,analyst:0,those:0,must:0,info:0,made:0,look:0,hous:0,provid:0,checkout:0,setup:0,work:0,uniqu:0,alter:0,defin:0,below:0,can:0,abov:0,visit:0,quickli:0,root:0,epel:0,timefram:0,later:0,conf:0,process:0,certain:0,dure:0,arg:0,share:0,anywher:0,accept:0,packag:0,exit:0,exist:0,uncom:0,file:0,need:0,fedorahost:0,sever:0,fill:0,queue:0,multipl:0,form:0,want:0,thing:0,suggest:0,user:0,when:0,same:0,note:0,how:0,valid:0,statement:0,build:0,which:0,command:0,eventu:0,prepar:0,enabl:0,analysi:0,therefor:0,express:0,resourc:0,x86:0,corefil:0,clone:0,who:0,what:0,reflect:0,most:0,regular:0,temporari:0,log:0,deploi:0,usr:0,data:0,fedora:0,repo:0,task:0,essenti:0,binari:0,filesystem:0,directori:0,gather:0,descript:0,issu:0,inform:0,exampl:0,environ:0,place:0,thi:0,anoth:0,rpmfilter:0,order:0,latest:0},titles:["Core Analysis System (CAS)"],modules:{},descrefs:{},filenames:["index"]}) \ No newline at end of file +Search.setIndex({desctypes:{},terms:{all:0,mnt:0,snip:0,abil:0,follow:0,disk:0,depend:0,do_dlm_lock:0,those:0,aris:0,worth:0,sent:0,r14:0,r15:0,r12:0,r13:0,r10:0,r11:0,faq:0,ffffffff8010e789:0,vmcore:0,upstream:0,ticket:0,relev:0,administr:0,level:0,die:0,list:0,setup:0,pleas:0,x86_64:0,intial:0,direct:0,pass:0,download:0,further:0,what:0,sub:0,section:0,abl:0,access:0,version:0,autogener:0,gener:0,here:0,address:0,path:0,sinc:0,valu:0,ffffffff80110bf5:0,rdx:0,queue:0,typic:0,rdi:0,smp_call_function_interrupt:0,chanc:0,"0000010001073f48":0,via:0,repositori:0,modul:0,prefer:0,crash_32:0,filenam:0,instal:0,feb:0,describ:0,would:0,prove:0,doubl:0,visit:0,two:0,next:0,few:0,rhel:0,recommend:0,type:0,tell:0,more:0,sort:0,wrapper:0,smtp:0,ffffffff803e9b80:0,ffffffff8010e81c:0,must:0,retriev:0,hous:0,prepar:0,work:0,uniqu:0,can:0,root:0,tar:0,process:0,share:0,accept:0,want:0,occur:0,multipl:0,anoth:0,how:0,error_exit:0,anyon:0,verifi:0,perspect:0,ffffffff80528000:0,resourc:0,"00000102000a4780":0,clone:0,reflect:0,mai:0,data:0,fedora:0,essenti:0,issu:0,inform:0,environ:0,media:0,order:0,help:0,over:0,major:0,i386:0,hierarchi:0,paramet:0,"100f57cb030":0,ellargesmp:0,bin:0,mail:0,main:0,alter:0,crash:0,than:0,python:0,timestamp:0,overal:0,initi:0,number:0,"break":0,mention:0,now:0,introduct:0,name:0,edit:0,troubleshoot:0,authent:0,easili:0,each:0,debug:0,mean:0,continu:0,happen:0,extract:0,out:0,shown:0,network:0,ffffffff8014cc1d:0,ffffffff8011d191:0,content:0,fffffffffffffffa:0,advanc:0,orig_rax:0,given:0,base:0,releas:0,org:0,ffffffff80110e1d:0,keep:0,vmlinux:0,thing:0,yum:0,isn:0,assign:0,first:0,origin:0,rang:0,redhat:0,onc:0,debuglevel:0,swapper:0,instruct:0,done:0,least:0,rflag:0,size:0,differ:0,script:0,associ:0,system:0,messag:0,ffffffff80112058:0,statement:0,ffffffff8047a0a0:0,"final":0,boil:0,editor:0,option:0,debuginfo:0,tool:0,specifi:0,"var":0,exactli:0,rsp:0,corefil:0,provid:0,remov:0,emac:0,structur:0,store:0,analysi:0,anywher:0,packag:0,have:0,call_function_interrupt:0,"101f3658030":0,rax:0,rsi:0,date:0,bz2:0,lib:0,note:0,also:0,build:0,which:0,begin:0,normal:0,previou:0,compress:0,most:0,regular:0,deploi:0,everyth:0,"101f21efb80":0,gather:0,place:0,determin:0,irq:0,latest:0,show:0,text:0,find:0,redirect:0,current:0,onli:0,locat:0,configur:0,solut:0,state:0,should:0,analyz:0,local:0,variou:0,cvjf:0,express:0,autom:0,repo:0,requir:0,enabl:0,organ:0,contain:0,where:0,wiki:0,kernel:0,set:0,dump:0,"10001073f48":0,see:0,result:0,arg:0,corrupt:0,subject:0,ffffffffa03183ff:0,detect:0,databas:0,someth:0,enough:0,listinfo:[],approach:0,email:0,altern:0,assumpt:0,cpu_idl:0,default_idl:0,job:0,come:0,addit:0,last:0,admin:0,fault:0,etc:0,instanc:0,mani:0,com:0,improp:0,load:0,simpli:0,point:0,"1000107bfb0":0,rpm:0,mailman:[],coredump:0,"101f21efb50":0,mark:0,much:0,popul:0,quickli:0,wish:0,ani:0,try_crashdump:0,"0000000000000e86":0,func:0,present:0,therefor:0,look:0,rbx:0,solid:0,mount:0,rbp:0,defin:0,abov:0,error:0,"101f21efb20":0,ffffffff8047a0b0:0,timefram:0,rip:0,need:0,archiv:0,uncom:0,conf:0,fedorahost:0,sever:0,thei:0,suggest:0,same:0,binari:0,eventu:0,http:[],x86:0,temporari:0,user:0,"500gb":0,engin:0,stack:0,gss:0,task:0,"10001073e98":0,do_invalid_op:0,exampl:0,command:0,thi:0,filesystem:0,gzip:0,fail:0,usual:0,identifi:0,execut:0,workdirectori:0,heavili:0,previous:0,samba:0,wed:0,except:0,other:0,match:0,opt:0,read:0,mod:0,"1000107bfa0":0,like:0,specif:0,manual:0,resolv:0,server:0,collect:0,necessari:0,either:0,"101f21efb60":0,"101f21efc40":0,output:0,some:0,gfs_quotad:0,proper:0,tmp:0,mailserv:0,assum:0,ffffffff80529f08:0,exit:0,machin:0,core:0,who:0,run:0,reach:0,usag:0,prerequisit:0,from:0,unfortun:0,primarili:0,within:0,automat:0,down:0,chang:0,start_disk_dump:0,storag:0,git:0,rcx:0,log:0,wai:0,area:0,support:0,question:0,avail:0,includ:0,suit:0,hassl:0,usr:0,files:0,properli:0,form:0,pwd:0,line:0,analyst:0,info:0,made:0,possibl:0,checkout:0,below:0,ffffffff80111c90:0,problem:0,similar:0,epel:0,later:0,certain:0,dure:0,pid:0,incomplet:0,exist:0,file:0,cvzf:0,fill:0,bzip2:0,"00000100f57cb030":0,when:0,valid:0,test:0,ffffffff8010e7a9:0,architectur:0,benefici:0,ffffffff80529fb8:0,directori:0,descript:0,"1tb":0,rpmfilter:0,cpu:0},titles:["Core Analysis System"],modules:{},descrefs:{},filenames:["index"]}) \ No newline at end of file

1 0

cas.spec doc/genindex.html doc/index.html doc/objects.inv doc/search.html doc/searchindex.js doc/_sources doc/_static MANIFEST.in
by Adam Stokes 11 Feb '09

11 Feb '09

MANIFEST.in | 1 cas.spec | 7 doc/_sources/index.txt | 201 ++++++++++++ doc/_static/contents.png |binary doc/_static/default.css | 657 +++++++++++++++++++++++++++++++++++++++ doc/_static/doctools.js | 232 +++++++++++++ doc/_static/file.png |binary doc/_static/jquery.js | 32 + doc/_static/minus.png |binary doc/_static/navigation.png |binary doc/_static/plus.png |binary doc/_static/pygments.css | 61 +++ doc/_static/rightsidebar.css | 16 doc/_static/searchtools.js | 467 ++++++++++++++++++++++++++++ doc/_static/sphinxdoc.css | 557 +++++++++++++++++++++++++++++++++ doc/_static/stickysidebar.css | 19 + doc/_static/traditional.css | 700 ++++++++++++++++++++++++++++++++++++++++++ doc/genindex.html | 81 ++++ doc/index.html | 266 +++++++++++++++ doc/objects.inv | 3 doc/search.html | 83 ++++ doc/searchindex.js | 1 22 files changed, 3382 insertions(+), 2 deletions(-) New commits: commit 1aacf3012ce6257d9e4471300ebde845f7e937a9 Author: Adam Stokes <uzr(a)rambos.knife> Date: Wed Feb 11 08:30:17 2009 -0500 - proper documentation added. diff --git a/MANIFEST.in b/MANIFEST.in index ab1c592..a035605 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -3,3 +3,4 @@ include cas.1.gz include cas-admin.1.gz include LICENSE include README +recursive-include doc * diff --git a/cas.spec b/cas.spec index b0ab6ef..e463724 100644 --- a/cas.spec +++ b/cas.spec @@ -3,7 +3,7 @@ Name: cas Summary: Tool to analyze and configure core file environment Version: 0.13 -Release: 118%{?dist} +Release: 120%{?dist} Source0: https://fedorahosted.org/releases/c/a/cas/%{name}-%{version}.tar.gz License: GPLv3+ Group: Development/Libraries @@ -39,9 +39,12 @@ rm -rf ${RPM_BUILD_ROOT} %{python_sitelib}/* %{_mandir}/man1/cas.1.gz %{_mandir}/man1/cas-admin.1.gz -%doc LICENSE README PKG-INFO +%doc LICENSE README PKG-INFO doc/* %changelog +* Wed Feb 11 2009 Adam Stokes <ajs at redhat dot com> - 0.13-120 +- added proper documentation + * Wed Jan 7 2009 Adam Stokes <ajs at redhat dot com> - 0.13-116 - support for extracting kernel modules - support for analyzing x86 cores on x86_64 system diff --git a/doc/_sources/index.txt b/doc/_sources/index.txt new file mode 100644 index 0000000..aac3fcb --- /dev/null +++ b/doc/_sources/index.txt @@ -0,0 +1,201 @@ +Core Analysis System (CAS) +========================== + +Introduction +------------ + +Description +^^^^^^^^^^^ + +CAS provides a user the ability to configure an environment for core analysis +quickly. All the hassles of matching kernel versions and machine architecture +types to core dumps are automatically detected and processed. + +Prerequisites +^^^^^^^^^^^^^ + +CAS needs at least **Python 2.4** to run. For systems that are not running +Fedora 9 or later (this would include RHEL 4/5) the EPEL repo needs to be +installed. Visit `EPEL <https://fedoraproject.org/wiki/EPEL>`_ to enable +this repository. + +Optionally install `Func <http://fedorahosted.org/func>`_ +for automatic processing on other architecture specific systems. This +can easily be installed via `yum`:: + + $ yum install func + +Storage size can be determined based on how many kernel-debuginfo to be stored +and how many core dumps and their filesize will be processed. Typically, it is +recommended for at least 1TB for cores and another 500GB for debuginfo's. + +Since analyzing cores requires the same architecture specific systems the core +was generated on there will need to be systems available of those same types +in order for analyzation to work properly. + +Finally, root access to the CAS server. + +Configuration +^^^^^^^^^^^^^ + +CAS comes with one main configuration file which is located at ``/etc/cas.conf``. +The overall contents of this file is shown below, further down we will break up +each section and describe its meaning:: + + [settings] + kernels=/mnt/kernels + rpms=/var/db/cas/rpms.db + rpmFilter=.*kernel-debuginfo-[0-9].*\.rpm + debugs=/cores/debugs + debugLevel=DEBUG + workDirectory=/cores/processed + servers=/var/db/cas/servers.db + jobs=/var/db/cas/jobs.db + mailServer=mail.example.com + [advanced] + # crash_32=/usr/local/i386/crash + +``kernels``: (**Required**) Describes the location of where kernel-debuginfo packages are to be +stored. This can range anywhere from an nfs mount, samba share, local disk or +any other type of media the cas server can access. + +``rpms``: (**Required**) Database which houses the processing of kernel-debuginfo and stores the +necessary information for CAS to properly match core dumps. + +``rpmFilters``: (**Required**) This is a emacs based regular expression which is essentially +passed to a find command to locate the various kernel-debuginfo packages defined +in ``kernels`` directive. + +``debugs``: (**Required**) A temporary directory in which to store the extracted vmlinux files +from the kernel-debuginfo packages for processing. Another solution would be to +alter this to point an existing directory like ``/tmp``, for instance. + +``debugLevel``: As the name suggest it will set the debug level for CAS output. +Currently the only accepted values are ``DEBUG|INFO``. + +``workDirectory``: (**Required**) Defines where all processed cores will be placed. This mount +point will need to have the most storage assigned to it. Depending on how many +cores are processed in a given timeframe this area will fill up quickly. + +``servers``: If func is installed and configured all associated servers will +be stored here. + +``jobs``: Contains information on current jobs being processed and eventually +what jobs are in the queue. + +``mailServer``: If wanting output of CAS processing email to a certain address +this directive needs to be set. ``Note`` that the mail server should not +require smtp authentication. + +``crash_32``: Primarily used on x86_64 systems to process x86 cores. If x86 +version of crash is installed this directive can be set to the crash binary +and CAS will automatically process x86 cores on a x86_64 machine. ``Note`` this +is only available if the CAS server is a x86_64 machine. + +Setup +----- + +Preparing CAS Server +^^^^^^^^^^^^^^^^^^^^ + +To install the CAS package simply type:: + + $ yum install cas + +Once installed edit ``/etc/cas.conf`` as root using any preferred text editor. +As described above the required directives need to be altered to suit the +environment in question. + +In this example, ``/mnt/kernels`` is an nfs mount which houses the kernel-debuginfo +packages. ``/cores`` is where all processed cores are stored and ``/tmp`` is the +temporary storage for collecting the necessary data from the kernel-debuginfos. +A mail server is setup within the environment to email CAS results and this +optional directive is shown to reflect that. Finally, the CAS server is an x86_64 +machine and the environment will be processing x86 cores, therefore, the directive +for this is uncommented and path to the x86 crash binary is given. ``Note`` there +is information provided within the configuration file for installing the x86 crash +to a different location. + +Altering the configuration to reflect the above assumptions would show the +following:: + + [settings] + kernels=/mnt/kernels + rpms=/var/db/cas/rpms.db + rpmFilter=.*kernel-debuginfo-[0-9].*\.rpm + debugs=/tmp + debugLevel=DEBUG + workDirectory=/cores + servers=/var/db/cas/servers.db + jobs=/var/db/cas/jobs.db + mailServer=mail.cas-server.com + [advanced] + crash_32=/usr/local/i386/crash + +Now that the configuration file is altered and ``/mnt/kernels`` should be populated +with kernel-debuginfo rpm's the next section will describe running CAS. + +Running CAS +^^^^^^^^^^^ + +First, one or two administrative tasks need to be run. The required task is to build +a database for all the data gathered from the kernel-debuginfo packages.:: + + $ cas-admin -b + +If ``Func`` is installed and several systems are deployed for CAS to use run:: + + $ cas-admin -s + +At this point CAS is configured and looking at the output of CAS help there are +a few options to pass:: + + Usage: cas [opts] args + + Options: + -h, --help show this help message and exit + -i IDENTIFIER, --identifier=IDENTIFIER + Unique ID for core + -f FILENAME, --file=FILENAME + Filename + -e EMAIL, --email=EMAIL + Define email for results (must be valid!) + -m, --modules Extract associated kernel modules + +CAS prepares its directory hierarchy based on the ``identifier`` this option is +therefore required. ``filename`` is also required as it tells CAS exactly which +core to process and associate with ``identifier``. If wanting email results from +CAS simply pass it the email parameter. + +An example, of a user wanting to process a corefile named ``vmcore.12345``:: + + $ cas -i 12345 -f vmcore.12345 -e user(a)cas-server.com + +In the above example an assumption is made that ``12345`` is associated to some +form of ticketing system so to keep things organized an identifier was set of +that number. + +The directory hierarchy for the current job should look like ``/cores/12345``. +In addition to the processing of core files there is also a ``process log`` contained +within this directory for each job processed. If multiple jobs for the same identifier +are issued they are placed within a sub directory marked by the current timestamp +and the relevant data associated with it. + +The last option worth mentioning is for core analyst who are needing to work +within the core that requires one of the kernel modules loaded during the crash. +This can be extracted by passing the ``modules`` parameter in the CAS execution +statement. ``Note`` the ``modules`` parameter is not heavily used but can be +useful when analyzing filesystem issues and the like. + +From this point on CAS will download, process, and email the results of its +initial analysis to the specified email address. From there further instructions +are provided in either the email or the ``process log`` on how to access and analyze +the core. + +Resources +========= + +* `CAS Wiki <http://fedorahosted.org/cas>`_ +* `Mailing list <https://fedorahosted.org/mailman/listinfo/cas>`_ +* `Upstream releases <https://fedorahosted.org/releases/c/a/cas/>`_ +* Checkout latest from Git, ``git clone git://git.fedorahosted.org/cas.git`` diff --git a/doc/_static/contents.png b/doc/_static/contents.png new file mode 100644 index 0000000..7fb8215 Binary files /dev/null and b/doc/_static/contents.png differ diff --git a/doc/_static/default.css b/doc/_static/default.css new file mode 100644 index 0000000..005caa1 --- /dev/null +++ b/doc/_static/default.css @@ -0,0 +1,657 @@ +/** + * Sphinx Doc Design + */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +/* :::: LAYOUT :::: */ + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: white; + padding: 0 20px 30px 20px; +} + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.clearer { + clear: both; +} + +div.footer { + color: #fff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #fff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + color: #fff; + width: 100%; + line-height: 30px; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +div.related a { + color: white; +} + +/* ::: TOC :::: */ +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: white; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: white; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: white; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: white; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + list-style: none; + color: white; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +/* :::: MODULE CLOUD :::: */ +div.modulecloud { + margin: -5px 10px 5px 10px; + padding: 10px; + line-height: 160%; + border: 1px solid #cbe7e5; + background-color: #f2fbfd; +} + +div.modulecloud a { + padding: 0 5px 0 5px; +} + +/* :::: SEARCH :::: */ +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* :::: COMMON FORM STYLES :::: */ + +div.actions { + padding: 5px 10px 5px 10px; + border-top: 1px solid #cbe7e5; + border-bottom: 1px solid #cbe7e5; + background-color: #e0f6f4; +} + +form dl { + color: #333; +} + +form dt { + clear: both; + float: left; + min-width: 110px; + margin-right: 10px; + padding-top: 2px; +} + +input#homepage { + display: none; +} + +div.error { + margin: 5px 20px 0 0; + padding: 5px; + border: 1px solid #d00; + font-weight: bold; +} + +/* :::: INDEX PAGE :::: */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* :::: INDEX STYLES :::: */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +form.pfform { + margin: 10px 0 20px 0; +} + +/* :::: GLOBAL STYLES :::: */ + +.docwarning { + background-color: #ffe4e4; + padding: 10px; + margin: 0 -20px 0 -20px; + border-bottom: 1px solid #f66; +} + +p.subhead { + font-weight: bold; + margin-top: 20px; +} + +a { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +ul.fakelist { + list-style: none; + margin: 10px 0 10px 20px; + padding: 0; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +/* "Footnotes" heading */ +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* Sidebars */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* "Topics" */ + +div.topic { + background-color: #eee; + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* Admonitions */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +table.docutils { + border: 0; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +dl { + margin-bottom: 15px; + clear: both; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.refcount { + color: #060; +} + +dt:target, +.highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +th { + text-align: left; + padding-right: 5px; +} + +pre { + padding: 5px; + background-color: #efc; + color: #333; + border: 1px solid #ac9; + border-left: none; + border-right: none; + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +.footnote:target { background-color: #ffa } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +form.comment { + margin: 0; + padding: 10px 30px 10px 30px; + background-color: #eee; +} + +form.comment h3 { + background-color: #326591; + color: white; + margin: -10px -30px 10px -30px; + padding: 5px; + font-size: 1.4em; +} + +form.comment input, +form.comment textarea { + border: 1px solid #ccc; + padding: 2px; + font-family: sans-serif; + font-size: 100%; +} + +form.comment input[type="text"] { + width: 240px; +} + +form.comment textarea { + width: 100%; + height: 200px; + margin-bottom: 10px; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +img.math { + vertical-align: middle; +} + +div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +img.logo { + border: 0; +} + +/* :::: PRINT :::: */ +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0; + width : 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + div#comments div.new-comment-box, + #top-link { + display: none; + } +} diff --git a/doc/_static/doctools.js b/doc/_static/doctools.js new file mode 100644 index 0000000..be4bdc8 --- /dev/null +++ b/doc/_static/doctools.js @@ -0,0 +1,232 @@ +/// XXX: make it cross browser + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger + */ +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", "dirxml", + "group", "groupEnd", "time", "timeEnd", "count", "trace", "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {} +} + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +} + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +} + +/** + * small function to check if an array contains + * a given item. + */ +jQuery.contains = function(arr, item) { + for (var i = 0; i < arr.length; i++) { + if (arr[i] == item) + return true; + } + return false; +} + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery.className.has(node.parentNode, className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this) + }); + } + } + return this.each(function() { + highlight(this); + }); +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initModIndex(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can savely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[@id] > :header:first').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[@id]').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlight'); + }); + }, 10); + $('<li class="highlight-link"><a href="javascript:Documentation.' + + 'hideSearchWords()">' + _('Hide Search Matches') + '</a></li>') + .appendTo($('.sidebar .this-page-menu')); + } + }, + + /** + * init the modindex toggle buttons + */ + initModIndex : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + console.log($('tr.cg-' + idnum).toggle()); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_MODINDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('.sidebar .this-page-menu li.highlight-link').fadeOut(300); + $('span.highlight').removeClass('highlight'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/doc/_static/file.png b/doc/_static/file.png new file mode 100644 index 0000000..d18082e Binary files /dev/null and b/doc/_static/file.png differ diff --git a/doc/_static/jquery.js b/doc/_static/jquery.js new file mode 100644 index 0000000..82b98e1 --- /dev/null +++ b/doc/_static/jquery.js @@ -0,0 +1,32 @@ +/* + * jQuery 1.2.6 - New Wave Javascript + * + * Copyright (c) 2008 John Resig (jquery.com) + * Dual licensed under the MIT (MIT-LICENSE.txt) + * and GPL (GPL-LICENSE.txt) licenses. + * + * $Date: 2008-05-24 14:22:17 -0400 (Sat, 24 May 2008) $ + * $Rev: 5685 $ + */ +(function(){var _jQuery=window.jQuery,_$=window.$;var jQuery=window.jQuery=window.$=function(selector,context){return new jQuery.fn.init(selector,context);};var quickExpr=/^[^<]*(<(.|\s)+>)[^>]*$|^#(\w+)$/,isSimple=/^.[^:#\[\.]*$/,undefined;jQuery.fn=jQuery.prototype={init:function(selector,context){selector=selector||document;if(selector.nodeType){this[0]=selector;this.length=1;return this;}if(typeof selector=="string"){var match=quickExpr.exec(selector);if(match&&(match[1]||!context)){if(match[1])selector=jQuery.clean([match[1]],context);else{var elem=document.getElementById(match[3]);if(elem){if(elem.id!=match[3])return jQuery().find(selector);return jQuery(elem);}selector=[];}}else +return jQuery(context).find(selector);}else if(jQuery.isFunction(selector))return jQuery(document)[jQuery.fn.ready?"ready":"load"](selector);return this.setArray(jQuery.makeArray(selector));},jquery:"1.2.6",size:function(){return this.length;},length:0,get:function(num){return num==undefined?jQuery.makeArray(this):this[num];},pushStack:function(elems){var ret=jQuery(elems);ret.prevObject=this;return ret;},setArray:function(elems){this.length=0;Array.prototype.push.apply(this,elems);return this;},each:function(callback,args){return jQuery.each(this,callback,args);},index:function(elem){var ret=-1;return jQuery.inArray(elem&&elem.jquery?elem[0]:elem,this);},attr:function(name,value,type){var options=name;if(name.constructor==String)if(value===undefined)return this[0]&&jQuery[type||"attr"](this[0],name);else{options={};options[name]=value;}return this.each(function(i){for(name in options)jQuery.attr(type?this.style:this,name,jQuery.prop(this,options[name],type,i,name));});},css:function(key,value){if((key=='width'||key=='height')&&parseFloat(value)<0)value=undefined;return this.attr(key,value,"curCSS");},text:function(text){if(typeof text!="object"&&text!=null)return this.empty().append((this[0]&&this[0].ownerDocument||document).createTextNode(text));var ret="";jQuery.each(text||this,function(){jQuery.each(this.childNodes,function(){if(this.nodeType!=8)ret+=this.nodeType!=1?this.nodeValue:jQuery.fn.text([this]);});});return ret;},wrapAll:function(html){if(this[0])jQuery(html,this[0].ownerDocument).clone().insertBefore(this[0]).map(function(){var elem=this;while(elem.firstChild)elem=elem.firstChild;return elem;}).append(this);return this;},wrapInner:function(html){return this.each(function(){jQuery(this).contents().wrapAll(html);});},wrap:function(html){return this.each(function(){jQuery(this).wrapAll(html);});},append:function(){return this.domManip(arguments,true,false,function(elem){if(this.nodeType==1)this.appendChild(elem);});},prepend:function(){return this.domManip(arguments,true,true,function(elem){if(this.nodeType==1)this.insertBefore(elem,this.firstChild);});},before:function(){return this.domManip(arguments,false,false,function(elem){this.parentNode.insertBefore(elem,this);});},after:function(){return this.domManip(arguments,false,true,function(elem){this.parentNode.insertBefore(elem,this.nextSibling);});},end:function(){return this.prevObject||jQuery([]);},find:function(selector){var elems=jQuery.map(this,function(elem){return jQuery.find(selector,elem);});return this.pushStack(/[^+>] [^+>]/.test(selector)||selector.indexOf("..")>-1?jQuery.unique(elems):elems);},clone:function(events){var ret=this.map(function(){if(jQuery.browser.msie&&!jQuery.isXMLDoc(this)){var clone=this.cloneNode(true),container=document.createElement("div");container.appendChild(clone);return jQuery.clean([container.innerHTML])[0];}else +return this.cloneNode(true);});var clone=ret.find("*").andSelf().each(function(){if(this[expando]!=undefined)this[expando]=null;});if(events===true)this.find("*").andSelf().each(function(i){if(this.nodeType==3)return;var events=jQuery.data(this,"events");for(var type in events)for(var handler in events[type])jQuery.event.add(clone[i],type,events[type][handler],events[type][handler].data);});return ret;},filter:function(selector){return this.pushStack(jQuery.isFunction(selector)&&jQuery.grep(this,function(elem,i){return selector.call(elem,i);})||jQuery.multiFilter(selector,this));},not:function(selector){if(selector.constructor==String)if(isSimple.test(selector))return this.pushStack(jQuery.multiFilter(selector,this,true));else +selector=jQuery.multiFilter(selector,this);var isArrayLike=selector.length&&selector[selector.length-1]!==undefined&&!selector.nodeType;return this.filter(function(){return isArrayLike?jQuery.inArray(this,selector)<0:this!=selector;});},add:function(selector){return this.pushStack(jQuery.unique(jQuery.merge(this.get(),typeof selector=='string'?jQuery(selector):jQuery.makeArray(selector))));},is:function(selector){return!!selector&&jQuery.multiFilter(selector,this).length>0;},hasClass:function(selector){return this.is("."+selector);},val:function(value){if(value==undefined){if(this.length){var elem=this[0];if(jQuery.nodeName(elem,"select")){var index=elem.selectedIndex,values=[],options=elem.options,one=elem.type=="select-one";if(index<0)return null;for(var i=one?index:0,max=one?index+1:options.length;i<max;i++){var option=options[i];if(option.selected){value=jQuery.browser.msie&&!option.attributes.value.specified?option.text:option.value;if(one)return value;values.push(value);}}return values;}else +return(this[0].value||"").replace(/\r/g,"");}return undefined;}if(value.constructor==Number)value+='';return this.each(function(){if(this.nodeType!=1)return;if(value.constructor==Array&&/radio|checkbox/.test(this.type))this.checked=(jQuery.inArray(this.value,value)>=0||jQuery.inArray(this.name,value)>=0);else if(jQuery.nodeName(this,"select")){var values=jQuery.makeArray(value);jQuery("option",this).each(function(){this.selected=(jQuery.inArray(this.value,values)>=0||jQuery.inArray(this.text,values)>=0);});if(!values.length)this.selectedIndex=-1;}else +this.value=value;});},html:function(value){return value==undefined?(this[0]?this[0].innerHTML:null):this.empty().append(value);},replaceWith:function(value){return this.after(value).remove();},eq:function(i){return this.slice(i,i+1);},slice:function(){return this.pushStack(Array.prototype.slice.apply(this,arguments));},map:function(callback){return this.pushStack(jQuery.map(this,function(elem,i){return callback.call(elem,i,elem);}));},andSelf:function(){return this.add(this.prevObject);},data:function(key,value){var parts=key.split(".");parts[1]=parts[1]?"."+parts[1]:"";if(value===undefined){var data=this.triggerHandler("getData"+parts[1]+"!",[parts[0]]);if(data===undefined&&this.length)data=jQuery.data(this[0],key);return data===undefined&&parts[1]?this.data(parts[0]):data;}else +return this.trigger("setData"+parts[1]+"!",[parts[0],value]).each(function(){jQuery.data(this,key,value);});},removeData:function(key){return this.each(function(){jQuery.removeData(this,key);});},domManip:function(args,table,reverse,callback){var clone=this.length>1,elems;return this.each(function(){if(!elems){elems=jQuery.clean(args,this.ownerDocument);if(reverse)elems.reverse();}var obj=this;if(table&&jQuery.nodeName(this,"table")&&jQuery.nodeName(elems[0],"tr"))obj=this.getElementsByTagName("tbody")[0]||this.appendChild(this.ownerDocument.createElement("tbody"));var scripts=jQuery([]);jQuery.each(elems,function(){var elem=clone?jQuery(this).clone(true)[0]:this;if(jQuery.nodeName(elem,"script"))scripts=scripts.add(elem);else{if(elem.nodeType==1)scripts=scripts.add(jQuery("script",elem).remove());callback.call(obj,elem);}});scripts.each(evalScript);});}};jQuery.fn.init.prototype=jQuery.fn;function evalScript(i,elem){if(elem.src)jQuery.ajax({url:elem.src,async:false,dataType:"script"});else +jQuery.globalEval(elem.text||elem.textContent||elem.innerHTML||"");if(elem.parentNode)elem.parentNode.removeChild(elem);}function now(){return+new Date;}jQuery.extend=jQuery.fn.extend=function(){var target=arguments[0]||{},i=1,length=arguments.length,deep=false,options;if(target.constructor==Boolean){deep=target;target=arguments[1]||{};i=2;}if(typeof target!="object"&&typeof target!="function")target={};if(length==i){target=this;--i;}for(;i<length;i++)if((options=arguments[i])!=null)for(var name in options){var src=target[name],copy=options[name];if(target===copy)continue;if(deep&&copy&&typeof copy=="object"&&!copy.nodeType)target[name]=jQuery.extend(deep,src||(copy.length!=null?[]:{}),copy);else if(copy!==undefined)target[name]=copy;}return target;};var expando="jQuery"+now(),uuid=0,windowData={},exclude=/z-?index|font-?weight|opacity|zoom|line-?height/i,defaultView=document.defaultView||{};jQuery.extend({noConflict:function(deep){window.$=_$;if(deep)window.jQuery=_jQuery;return jQuery;},isFunction:function(fn){return!!fn&&typeof fn!="string"&&!fn.nodeName&&fn.constructor!=Array&&/^[\s[]?function/.test(fn+"");},isXMLDoc:function(elem){return elem.documentElement&&!elem.body||elem.tagName&&elem.ownerDocument&&!elem.ownerDocument.body;},globalEval:function(data){data=jQuery.trim(data);if(data){var head=document.getElementsByTagName("head")[0]||document.documentElement,script=document.createElement("script");script.type="text/javascript";if(jQuery.browser.msie)script.text=data;else +script.appendChild(document.createTextNode(data));head.insertBefore(script,head.firstChild);head.removeChild(script);}},nodeName:function(elem,name){return elem.nodeName&&elem.nodeName.toUpperCase()==name.toUpperCase();},cache:{},data:function(elem,name,data){elem=elem==window?windowData:elem;var id=elem[expando];if(!id)id=elem[expando]=++uuid;if(name&&!jQuery.cache[id])jQuery.cache[id]={};if(data!==undefined)jQuery.cache[id][name]=data;return name?jQuery.cache[id][name]:id;},removeData:function(elem,name){elem=elem==window?windowData:elem;var id=elem[expando];if(name){if(jQuery.cache[id]){delete jQuery.cache[id][name];name="";for(name in jQuery.cache[id])break;if(!name)jQuery.removeData(elem);}}else{try{delete elem[expando];}catch(e){if(elem.removeAttribute)elem.removeAttribute(expando);}delete jQuery.cache[id];}},each:function(object,callback,args){var name,i=0,length=object.length;if(args){if(length==undefined){for(name in object)if(callback.apply(object[name],args)===false)break;}else +for(;i<length;)if(callback.apply(object[i++],args)===false)break;}else{if(length==undefined){for(name in object)if(callback.call(object[name],name,object[name])===false)break;}else +for(var value=object[0];i<length&&callback.call(value,i,value)!==false;value=object[++i]){}}return object;},prop:function(elem,value,type,i,name){if(jQuery.isFunction(value))value=value.call(elem,i);return value&&value.constructor==Number&&type=="curCSS"&&!exclude.test(name)?value+"px":value;},className:{add:function(elem,classNames){jQuery.each((classNames||"").split(/\s+/),function(i,className){if(elem.nodeType==1&&!jQuery.className.has(elem.className,className))elem.className+=(elem.className?" ":"")+className;});},remove:function(elem,classNames){if(elem.nodeType==1)elem.className=classNames!=undefined?jQuery.grep(elem.className.split(/\s+/),function(className){return!jQuery.className.has(classNames,className);}).join(" "):"";},has:function(elem,className){return jQuery.inArray(className,(elem.className||elem).toString().split(/\s+/))>-1;}},swap:function(elem,options,callback){var old={};for(var name in options){old[name]=elem.style[name];elem.style[name]=options[name];}callback.call(elem);for(var name in options)elem.style[name]=old[name];},css:function(elem,name,force){if(name=="width"||name=="height"){var val,props={position:"absolute",visibility:"hidden",display:"block"},which=name=="width"?["Left","Right"]:["Top","Bottom"];function getWH(){val=name=="width"?elem.offsetWidth:elem.offsetHeight;var padding=0,border=0;jQuery.each(which,function(){padding+=parseFloat(jQuery.curCSS(elem,"padding"+this,true))||0;border+=parseFloat(jQuery.curCSS(elem,"border"+this+"Width",true))||0;});val-=Math.round(padding+border);}if(jQuery(elem).is(":visible"))getWH();else +jQuery.swap(elem,props,getWH);return Math.max(0,val);}return jQuery.curCSS(elem,name,force);},curCSS:function(elem,name,force){var ret,style=elem.style;function color(elem){if(!jQuery.browser.safari)return false;var ret=defaultView.getComputedStyle(elem,null);return!ret||ret.getPropertyValue("color")=="";}if(name=="opacity"&&jQuery.browser.msie){ret=jQuery.attr(style,"opacity");return ret==""?"1":ret;}if(jQuery.browser.opera&&name=="display"){var save=style.outline;style.outline="0 solid black";style.outline=save;}if(name.match(/float/i))name=styleFloat;if(!force&&style&&style[name])ret=style[name];else if(defaultView.getComputedStyle){if(name.match(/float/i))name="float";name=name.replace(/([A-Z])/g,"-$1").toLowerCase();var computedStyle=defaultView.getComputedStyle(elem,null);if(computedStyle&&!color(elem))ret=computedStyle.getPropertyValue(name);else{var swap=[],stack=[],a=elem,i=0;for(;a&&color(a);a=a.parentNode)stack.unshift(a);for(;i<stack.length;i++)if(color(stack[i])){swap[i]=stack[i].style.display;stack[i].style.display="block";}ret=name=="display"&&swap[stack.length-1]!=null?"none":(computedStyle&&computedStyle.getPropertyValue(name))||"";for(i=0;i<swap.length;i++)if(swap[i]!=null)stack[i].style.display=swap[i];}if(name=="opacity"&&ret=="")ret="1";}else if(elem.currentStyle){var camelCase=name.replace(/\-(\w)/g,function(all,letter){return letter.toUpperCase();});ret=elem.currentStyle[name]||elem.currentStyle[camelCase];if(!/^\d+(px)?$/i.test(ret)&&/^\d/.test(ret)){var left=style.left,rsLeft=elem.runtimeStyle.left;elem.runtimeStyle.left=elem.currentStyle.left;style.left=ret||0;ret=style.pixelLeft+"px";style.left=left;elem.runtimeStyle.left=rsLeft;}}return ret;},clean:function(elems,context){var ret=[];context=context||document;if(typeof context.createElement=='undefined')context=context.ownerDocument||context[0]&&context[0].ownerDocument||document;jQuery.each(elems,function(i,elem){if(!elem)return;if(elem.constructor==Number)elem+='';if(typeof elem=="string"){elem=elem.replace(/(<(\w+)[^>]*?)\/>/g,function(all,front,tag){return tag.match(/^(abbr|br|col|img|input|link|meta|param|hr|area|embed)$/i)?all:front+"></"+tag+">";});var tags=jQuery.trim(elem).toLowerCase(),div=context.createElement("div");var wrap=!tags.indexOf("<opt")&&[1,"<select multiple='multiple'>","</select>"]||!tags.indexOf("<leg")&&[1,"<fieldset>","</fieldset>"]||tags.match(/^<(thead|tbody|tfoot|colg|cap)/)&&[1,"<table>","</table>"]||!tags.indexOf("<tr")&&[2,"<table><tbody>","</tbody></table>"]||(!tags.indexOf("<td")||!tags.indexOf("<th"))&&[3,"<table><tbody><tr>","</tr></tbody></table>"]||!tags.indexOf("<col")&&[2,"<table><tbody></tbody><colgroup>","</colgroup></table>"]||jQuery.browser.msie&&[1,"div<div>","</div>"]||[0,"",""];div.innerHTML=wrap[1]+elem+wrap[2];while(wrap[0]--)div=div.lastChild;if(jQuery.browser.msie){var tbody=!tags.indexOf("<table")&&tags.indexOf("<tbody")<0?div.firstChild&&div.firstChild.childNodes:wrap[1]=="<table>"&&tags.indexOf("<tbody")<0?div.childNodes:[];for(var j=tbody.length-1;j>=0;--j)if(jQuery.nodeName(tbody[j],"tbody")&&!tbody[j].childNodes.length)tbody[j].parentNode.removeChild(tbody[j]);if(/^\s/.test(elem))div.insertBefore(context.createTextNode(elem.match(/^\s*/)[0]),div.firstChild);}elem=jQuery.makeArray(div.childNodes);}if(elem.length===0&&(!jQuery.nodeName(elem,"form")&&!jQuery.nodeName(elem,"select")))return;if(elem[0]==undefined||jQuery.nodeName(elem,"form")||elem.options)ret.push(elem);else +ret=jQuery.merge(ret,elem);});return ret;},attr:function(elem,name,value){if(!elem||elem.nodeType==3||elem.nodeType==8)return undefined;var notxml=!jQuery.isXMLDoc(elem),set=value!==undefined,msie=jQuery.browser.msie;name=notxml&&jQuery.props[name]||name;if(elem.tagName){var special=/href|src|style/.test(name);if(name=="selected"&&jQuery.browser.safari)elem.parentNode.selectedIndex;if(name in elem&&notxml&&!special){if(set){if(name=="type"&&jQuery.nodeName(elem,"input")&&elem.parentNode)throw"type property can't be changed";elem[name]=value;}if(jQuery.nodeName(elem,"form")&&elem.getAttributeNode(name))return elem.getAttributeNode(name).nodeValue;return elem[name];}if(msie&&notxml&&name=="style")return jQuery.attr(elem.style,"cssText",value);if(set)elem.setAttribute(name,""+value);var attr=msie&&notxml&&special?elem.getAttribute(name,2):elem.getAttribute(name);return attr===null?undefined:attr;}if(msie&&name=="opacity"){if(set){elem.zoom=1;elem.filter=(elem.filter||"").replace(/alpha$[^)]*$/,"")+(parseInt(value)+''=="NaN"?"":"alpha(opacity="+value*100+")");}return elem.filter&&elem.filter.indexOf("opacity=")>=0?(parseFloat(elem.filter.match(/opacity=([^)]*)/)[1])/100)+'':"";}name=name.replace(/-([a-z])/ig,function(all,letter){return letter.toUpperCase();});if(set)elem[name]=value;return elem[name];},trim:function(text){return(text||"").replace(/^\s+|\s+$/g,"");},makeArray:function(array){var ret=[];if(array!=null){var i=array.length;if(i==null||array.split||array.setInterval||array.call)ret[0]=array;else +while(i)ret[--i]=array[i];}return ret;},inArray:function(elem,array){for(var i=0,length=array.length;i<length;i++)if(array[i]===elem)return i;return-1;},merge:function(first,second){var i=0,elem,pos=first.length;if(jQuery.browser.msie){while(elem=second[i++])if(elem.nodeType!=8)first[pos++]=elem;}else +while(elem=second[i++])first[pos++]=elem;return first;},unique:function(array){var ret=[],done={};try{for(var i=0,length=array.length;i<length;i++){var id=jQuery.data(array[i]);if(!done[id]){done[id]=true;ret.push(array[i]);}}}catch(e){ret=array;}return ret;},grep:function(elems,callback,inv){var ret=[];for(var i=0,length=elems.length;i<length;i++)if(!inv!=!callback(elems[i],i))ret.push(elems[i]);return ret;},map:function(elems,callback){var ret=[];for(var i=0,length=elems.length;i<length;i++){var value=callback(elems[i],i);if(value!=null)ret[ret.length]=value;}return ret.concat.apply([],ret);}});var userAgent=navigator.userAgent.toLowerCase();jQuery.browser={version:(userAgent.match(/.+(?:rv|it|ra|ie)[\/: ]([\d.]+)/)||[])[1],safari:/webkit/.test(userAgent),opera:/opera/.test(userAgent),msie:/msie/.test(userAgent)&&!/opera/.test(userAgent),mozilla:/mozilla/.test(userAgent)&&!/(compatible|webkit)/.test(userAgent)};var styleFloat=jQuery.browser.msie?"styleFloat":"cssFloat";jQuery.extend({boxModel:!jQuery.browser.msie||document.compatMode=="CSS1Compat",props:{"for":"htmlFor","class":"className","float":styleFloat,cssFloat:styleFloat,styleFloat:styleFloat,readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing"}});jQuery.each({parent:function(elem){return elem.parentNode;},parents:function(elem){return jQuery.dir(elem,"parentNode");},next:function(elem){return jQuery.nth(elem,2,"nextSibling");},prev:function(elem){return jQuery.nth(elem,2,"previousSibling");},nextAll:function(elem){return jQuery.dir(elem,"nextSibling");},prevAll:function(elem){return jQuery.dir(elem,"previousSibling");},siblings:function(elem){return jQuery.sibling(elem.parentNode.firstChild,elem);},children:function(elem){return jQuery.sibling(elem.firstChild);},contents:function(elem){return jQuery.nodeName(elem,"iframe")?elem.contentDocument||elem.contentWindow.document:jQuery.makeArray(elem.childNodes);}},function(name,fn){jQuery.fn[name]=function(selector){var ret=jQuery.map(this,fn);if(selector&&typeof selector=="string")ret=jQuery.multiFilter(selector,ret);return this.pushStack(jQuery.unique(ret));};});jQuery.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(name,original){jQuery.fn[name]=function(){var args=arguments;return this.each(function(){for(var i=0,length=args.length;i<length;i++)jQuery(args[i])[original](this);});};});jQuery.each({removeAttr:function(name){jQuery.attr(this,name,"");if(this.nodeType==1)this.removeAttribute(name);},addClass:function(classNames){jQuery.className.add(this,classNames);},removeClass:function(classNames){jQuery.className.remove(this,classNames);},toggleClass:function(classNames){jQuery.className[jQuery.className.has(this,classNames)?"remove":"add"](this,classNames);},remove:function(selector){if(!selector||jQuery.filter(selector,[this]).r.length){jQuery("*",this).add(this).each(function(){jQuery.event.remove(this);jQuery.removeData(this);});if(this.parentNode)this.parentNode.removeChild(this);}},empty:function(){jQuery(">*",this).remove();while(this.firstChild)this.removeChild(this.firstChild);}},function(name,fn){jQuery.fn[name]=function(){return this.each(fn,arguments);};});jQuery.each(["Height","Width"],function(i,name){var type=name.toLowerCase();jQuery.fn[type]=function(size){return this[0]==window?jQuery.browser.opera&&document.body["client"+name]||jQuery.browser.safari&&window["inner"+name]||document.compatMode=="CSS1Compat"&&document.documentElement["client"+name]||document.body["client"+name]:this[0]==document?Math.max(Math.max(document.body["scroll"+name],document.documentElement["scroll"+name]),Math.max(document.body["offset"+name],document.documentElement["offset"+name])):size==undefined?(this.length?jQuery.css(this[0],type):null):this.css(type,size.constructor==String?size:size+"px");};});function num(elem,prop){return elem[0]&&parseInt(jQuery.curCSS(elem[0],prop,true),10)||0;}var chars=jQuery.browser.safari&&parseInt(jQuery.browser.version)<417?"(?:[\\w*_-]|\\\\.)":"(?:[\\w\u0128-\uFFFF*_-]|\\\\.)",quickChild=new RegExp("^>\\s*("+chars+"+)"),quickID=new RegExp("^("+chars+"+)(#)("+chars+"+)"),quickClass=new RegExp("^([#.]?)("+chars+"*)");jQuery.extend({expr:{"":function(a,i,m){return m[2]=="*"||jQuery.nodeName(a,m[2]);},"#":function(a,i,m){return a.getAttribute("id")==m[2];},":":{lt:function(a,i,m){return i<m[3]-0;},gt:function(a,i,m){return i>m[3]-0;},nth:function(a,i,m){return m[3]-0==i;},eq:function(a,i,m){return m[3]-0==i;},first:function(a,i){return i==0;},last:function(a,i,m,r){return i==r.length-1;},even:function(a,i){return i%2==0;},odd:function(a,i){return i%2;},"first-child":function(a){return a.parentNode.getElementsByTagName("*")[0]==a;},"last-child":function(a){return jQuery.nth(a.parentNode.lastChild,1,"previousSibling")==a;},"only-child":function(a){return!jQuery.nth(a.parentNode.lastChild,2,"previousSibling");},parent:function(a){return a.firstChild;},empty:function(a){return!a.firstChild;},contains:function(a,i,m){return(a.textContent||a.innerText||jQuery(a).text()||"").indexOf(m[3])>=0;},visible:function(a){return"hidden"!=a.type&&jQuery.css(a,"display")!="none"&&jQuery.css(a,"visibility")!="hidden";},hidden:function(a){return"hidden"==a.type||jQuery.css(a,"display")=="none"||jQuery.css(a,"visibility")=="hidden";},enabled:function(a){return!a.disabled;},disabled:function(a){return a.disabled;},checked:function(a){return a.checked;},selected:function(a){return a.selected||jQuery.attr(a,"selected");},text:function(a){return"text"==a.type;},radio:function(a){return"radio"==a.type;},checkbox:function(a){return"checkbox"==a.type;},file:function(a){return"file"==a.type;},password:function(a){return"password"==a.type;},submit:function(a){return"submit"==a.type;},image:function(a){return"image"==a.type;},reset:function(a){return"reset"==a.type;},button:function(a){return"button"==a.type||jQuery.nodeName(a,"button");},input:function(a){return/input|select|textarea|button/i.test(a.nodeName);},has:function(a,i,m){return jQuery.find(m[3],a).length;},header:function(a){return/h\d/i.test(a.nodeName);},animated:function(a){return jQuery.grep(jQuery.timers,function(fn){return a==fn.elem;}).length;}}},parse:[/^(\[) *@?([\w-]+) *([!*$^~=]*) *('?"?)(.*?)\4 *\]/,/^(:)([\w-]+)$"?'?(.*?(\(.*?$)?[^(]*?)"?'?\)/,new RegExp("^([:.#]*)("+chars+"+)")],multiFilter:function(expr,elems,not){var old,cur=[];while(expr&&expr!=old){old=expr;var f=jQuery.filter(expr,elems,not);expr=f.t.replace(/^\s*,\s*/,"");cur=not?elems=f.r:jQuery.merge(cur,f.r);}return cur;},find:function(t,context){if(typeof t!="string")return[t];if(context&&context.nodeType!=1&&context.nodeType!=9)return[];context=context||document;var ret=[context],done=[],last,nodeName;while(t&&last!=t){var r=[];last=t;t=jQuery.trim(t);var foundToken=false,re=quickChild,m=re.exec(t);if(m){nodeName=m[1].toUpperCase();for(var i=0;ret[i];i++)for(var c=ret[i].firstChild;c;c=c.nextSibling)if(c.nodeType==1&&(nodeName=="*"||c.nodeName.toUpperCase()==nodeName))r.push(c);ret=r;t=t.replace(re,"");if(t.indexOf(" ")==0)continue;foundToken=true;}else{re=/^([>+~])\s*(\w*)/i;if((m=re.exec(t))!=null){r=[];var merge={};nodeName=m[2].toUpperCase();m=m[1];for(var j=0,rl=ret.length;j<rl;j++){var n=m=="~"||m=="+"?ret[j].nextSibling:ret[j].firstChild;for(;n;n=n.nextSibling)if(n.nodeType==1){var id=jQuery.data(n);if(m=="~"&&merge[id])break;if(!nodeName||n.nodeName.toUpperCase()==nodeName){if(m=="~")merge[id]=true;r.push(n);}if(m=="+")break;}}ret=r;t=jQuery.trim(t.replace(re,""));foundToken=true;}}if(t&&!foundToken){if(!t.indexOf(",")){if(context==ret[0])ret.shift();done=jQuery.merge(done,ret);r=ret=[context];t=" "+t.substr(1,t.length);}else{var re2=quickID;var m=re2.exec(t);if(m){m=[0,m[2],m[3],m[1]];}else{re2=quickClass;m=re2.exec(t);}m[2]=m[2].replace(/\\/g,"");var elem=ret[ret.length-1];if(m[1]=="#"&&elem&&elem.getElementById&&!jQuery.isXMLDoc(elem)){var oid=elem.getElementById(m[2]);if((jQuery.browser.msie||jQuery.browser.opera)&&oid&&typeof oid.id=="string"&&oid.id!=m[2])oid=jQuery('[@id="'+m[2]+'"]',elem)[0];ret=r=oid&&(!m[3]||jQuery.nodeName(oid,m[3]))?[oid]:[];}else{for(var i=0;ret[i];i++){var tag=m[1]=="#"&&m[3]?m[3]:m[1]!=""||m[0]==""?"*":m[2];if(tag=="*"&&ret[i].nodeName.toLowerCase()=="object")tag="param";r=jQuery.merge(r,ret[i].getElementsByTagName(tag));}if(m[1]==".")r=jQuery.classFilter(r,m[2]);if(m[1]=="#"){var tmp=[];for(var i=0;r[i];i++)if(r[i].getAttribute("id")==m[2]){tmp=[r[i]];break;}r=tmp;}ret=r;}t=t.replace(re2,"");}}if(t){var val=jQuery.filter(t,r);ret=r=val.r;t=jQuery.trim(val.t);}}if(t)ret=[];if(ret&&context==ret[0])ret.shift();done=jQuery.merge(done,ret);return done;},classFilter:function(r,m,not){m=" "+m+" ";var tmp=[];for(var i=0;r[i];i++){var pass=(" "+r[i].className+" ").indexOf(m)>=0;if(!not&&pass||not&&!pass)tmp.push(r[i]);}return tmp;},filter:function(t,r,not){var last;while(t&&t!=last){last=t;var p=jQuery.parse,m;for(var i=0;p[i];i++){m=p[i].exec(t);if(m){t=t.substring(m[0].length);m[2]=m[2].replace(/\\/g,"");break;}}if(!m)break;if(m[1]==":"&&m[2]=="not")r=isSimple.test(m[3])?jQuery.filter(m[3],r,true).r:jQuery(r).not(m[3]);else if(m[1]==".")r=jQuery.classFilter(r,m[2],not);else if(m[1]=="["){var tmp=[],type=m[3];for(var i=0,rl=r.length;i<rl;i++){var a=r[i],z=a[jQuery.props[m[2]]||m[2]];if(z==null||/href|src|selected/.test(m[2]))z=jQuery.attr(a,m[2])||'';if((type==""&&!!z||type=="="&&z==m[5]||type=="!="&&z!=m[5]||type=="^="&&z&&!z.indexOf(m[5])||type=="$="&&z.substr(z.length-m[5].length)==m[5]||(type=="*="||type=="~=")&&z.indexOf(m[5])>=0)^not)tmp.push(a);}r=tmp;}else if(m[1]==":"&&m[2]=="nth-child"){var merge={},tmp=[],test=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(m[3]=="even"&&"2n"||m[3]=="odd"&&"2n+1"||!/\D/.test(m[3])&&"0n+"+m[3]||m[3]),first=(test[1]+(test[2]||1))-0,last=test[3]-0;for(var i=0,rl=r.length;i<rl;i++){var node=r[i],parentNode=node.parentNode,id=jQuery.data(parentNode);if(!merge[id]){var c=1;for(var n=parentNode.firstChild;n;n=n.nextSibling)if(n.nodeType==1)n.nodeIndex=c++;merge[id]=true;}var add=false;if(first==0){if(node.nodeIndex==last)add=true;}else if((node.nodeIndex-last)%first==0&&(node.nodeIndex-last)/first>=0)add=true;if(add^not)tmp.push(node);}r=tmp;}else{var fn=jQuery.expr[m[1]];if(typeof fn=="object")fn=fn[m[2]];if(typeof fn=="string")fn=eval("false||function(a,i){return "+fn+";}");r=jQuery.grep(r,function(elem,i){return fn(elem,i,m,r);},not);}}return{r:r,t:t};},dir:function(elem,dir){var matched=[],cur=elem[dir];while(cur&&cur!=document){if(cur.nodeType==1)matched.push(cur);cur=cur[dir];}return matched;},nth:function(cur,result,dir,elem){result=result||1;var num=0;for(;cur;cur=cur[dir])if(cur.nodeType==1&&++num==result)break;return cur;},sibling:function(n,elem){var r=[];for(;n;n=n.nextSibling){if(n.nodeType==1&&n!=elem)r.push(n);}return r;}});jQuery.event={add:function(elem,types,handler,data){if(elem.nodeType==3||elem.nodeType==8)return;if(jQuery.browser.msie&&elem.setInterval)elem=window;if(!handler.guid)handler.guid=this.guid++;if(data!=undefined){var fn=handler;handler=this.proxy(fn,function(){return fn.apply(this,arguments);});handler.data=data;}var events=jQuery.data(elem,"events")||jQuery.data(elem,"events",{}),handle=jQuery.data(elem,"handle")||jQuery.data(elem,"handle",function(){if(typeof jQuery!="undefined"&&!jQuery.event.triggered)return jQuery.event.handle.apply(arguments.callee.elem,arguments);});handle.elem=elem;jQuery.each(types.split(/\s+/),function(index,type){var parts=type.split(".");type=parts[0];handler.type=parts[1];var handlers=events[type];if(!handlers){handlers=events[type]={};if(!jQuery.event.special[type]||jQuery.event.special[type].setup.call(elem)===false){if(elem.addEventListener)elem.addEventListener(type,handle,false);else if(elem.attachEvent)elem.attachEvent("on"+type,handle);}}handlers[handler.guid]=handler;jQuery.event.global[type]=true;});elem=null;},guid:1,global:{},remove:function(elem,types,handler){if(elem.nodeType==3||elem.nodeType==8)return;var events=jQuery.data(elem,"events"),ret,index;if(events){if(types==undefined||(typeof types=="string"&&types.charAt(0)=="."))for(var type in events)this.remove(elem,type+(types||""));else{if(types.type){handler=types.handler;types=types.type;}jQuery.each(types.split(/\s+/),function(index,type){var parts=type.split(".");type=parts[0];if(events[type]){if(handler)delete events[type][handler.guid];else +for(handler in events[type])if(!parts[1]||events[type][handler].type==parts[1])delete events[type][handler];for(ret in events[type])break;if(!ret){if(!jQuery.event.special[type]||jQuery.event.special[type].teardown.call(elem)===false){if(elem.removeEventListener)elem.removeEventListener(type,jQuery.data(elem,"handle"),false);else if(elem.detachEvent)elem.detachEvent("on"+type,jQuery.data(elem,"handle"));}ret=null;delete events[type];}}});}for(ret in events)break;if(!ret){var handle=jQuery.data(elem,"handle");if(handle)handle.elem=null;jQuery.removeData(elem,"events");jQuery.removeData(elem,"handle");}}},trigger:function(type,data,elem,donative,extra){data=jQuery.makeArray(data);if(type.indexOf("!")>=0){type=type.slice(0,-1);var exclusive=true;}if(!elem){if(this.global[type])jQuery("*").add([window,document]).trigger(type,data);}else{if(elem.nodeType==3||elem.nodeType==8)return undefined;var val,ret,fn=jQuery.isFunction(elem[type]||null),event=!data[0]||!data[0].preventDefault;if(event){data.unshift({type:type,target:elem,preventDefault:function(){},stopPropagation:function(){},timeStamp:now()});data[0][expando]=true;}data[0].type=type;if(exclusive)data[0].exclusive=true;var handle=jQuery.data(elem,"handle");if(handle)val=handle.apply(elem,data);if((!fn||(jQuery.nodeName(elem,'a')&&type=="click"))&&elem["on"+type]&&elem["on"+type].apply(elem,data)===false)val=false;if(event)data.shift();if(extra&&jQuery.isFunction(extra)){ret=extra.apply(elem,val==null?data:data.concat(val));if(ret!==undefined)val=ret;}if(fn&&donative!==false&&val!==false&&!(jQuery.nodeName(elem,'a')&&type=="click")){this.triggered=true;try{elem[type]();}catch(e){}}this.triggered=false;}return val;},handle:function(event){var val,ret,namespace,all,handlers;event=arguments[0]=jQuery.event.fix(event||window.event);namespace=event.type.split(".");event.type=namespace[0];namespace=namespace[1];all=!namespace&&!event.exclusive;handlers=(jQuery.data(this,"events")||{})[event.type];for(var j in handlers){var handler=handlers[j];if(all||handler.type==namespace){event.handler=handler;event.data=handler.data;ret=handler.apply(this,arguments);if(val!==false)val=ret;if(ret===false){event.preventDefault();event.stopPropagation();}}}return val;},fix:function(event){if(event[expando]==true)return event;var originalEvent=event;event={originalEvent:originalEvent};var props="altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode metaKey newValue originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target timeStamp toElement type view wheelDelta which".split(" ");for(var i=props.length;i;i--)event[props[i]]=originalEvent[props[i]];event[expando]=true;event.preventDefault=function(){if(originalEvent.preventDefault)originalEvent.preventDefault();originalEvent.returnValue=false;};event.stopPropagation=function(){if(originalEvent.stopPropagation)originalEvent.stopPropagation();originalEvent.cancelBubble=true;};event.timeStamp=event.timeStamp||now();if(!event.target)event.target=event.srcElement||document;if(event.target.nodeType==3)event.target=event.target.parentNode;if(!event.relatedTarget&&event.fromElement)event.relatedTarget=event.fromElement==event.target?event.toElement:event.fromElement;if(event.pageX==null&&event.clientX!=null){var doc=document.documentElement,body=document.body;event.pageX=event.clientX+(doc&&doc.scrollLeft||body&&body.scrollLeft||0)-(doc.clientLeft||0);event.pageY=event.clientY+(doc&&doc.scrollTop||body&&body.scrollTop||0)-(doc.clientTop||0);}if(!event.which&&((event.charCode||event.charCode===0)?event.charCode:event.keyCode))event.which=event.charCode||event.keyCode;if(!event.metaKey&&event.ctrlKey)event.metaKey=event.ctrlKey;if(!event.which&&event.button)event.which=(event.button&1?1:(event.button&2?3:(event.button&4?2:0)));return event;},proxy:function(fn,proxy){proxy.guid=fn.guid=fn.guid||proxy.guid||this.guid++;return proxy;},special:{ready:{setup:function(){bindReady();return;},teardown:function(){return;}},mouseenter:{setup:function(){if(jQuery.browser.msie)return false;jQuery(this).bind("mouseover",jQuery.event.special.mouseenter.handler);return true;},teardown:function(){if(jQuery.browser.msie)return false;jQuery(this).unbind("mouseover",jQuery.event.special.mouseenter.handler);return true;},handler:function(event){if(withinElement(event,this))return true;event.type="mouseenter";return jQuery.event.handle.apply(this,arguments);}},mouseleave:{setup:function(){if(jQuery.browser.msie)return false;jQuery(this).bind("mouseout",jQuery.event.special.mouseleave.handler);return true;},teardown:function(){if(jQuery.browser.msie)return false;jQuery(this).unbind("mouseout",jQuery.event.special.mouseleave.handler);return true;},handler:function(event){if(withinElement(event,this))return true;event.type="mouseleave";return jQuery.event.handle.apply(this,arguments);}}}};jQuery.fn.extend({bind:function(type,data,fn){return type=="unload"?this.one(type,data,fn):this.each(function(){jQuery.event.add(this,type,fn||data,fn&&data);});},one:function(type,data,fn){var one=jQuery.event.proxy(fn||data,function(event){jQuery(this).unbind(event,one);return(fn||data).apply(this,arguments);});return this.each(function(){jQuery.event.add(this,type,one,fn&&data);});},unbind:function(type,fn){return this.each(function(){jQuery.event.remove(this,type,fn);});},trigger:function(type,data,fn){return this.each(function(){jQuery.event.trigger(type,data,this,true,fn);});},triggerHandler:function(type,data,fn){return this[0]&&jQuery.event.trigger(type,data,this[0],false,fn);},toggle:function(fn){var args=arguments,i=1;while(i<args.length)jQuery.event.proxy(fn,args[i++]);return this.click(jQuery.event.proxy(fn,function(event){this.lastToggle=(this.lastToggle||0)%i;event.preventDefault();return args[this.lastToggle++].apply(this,arguments)||false;}));},hover:function(fnOver,fnOut){return this.bind('mouseenter',fnOver).bind('mouseleave',fnOut);},ready:function(fn){bindReady();if(jQuery.isReady)fn.call(document,jQuery);else +jQuery.readyList.push(function(){return fn.call(this,jQuery);});return this;}});jQuery.extend({isReady:false,readyList:[],ready:function(){if(!jQuery.isReady){jQuery.isReady=true;if(jQuery.readyList){jQuery.each(jQuery.readyList,function(){this.call(document);});jQuery.readyList=null;}jQuery(document).triggerHandler("ready");}}});var readyBound=false;function bindReady(){if(readyBound)return;readyBound=true;if(document.addEventListener&&!jQuery.browser.opera)document.addEventListener("DOMContentLoaded",jQuery.ready,false);if(jQuery.browser.msie&&window==top)(function(){if(jQuery.isReady)return;try{document.documentElement.doScroll("left");}catch(error){setTimeout(arguments.callee,0);return;}jQuery.ready();})();if(jQuery.browser.opera)document.addEventListener("DOMContentLoaded",function(){if(jQuery.isReady)return;for(var i=0;i<document.styleSheets.length;i++)if(document.styleSheets[i].disabled){setTimeout(arguments.callee,0);return;}jQuery.ready();},false);if(jQuery.browser.safari){var numStyles;(function(){if(jQuery.isReady)return;if(document.readyState!="loaded"&&document.readyState!="complete"){setTimeout(arguments.callee,0);return;}if(numStyles===undefined)numStyles=jQuery("style, link[rel=stylesheet]").length;if(document.styleSheets.length!=numStyles){setTimeout(arguments.callee,0);return;}jQuery.ready();})();}jQuery.event.add(window,"load",jQuery.ready);}jQuery.each(("blur,focus,load,resize,scroll,unload,click,dblclick,"+"mousedown,mouseup,mousemove,mouseover,mouseout,change,select,"+"submit,keydown,keypress,keyup,error").split(","),function(i,name){jQuery.fn[name]=function(fn){return fn?this.bind(name,fn):this.trigger(name);};});var withinElement=function(event,elem){var parent=event.relatedTarget;while(parent&&parent!=elem)try{parent=parent.parentNode;}catch(error){parent=elem;}return parent==elem;};jQuery(window).bind("unload",function(){jQuery("*").add(document).unbind();});jQuery.fn.extend({_load:jQuery.fn.load,load:function(url,params,callback){if(typeof url!='string')return this._load(url);var off=url.indexOf(" ");if(off>=0){var selector=url.slice(off,url.length);url=url.slice(0,off);}callback=callback||function(){};var type="GET";if(params)if(jQuery.isFunction(params)){callback=params;params=null;}else{params=jQuery.param(params);type="POST";}var self=this;jQuery.ajax({url:url,type:type,dataType:"html",data:params,complete:function(res,status){if(status=="success"||status=="notmodified")self.html(selector?jQuery("<div/>").append(res.responseText.replace(/<script(.|\s)*?\/script>/g,"")).find(selector):res.responseText);self.each(callback,[res.responseText,status,res]);}});return this;},serialize:function(){return jQuery.param(this.serializeArray());},serializeArray:function(){return this.map(function(){return jQuery.nodeName(this,"form")?jQuery.makeArray(this.elements):this;}).filter(function(){return this.name&&!this.disabled&&(this.checked||/select|textarea/i.test(this.nodeName)||/text|hidden|password/i.test(this.type));}).map(function(i,elem){var val=jQuery(this).val();return val==null?null:val.constructor==Array?jQuery.map(val,function(val,i){return{name:elem.name,value:val};}):{name:elem.name,value:val};}).get();}});jQuery.each("ajaxStart,ajaxStop,ajaxComplete,ajaxError,ajaxSuccess,ajaxSend".split(","),function(i,o){jQuery.fn[o]=function(f){return this.bind(o,f);};});var jsc=now();jQuery.extend({get:function(url,data,callback,type){if(jQuery.isFunction(data)){callback=data;data=null;}return jQuery.ajax({type:"GET",url:url,data:data,success:callback,dataType:type});},getScript:function(url,callback){return jQuery.get(url,null,callback,"script");},getJSON:function(url,data,callback){return jQuery.get(url,data,callback,"json");},post:function(url,data,callback,type){if(jQuery.isFunction(data)){callback=data;data={};}return jQuery.ajax({type:"POST",url:url,data:data,success:callback,dataType:type});},ajaxSetup:function(settings){jQuery.extend(jQuery.ajaxSettings,settings);},ajaxSettings:{url:location.href,global:true,type:"GET",timeout:0,contentType:"application/x-www-form-urlencoded",processData:true,async:true,data:null,username:null,password:null,accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},ajax:function(s){s=jQuery.extend(true,s,jQuery.extend(true,{},jQuery.ajaxSettings,s));var jsonp,jsre=/=\?(&|$)/g,status,data,type=s.type.toUpperCase();if(s.data&&s.processData&&typeof s.data!="string")s.data=jQuery.param(s.data);if(s.dataType=="jsonp"){if(type=="GET"){if(!s.url.match(jsre))s.url+=(s.url.match(/\?/)?"&":"?")+(s.jsonp||"callback")+"=?";}else if(!s.data||!s.data.match(jsre))s.data=(s.data?s.data+"&":"")+(s.jsonp||"callback")+"=?";s.dataType="json";}if(s.dataType=="json"&&(s.data&&s.data.match(jsre)||s.url.match(jsre))){jsonp="jsonp"+jsc++;if(s.data)s.data=(s.data+"").replace(jsre,"="+jsonp+"$1");s.url=s.url.replace(jsre,"="+jsonp+"$1");s.dataType="script";window[jsonp]=function(tmp){data=tmp;success();complete();window[jsonp]=undefined;try{delete window[jsonp];}catch(e){}if(head)head.removeChild(script);};}if(s.dataType=="script"&&s.cache==null)s.cache=false;if(s.cache===false&&type=="GET"){var ts=now();var ret=s.url.replace(/(\?|&)_=.*?(&|$)/,"$1_="+ts+"$2");s.url=ret+((ret==s.url)?(s.url.match(/\?/)?"&":"?")+"_="+ts:"");}if(s.data&&type=="GET"){s.url+=(s.url.match(/\?/)?"&":"?")+s.data;s.data=null;}if(s.global&&!jQuery.active++)jQuery.event.trigger("ajaxStart");var remote=/^(?:\w+:)?\/\/([^\/?#]+)/;if(s.dataType=="script"&&type=="GET"&&remote.test(s.url)&&remote.exec(s.url)[1]!=location.host){var head=document.getElementsByTagName("head")[0];var script=document.createElement("script");script.src=s.url;if(s.scriptCharset)script.charset=s.scriptCharset;if(!jsonp){var done=false;script.onload=script.onreadystatechange=function(){if(!done&&(!this.readyState||this.readyState=="loaded"||this.readyState=="complete")){done=true;success();complete();head.removeChild(script);}};}head.appendChild(script);return undefined;}var requestDone=false;var xhr=window.ActiveXObject?new ActiveXObject("Microsoft.XMLHTTP"):new XMLHttpRequest();if(s.username)xhr.open(type,s.url,s.async,s.username,s.password);else +xhr.open(type,s.url,s.async);try{if(s.data)xhr.setRequestHeader("Content-Type",s.contentType);if(s.ifModified)xhr.setRequestHeader("If-Modified-Since",jQuery.lastModified[s.url]||"Thu, 01 Jan 1970 00:00:00 GMT");xhr.setRequestHeader("X-Requested-With","XMLHttpRequest");xhr.setRequestHeader("Accept",s.dataType&&s.accepts[s.dataType]?s.accepts[s.dataType]+", */*":s.accepts._default);}catch(e){}if(s.beforeSend&&s.beforeSend(xhr,s)===false){s.global&&jQuery.active--;xhr.abort();return false;}if(s.global)jQuery.event.trigger("ajaxSend",[xhr,s]);var onreadystatechange=function(isTimeout){if(!requestDone&&xhr&&(xhr.readyState==4||isTimeout=="timeout")){requestDone=true;if(ival){clearInterval(ival);ival=null;}status=isTimeout=="timeout"&&"timeout"||!jQuery.httpSuccess(xhr)&&"error"||s.ifModified&&jQuery.httpNotModified(xhr,s.url)&&"notmodified"||"success";if(status=="success"){try{data=jQuery.httpData(xhr,s.dataType,s.dataFilter);}catch(e){status="parsererror";}}if(status=="success"){var modRes;try{modRes=xhr.getResponseHeader("Last-Modified");}catch(e){}if(s.ifModified&&modRes)jQuery.lastModified[s.url]=modRes;if(!jsonp)success();}else +jQuery.handleError(s,xhr,status);complete();if(s.async)xhr=null;}};if(s.async){var ival=setInterval(onreadystatechange,13);if(s.timeout>0)setTimeout(function(){if(xhr){xhr.abort();if(!requestDone)onreadystatechange("timeout");}},s.timeout);}try{xhr.send(s.data);}catch(e){jQuery.handleError(s,xhr,null,e);}if(!s.async)onreadystatechange();function success(){if(s.success)s.success(data,status);if(s.global)jQuery.event.trigger("ajaxSuccess",[xhr,s]);}function complete(){if(s.complete)s.complete(xhr,status);if(s.global)jQuery.event.trigger("ajaxComplete",[xhr,s]);if(s.global&&!--jQuery.active)jQuery.event.trigger("ajaxStop");}return xhr;},handleError:function(s,xhr,status,e){if(s.error)s.error(xhr,status,e);if(s.global)jQuery.event.trigger("ajaxError",[xhr,s,e]);},active:0,httpSuccess:function(xhr){try{return!xhr.status&&location.protocol=="file:"||(xhr.status>=200&&xhr.status<300)||xhr.status==304||xhr.status==1223||jQuery.browser.safari&&xhr.status==undefined;}catch(e){}return false;},httpNotModified:function(xhr,url){try{var xhrRes=xhr.getResponseHeader("Last-Modified");return xhr.status==304||xhrRes==jQuery.lastModified[url]||jQuery.browser.safari&&xhr.status==undefined;}catch(e){}return false;},httpData:function(xhr,type,filter){var ct=xhr.getResponseHeader("content-type"),xml=type=="xml"||!type&&ct&&ct.indexOf("xml")>=0,data=xml?xhr.responseXML:xhr.responseText;if(xml&&data.documentElement.tagName=="parsererror")throw"parsererror";if(filter)data=filter(data,type);if(type=="script")jQuery.globalEval(data);if(type=="json")data=eval("("+data+")");return data;},param:function(a){var s=[];if(a.constructor==Array||a.jquery)jQuery.each(a,function(){s.push(encodeURIComponent(this.name)+"="+encodeURIComponent(this.value));});else +for(var j in a)if(a[j]&&a[j].constructor==Array)jQuery.each(a[j],function(){s.push(encodeURIComponent(j)+"="+encodeURIComponent(this));});else +s.push(encodeURIComponent(j)+"="+encodeURIComponent(jQuery.isFunction(a[j])?a[j]():a[j]));return s.join("&").replace(/%20/g,"+");}});jQuery.fn.extend({show:function(speed,callback){return speed?this.animate({height:"show",width:"show",opacity:"show"},speed,callback):this.filter(":hidden").each(function(){this.style.display=this.oldblock||"";if(jQuery.css(this,"display")=="none"){var elem=jQuery("<"+this.tagName+" />").appendTo("body");this.style.display=elem.css("display");if(this.style.display=="none")this.style.display="block";elem.remove();}}).end();},hide:function(speed,callback){return speed?this.animate({height:"hide",width:"hide",opacity:"hide"},speed,callback):this.filter(":visible").each(function(){this.oldblock=this.oldblock||jQuery.css(this,"display");this.style.display="none";}).end();},_toggle:jQuery.fn.toggle,toggle:function(fn,fn2){return jQuery.isFunction(fn)&&jQuery.isFunction(fn2)?this._toggle.apply(this,arguments):fn?this.animate({height:"toggle",width:"toggle",opacity:"toggle"},fn,fn2):this.each(function(){jQuery(this)[jQuery(this).is(":hidden")?"show":"hide"]();});},slideDown:function(speed,callback){return this.animate({height:"show"},speed,callback);},slideUp:function(speed,callback){return this.animate({height:"hide"},speed,callback);},slideToggle:function(speed,callback){return this.animate({height:"toggle"},speed,callback);},fadeIn:function(speed,callback){return this.animate({opacity:"show"},speed,callback);},fadeOut:function(speed,callback){return this.animate({opacity:"hide"},speed,callback);},fadeTo:function(speed,to,callback){return this.animate({opacity:to},speed,callback);},animate:function(prop,speed,easing,callback){var optall=jQuery.speed(speed,easing,callback);return this[optall.queue===false?"each":"queue"](function(){if(this.nodeType!=1)return false;var opt=jQuery.extend({},optall),p,hidden=jQuery(this).is(":hidden"),self=this;for(p in prop){if(prop[p]=="hide"&&hidden||prop[p]=="show"&&!hidden)return opt.complete.call(this);if(p=="height"||p=="width"){opt.display=jQuery.css(this,"display");opt.overflow=this.style.overflow;}}if(opt.overflow!=null)this.style.overflow="hidden";opt.curAnim=jQuery.extend({},prop);jQuery.each(prop,function(name,val){var e=new jQuery.fx(self,opt,name);if(/toggle|show|hide/.test(val))e[val=="toggle"?hidden?"show":"hide":val](prop);else{var parts=val.toString().match(/^([+-]=)?([\d+-.]+)(.*)$/),start=e.cur(true)||0;if(parts){var end=parseFloat(parts[2]),unit=parts[3]||"px";if(unit!="px"){self.style[name]=(end||1)+unit;start=((end||1)/e.cur(true))*start;self.style[name]=start+unit;}if(parts[1])end=((parts[1]=="-="?-1:1)*end)+start;e.custom(start,end,unit);}else +e.custom(start,val,"");}});return true;});},queue:function(type,fn){if(jQuery.isFunction(type)||(type&&type.constructor==Array)){fn=type;type="fx";}if(!type||(typeof type=="string"&&!fn))return queue(this[0],type);return this.each(function(){if(fn.constructor==Array)queue(this,type,fn);else{queue(this,type).push(fn);if(queue(this,type).length==1)fn.call(this);}});},stop:function(clearQueue,gotoEnd){var timers=jQuery.timers;if(clearQueue)this.queue([]);this.each(function(){for(var i=timers.length-1;i>=0;i--)if(timers[i].elem==this){if(gotoEnd)timers[i](true);timers.splice(i,1);}});if(!gotoEnd)this.dequeue();return this;}});var queue=function(elem,type,array){if(elem){type=type||"fx";var q=jQuery.data(elem,type+"queue");if(!q||array)q=jQuery.data(elem,type+"queue",jQuery.makeArray(array));}return q;};jQuery.fn.dequeue=function(type){type=type||"fx";return this.each(function(){var q=queue(this,type);q.shift();if(q.length)q[0].call(this);});};jQuery.extend({speed:function(speed,easing,fn){var opt=speed&&speed.constructor==Object?speed:{complete:fn||!fn&&easing||jQuery.isFunction(speed)&&speed,duration:speed,easing:fn&&easing||easing&&easing.constructor!=Function&&easing};opt.duration=(opt.duration&&opt.duration.constructor==Number?opt.duration:jQuery.fx.speeds[opt.duration])||jQuery.fx.speeds.def;opt.old=opt.complete;opt.complete=function(){if(opt.queue!==false)jQuery(this).dequeue();if(jQuery.isFunction(opt.old))opt.old.call(this);};return opt;},easing:{linear:function(p,n,firstNum,diff){return firstNum+diff*p;},swing:function(p,n,firstNum,diff){return((-Math.cos(p*Math.PI)/2)+0.5)*diff+firstNum;}},timers:[],timerId:null,fx:function(elem,options,prop){this.options=options;this.elem=elem;this.prop=prop;if(!options.orig)options.orig={};}});jQuery.fx.prototype={update:function(){if(this.options.step)this.options.step.call(this.elem,this.now,this);(jQuery.fx.step[this.prop]||jQuery.fx.step._default)(this);if(this.prop=="height"||this.prop=="width")this.elem.style.display="block";},cur:function(force){if(this.elem[this.prop]!=null&&this.elem.style[this.prop]==null)return this.elem[this.prop];var r=parseFloat(jQuery.css(this.elem,this.prop,force));return r&&r>-10000?r:parseFloat(jQuery.curCSS(this.elem,this.prop))||0;},custom:function(from,to,unit){this.startTime=now();this.start=from;this.end=to;this.unit=unit||this.unit||"px";this.now=this.start;this.pos=this.state=0;this.update();var self=this;function t(gotoEnd){return self.step(gotoEnd);}t.elem=this.elem;jQuery.timers.push(t);if(jQuery.timerId==null){jQuery.timerId=setInterval(function(){var timers=jQuery.timers;for(var i=0;i<timers.length;i++)if(!timers[i]())timers.splice(i--,1);if(!timers.length){clearInterval(jQuery.timerId);jQuery.timerId=null;}},13);}},show:function(){this.options.orig[this.prop]=jQuery.attr(this.elem.style,this.prop);this.options.show=true;this.custom(0,this.cur());if(this.prop=="width"||this.prop=="height")this.elem.style[this.prop]="1px";jQuery(this.elem).show();},hide:function(){this.options.orig[this.prop]=jQuery.attr(this.elem.style,this.prop);this.options.hide=true;this.custom(this.cur(),0);},step:function(gotoEnd){var t=now();if(gotoEnd||t>this.options.duration+this.startTime){this.now=this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;var done=true;for(var i in this.options.curAnim)if(this.options.curAnim[i]!==true)done=false;if(done){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;this.elem.style.display=this.options.display;if(jQuery.css(this.elem,"display")=="none")this.elem.style.display="block";}if(this.options.hide)this.elem.style.display="none";if(this.options.hide||this.options.show)for(var p in this.options.curAnim)jQuery.attr(this.elem.style,p,this.options.orig[p]);}if(done)this.options.complete.call(this.elem);return false;}else{var n=t-this.startTime;this.state=n/this.options.duration;this.pos=jQuery.easing[this.options.easing||(jQuery.easing.swing?"swing":"linear")](this.state,n,0,1,this.options.duration);this.now=this.start+((this.end-this.start)*this.pos);this.update();}return true;}};jQuery.extend(jQuery.fx,{speeds:{slow:600,fast:200,def:400},step:{scrollLeft:function(fx){fx.elem.scrollLeft=fx.now;},scrollTop:function(fx){fx.elem.scrollTop=fx.now;},opacity:function(fx){jQuery.attr(fx.elem.style,"opacity",fx.now);},_default:function(fx){fx.elem.style[fx.prop]=fx.now+fx.unit;}}});jQuery.fn.offset=function(){var left=0,top=0,elem=this[0],results;if(elem)with(jQuery.browser){var parent=elem.parentNode,offsetChild=elem,offsetParent=elem.offsetParent,doc=elem.ownerDocument,safari2=safari&&parseInt(version)<522&&!/adobeair/i.test(userAgent),css=jQuery.curCSS,fixed=css(elem,"position")=="fixed";if(elem.getBoundingClientRect){var box=elem.getBoundingClientRect();add(box.left+Math.max(doc.documentElement.scrollLeft,doc.body.scrollLeft),box.top+Math.max(doc.documentElement.scrollTop,doc.body.scrollTop));add(-doc.documentElement.clientLeft,-doc.documentElement.clientTop);}else{add(elem.offsetLeft,elem.offsetTop);while(offsetParent){add(offsetParent.offsetLeft,offsetParent.offsetTop);if(mozilla&&!/^t(able|d|h)$/i.test(offsetParent.tagName)||safari&&!safari2)border(offsetParent);if(!fixed&&css(offsetParent,"position")=="fixed")fixed=true;offsetChild=/^body$/i.test(offsetParent.tagName)?offsetChild:offsetParent;offsetParent=offsetParent.offsetParent;}while(parent&&parent.tagName&&!/^body|html$/i.test(parent.tagName)){if(!/^inline|table.*$/i.test(css(parent,"display")))add(-parent.scrollLeft,-parent.scrollTop);if(mozilla&&css(parent,"overflow")!="visible")border(parent);parent=parent.parentNode;}if((safari2&&(fixed||css(offsetChild,"position")=="absolute"))||(mozilla&&css(offsetChild,"position")!="absolute"))add(-doc.body.offsetLeft,-doc.body.offsetTop);if(fixed)add(Math.max(doc.documentElement.scrollLeft,doc.body.scrollLeft),Math.max(doc.documentElement.scrollTop,doc.body.scrollTop));}results={top:top,left:left};}function border(elem){add(jQuery.curCSS(elem,"borderLeftWidth",true),jQuery.curCSS(elem,"borderTopWidth",true));}function add(l,t){left+=parseInt(l,10)||0;top+=parseInt(t,10)||0;}return results;};jQuery.fn.extend({position:function(){var left=0,top=0,results;if(this[0]){var offsetParent=this.offsetParent(),offset=this.offset(),parentOffset=/^body|html$/i.test(offsetParent[0].tagName)?{top:0,left:0}:offsetParent.offset();offset.top-=num(this,'marginTop');offset.left-=num(this,'marginLeft');parentOffset.top+=num(offsetParent,'borderTopWidth');parentOffset.left+=num(offsetParent,'borderLeftWidth');results={top:offset.top-parentOffset.top,left:offset.left-parentOffset.left};}return results;},offsetParent:function(){var offsetParent=this[0].offsetParent;while(offsetParent&&(!/^body|html$/i.test(offsetParent.tagName)&&jQuery.css(offsetParent,'position')=='static'))offsetParent=offsetParent.offsetParent;return jQuery(offsetParent);}});jQuery.each(['Left','Top'],function(i,name){var method='scroll'+name;jQuery.fn[method]=function(val){if(!this[0])return;return val!=undefined?this.each(function(){this==window||this==document?window.scrollTo(!i?val:jQuery(window).scrollLeft(),i?val:jQuery(window).scrollTop()):this[method]=val;}):this[0]==window||this[0]==document?self[i?'pageYOffset':'pageXOffset']||jQuery.boxModel&&document.documentElement[method]||document.body[method]:this[0][method];};});jQuery.each(["Height","Width"],function(i,name){var tl=i?"Left":"Top",br=i?"Right":"Bottom";jQuery.fn["inner"+name]=function(){return this[name.toLowerCase()]()+num(this,"padding"+tl)+num(this,"padding"+br);};jQuery.fn["outer"+name]=function(margin){return this["inner"+name]()+num(this,"border"+tl+"Width")+num(this,"border"+br+"Width")+(margin?num(this,"margin"+tl)+num(this,"margin"+br):0);};});})(); \ No newline at end of file diff --git a/doc/_static/minus.png b/doc/_static/minus.png new file mode 100644 index 0000000..da1c562 Binary files /dev/null and b/doc/_static/minus.png differ diff --git a/doc/_static/navigation.png b/doc/_static/navigation.png new file mode 100644 index 0000000..1081dc1 Binary files /dev/null and b/doc/_static/navigation.png differ diff --git a/doc/_static/plus.png b/doc/_static/plus.png new file mode 100644 index 0000000..b3cb374 Binary files /dev/null and b/doc/_static/plus.png differ diff --git a/doc/_static/pygments.css b/doc/_static/pygments.css new file mode 100644 index 0000000..1f2d2b6 --- /dev/null +++ b/doc/_static/pygments.css @@ -0,0 +1,61 @@ +.hll { background-color: #ffffcc } +.c { color: #408090; font-style: italic } /* Comment */ +.err { border: 1px solid #FF0000 } /* Error */ +.k { color: #007020; font-weight: bold } /* Keyword */ +.o { color: #666666 } /* Operator */ +.cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.cp { color: #007020 } /* Comment.Preproc */ +.c1 { color: #408090; font-style: italic } /* Comment.Single */ +.cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.gd { color: #A00000 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gr { color: #FF0000 } /* Generic.Error */ +.gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.gi { color: #00A000 } /* Generic.Inserted */ +.go { color: #303030 } /* Generic.Output */ +.gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.gt { color: #0040D0 } /* Generic.Traceback */ +.kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.kp { color: #007020 } /* Keyword.Pseudo */ +.kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #902000 } /* Keyword.Type */ +.m { color: #208050 } /* Literal.Number */ +.s { color: #4070a0 } /* Literal.String */ +.na { color: #4070a0 } /* Name.Attribute */ +.nb { color: #007020 } /* Name.Builtin */ +.nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.no { color: #60add5 } /* Name.Constant */ +.nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.ne { color: #007020 } /* Name.Exception */ +.nf { color: #06287e } /* Name.Function */ +.nl { color: #002070; font-weight: bold } /* Name.Label */ +.nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.nt { color: #062873; font-weight: bold } /* Name.Tag */ +.nv { color: #bb60d5 } /* Name.Variable */ +.ow { color: #007020; font-weight: bold } /* Operator.Word */ +.w { color: #bbbbbb } /* Text.Whitespace */ +.mf { color: #208050 } /* Literal.Number.Float */ +.mh { color: #208050 } /* Literal.Number.Hex */ +.mi { color: #208050 } /* Literal.Number.Integer */ +.mo { color: #208050 } /* Literal.Number.Oct */ +.sb { color: #4070a0 } /* Literal.String.Backtick */ +.sc { color: #4070a0 } /* Literal.String.Char */ +.sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.s2 { color: #4070a0 } /* Literal.String.Double */ +.se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.sh { color: #4070a0 } /* Literal.String.Heredoc */ +.si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.sx { color: #c65d09 } /* Literal.String.Other */ +.sr { color: #235388 } /* Literal.String.Regex */ +.s1 { color: #4070a0 } /* Literal.String.Single */ +.ss { color: #517918 } /* Literal.String.Symbol */ +.bp { color: #007020 } /* Name.Builtin.Pseudo */ +.vc { color: #bb60d5 } /* Name.Variable.Class */ +.vg { color: #bb60d5 } /* Name.Variable.Global */ +.vi { color: #bb60d5 } /* Name.Variable.Instance */ +.il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/doc/_static/rightsidebar.css b/doc/_static/rightsidebar.css new file mode 100644 index 0000000..bc604a8 --- /dev/null +++ b/doc/_static/rightsidebar.css @@ -0,0 +1,16 @@ +/** + * Sphinx Doc Design -- Right Side Bar Overrides + */ + + +div.sphinxsidebar { + float: right; +} + +div.bodywrapper { + margin: 0 230px 0 0; +} + +div.inlinecomments { + right: 250px; +} diff --git a/doc/_static/searchtools.js b/doc/_static/searchtools.js new file mode 100644 index 0000000..f9d9b6c --- /dev/null +++ b/doc/_static/searchtools.js @@ -0,0 +1,467 @@ +/** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurance, the + * latter for highlighting it. + */ + +jQuery.makeSearchSummary = function(text, keywords, hlwords) { + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('<div class="context"></div>').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlight'); + }); + return rv; +} + +/** + * Porter Stemmer + */ +var PorterStemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[@name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + /** + * Sets the index + */ + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (var i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out); + this.dots = $('<span></span>').appendTo(this.title); + this.status = $('<p style="display: none"></p>').appendTo(this.out); + this.output = $('<ul class="search"/>').appendTo(this.out); + + $('#search-progress').text(_('Preparing search...')); + this.startPulse(); + + // index already loaded, the browser was quick! + if (this.hasIndex()) + this.query(query); + else + this.setQuery(query); + }, + + query : function(query) { + // stem the searchterms and add them to the + // correct list + var stemmer = new PorterStemmer(); + var searchterms = []; + var excluded = []; + var hlterms = []; + var tmp = query.split(/\s+/); + var object = (tmp.length == 1) ? tmp[0].toLowerCase() : null; + for (var i = 0; i < tmp.length; i++) { + // stem the word + var word = stemmer.stemWord(tmp[i]).toLowerCase(); + // select the correct list + if (word[0] == '-') { + var toAppend = excluded; + word = word.substr(1); + } + else { + var toAppend = searchterms; + hlterms.push(tmp[i].toLowerCase()); + } + // only add if not already in the list + if (!$.contains(toAppend, word)) + toAppend.push(word); + }; + var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); + + console.debug('SEARCH: searching for:'); + console.info('required: ', searchterms); + console.info('excluded: ', excluded); + + // prepare search + var filenames = this._index.filenames; + var titles = this._index.titles; + var terms = this._index.terms; + var descrefs = this._index.descrefs; + var modules = this._index.modules; + var desctypes = this._index.desctypes; + var fileMap = {}; + var files = null; + var objectResults = []; + var regularResults = []; + $('#search-progress').empty(); + + // lookup as object + if (object != null) { + for (var module in modules) { + if (module.indexOf(object) > -1) { + fn = modules[module]; + descr = _('module, in ') + titles[fn]; + objectResults.push([filenames[fn], module, '#module-'+module, descr]); + } + } + for (var prefix in descrefs) { + for (var name in descrefs[prefix]) { + if (name.toLowerCase().indexOf(object) > -1) { + match = descrefs[prefix][name]; + fullname = (prefix ? prefix + '.' : '') + name; + descr = desctypes[match[1]] + _(', in ') + titles[match[0]]; + objectResults.push([filenames[match[0]], fullname, '#'+fullname, descr]); + } + } + } + } + + // sort results descending + objectResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + + // perform the search on the required terms + for (var i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + // no match but word was a required one + if ((files = terms[word]) == null) + break; + if (files.length == undefined) { + files = [files]; + } + // create the mapping + for (var j = 0; j < files.length; j++) { + var file = files[j]; + if (file in fileMap) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (var file in fileMap) { + var valid = true; + + // check if all requirements are matched + if (fileMap[file].length != searchterms.length) + continue; + + // ensure that none of the excluded terms is in the + // search result. + for (var i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + $.contains(terms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it + // to the result list + if (valid) + regularResults.push([filenames[file], titles[file], '', null]); + } + + // delete unused variables in order to not waste + // memory until list is retrieved completely + delete filenames, titles, terms; + + // now sort the regular results descending by title + regularResults.sort(function(a, b) { + var left = a[1].toLowerCase(); + var right = b[1].toLowerCase(); + return (left > right) ? -1 : ((left < right) ? 1 : 0); + }); + + // combine both + var results = regularResults.concat(objectResults); + + // print the results + var resultCount = results.length; + function displayNextItem() { + // results left, load the summary and display it + if (results.length) { + var item = results.pop(); + var listItem = $('<li style="display:none"></li>'); + listItem.append($('<a/>').attr( + 'href', + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX + + highlightstring + item[2]).html(item[1])); + if (item[3]) { + listItem.append($('<span> (' + item[3] + ')</span>')); + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { + $.get('_sources/' + item[0] + '.txt', function(data) { + listItem.append($.makeSearchSummary(data, searchterms, hlterms)); + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + }); + } else { + // no source available, just display title + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } + } + // search finished, update title and status message + else { + Search.stopPulse(); + Search.title.text(_('Search Results')); + if (!resultCount) + Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); + else + Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); + Search.status.fadeIn(500); + } + } + displayNextItem(); + } +} + +$(document).ready(function() { + Search.init(); +}); diff --git a/doc/_static/sphinxdoc.css b/doc/_static/sphinxdoc.css new file mode 100644 index 0000000..999bf48 --- /dev/null +++ b/doc/_static/sphinxdoc.css @@ -0,0 +1,557 @@ +/** + * Alternate Sphinx design + * Originally created by Armin Ronacher for Werkzeug, adapted by Georg Brandl. + */ + +body { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif; + font-size: 14px; + letter-spacing: -0.01em; + line-height: 150%; + text-align: center; + /*background-color: #AFC1C4; */ + background-color: #BFD1D4; + color: black; + padding: 0; + border: 1px solid #aaa; + + margin: 0px 80px 0px 80px; + min-width: 740px; +} + +a { + color: #CA7900; + text-decoration: none; +} + +a:hover { + color: #2491CF; +} + +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.015em; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +td.linenos pre { + padding: 0.5em 0; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.01em; +} + +hr { + border: 1px solid #abc; + margin: 2em; +} + +tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; + border: 0; +} + +tt.descclassname { + background-color: transparent; + border: 0; +} + +tt.xref { + background-color: transparent; + font-weight: bold; + border: 0; +} + +a tt { + background-color: transparent; + font-weight: bold; + border: 0; + color: #CA7900; +} + +a tt:hover { + color: #2491CF; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.refcount { + color: #060; +} + +dt:target, +.highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +pre { + line-height: 120%; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +.first { + margin-top: 0 !important; +} + +div.document { + background-color: white; + text-align: left; + background-image: url(contents.png); + background-repeat: repeat-x; +} + +/* +div.documentwrapper { + width: 100%; +} +*/ + +div.clearer { + clear: both; +} + +div.related h3 { + display: none; +} + +div.related ul { + background-image: url(navigation.png); + height: 2em; + list-style: none; + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 0; + padding-left: 10px; +} + +div.related ul li { + margin: 0; + padding: 0; + height: 2em; + float: left; +} + +div.related ul li.right { + float: right; + margin-right: 5px; +} + +div.related ul li a { + margin: 0; + padding: 0 5px 0 5px; + line-height: 1.75em; + color: #EE9816; +} + +div.related ul li a:hover { + color: #3CA8E7; +} + +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; +} + +div.body a { + text-decoration: underline; +} + +div.sphinxsidebar { + margin: 0; + padding: 0.5em 15px 15px 0; + width: 210px; + float: right; + text-align: left; +/* margin-left: -100%; */ +} + +div.sphinxsidebar h4, div.sphinxsidebar h3 { + margin: 1em 0 0.5em 0; + font-size: 0.9em; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border: 1px solid #86989B; + background-color: #AFC1C4; +} + +div.sphinxsidebar h3 a { + color: white; +} + +div.sphinxsidebar ul { + padding-left: 1.5em; + margin-top: 7px; + list-style: none; + padding: 0; + line-height: 130%; +} + +div.sphinxsidebar ul ul { + list-style: square; + margin-left: 20px; +} + +p { + margin: 0.8em 0 0.5em 0; +} + +p.rubric { + font-weight: bold; +} + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid #ccc; +} + +p.sidebar-title { + font-weight: bold; +} + +div.topic { + background-color: #f8f8f8; + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; +} + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; + font-size: 1.5em; + color: #11557C; +} + +h2 { + margin: 1.3em 0 0.2em 0; + font-size: 1.35em; + padding: 0; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.2em; +} + +div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { + color: black!important; +} + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: #aaa!important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: #777; + background-color: #eee; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.footer { + background-color: #E3EFF1; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #86989B; + text-decoration: underline; +} + +div.pagination { + margin-top: 2em; + padding-top: 0.5em; + border-top: 1px solid black; + text-align: center; +} + +div.sphinxsidebar ul.toc { + margin: 1em 0 1em 0; + padding: 0 0 0 0.5em; + list-style: none; +} + +div.sphinxsidebar ul.toc li { + margin: 0.5em 0 0.5em 0; + font-size: 0.9em; + line-height: 130%; +} + +div.sphinxsidebar ul.toc li p { + margin: 0; + padding: 0; +} + +div.sphinxsidebar ul.toc ul { + margin: 0.2em 0 0.2em 0; + padding: 0 0 0 1.8em; +} + +div.sphinxsidebar ul.toc ul li { + padding: 0; +} + +div.admonition, div.warning { + font-size: 0.9em; + margin: 1em 0 0 0; + border: 1px solid #86989B; + background-color: #f7f7f7; +} + +div.admonition p, div.warning p { + margin: 0.5em 1em 0.5em 1em; + padding: 0; +} + +div.admonition pre, div.warning pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition p.admonition-title, +div.warning p.admonition-title { + margin: 0; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border-bottom: 1px solid #86989B; + font-weight: bold; + background-color: #AFC1C4; +} + +div.warning { + border: 1px solid #940000; +} + +div.warning p.admonition-title { + background-color: #CF0000; + border-bottom-color: #940000; +} + +div.admonition ul, div.admonition ol, +div.warning ul, div.warning ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid #ccc; + background-color: #DDEAF0; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + + +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +form.pfform { + margin: 10px 0 20px 0; +} + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +img.math { + vertical-align: center; +} + +div.math { + text-align: center; +} + +span.eqno { + float: right; +} + +img.logo { + border: 0; +} diff --git a/doc/_static/stickysidebar.css b/doc/_static/stickysidebar.css new file mode 100644 index 0000000..dfc99c7 --- /dev/null +++ b/doc/_static/stickysidebar.css @@ -0,0 +1,19 @@ +/** + * Sphinx Doc Design -- Sticky sidebar Overrides + */ + +div.sphinxsidebar { + top: 30px; + left: 0px; + position: fixed; + margin: 0; + float: none; +} + +div.related { + position: fixed; +} + +div.documentwrapper { + margin-top: 30px; +} diff --git a/doc/_static/traditional.css b/doc/_static/traditional.css new file mode 100644 index 0000000..8c224c0 --- /dev/null +++ b/doc/_static/traditional.css @@ -0,0 +1,700 @@ +/** + * Sphinx Doc Design -- traditional python.org style + */ + +body { + color: #000; + margin: 0; + padding: 0; +} + +/* :::: LAYOUT :::: */ + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 230px 0 0; +} + +div.body { + background-color: white; + padding: 0 20px 30px 20px; +} + +div.sphinxsidebarwrapper { + border: 1px solid #99ccff; + padding: 10px; + margin: 10px 15px 10px 0; +} + +div.sphinxsidebar { + float: right; + margin-left: -100%; + width: 230px; +} + +div.clearer { + clear: both; +} + +div.footer { + clear: both; + width: 100%; + background-color: #99ccff; + padding: 9px 0 9px 0; + text-align: center; +} + +div.related { + background-color: #99ccff; + color: #333; + width: 100%; + height: 30px; + line-height: 30px; + border-bottom: 5px solid white; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; + font-weight: bold; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* ::: SIDEBAR :::: */ +div.sphinxsidebar h3 { + margin: 0; +} + +div.sphinxsidebar h4 { + margin: 5px 0 0 0; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + margin-left: 15px; + padding: 0; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + + +/* :::: SEARCH :::: */ +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* :::: COMMON FORM STYLES :::: */ + +div.actions { + border-top: 1px solid #aaa; + background-color: #ddd; + margin: 10px 0 0 -20px; + padding: 5px 0 5px 20px; +} + +form dl { + color: #333; +} + +form dt { + clear: both; + float: left; + min-width: 110px; + margin-right: 10px; + padding-top: 2px; +} + +input#homepage { + display: none; +} + +div.error { + margin: 5px 20px 0 0; + padding: 5px; + border: 1px solid #d00; + /*border: 2px solid #05171e; + background-color: #092835; + color: white;*/ + font-weight: bold; +} + +/* :::: INLINE COMMENTS :::: */ + +div.inlinecommentswrapper { + float: right; + max-width: 40%; +} + +div.commentmarker { + float: right; + background-image: url(style/comment.png); + background-repeat: no-repeat; + width: 25px; + height: 25px; + text-align: center; + padding-top: 3px; +} + +div.nocommentmarker { + float: right; + background-image: url(style/nocomment.png); + background-repeat: no-repeat; + width: 25px; + height: 25px; +} + +div.inlinecomments { + margin-left: 10px; + margin-bottom: 5px; + background-color: #eee; + border: 1px solid #ccc; + padding: 5px; +} + +div.inlinecomment { + border-top: 1px solid #ccc; + padding-top: 5px; + margin-top: 5px; +} + +.inlinecomments p { + margin: 5px 0 5px 0; +} + +.inlinecomments .head { + font-weight: bold; +} + +.inlinecomments .meta { + font-style: italic; +} + + +/* :::: COMMENTS :::: */ + +div#comments h3 { + border-top: 1px solid #aaa; + padding: 5px 20px 5px 20px; + margin: 20px -20px 20px -20px; + background-color: #ddd; +} + +/* +div#comments { + background-color: #ccc; + margin: 40px -20px -30px -20px; + padding: 0 0 1px 0; +} + +div#comments h4 { + margin: 30px 0 20px 0; + background-color: #aaa; + border-bottom: 1px solid #09232e; + color: #333; +} + +div#comments form { + display: block; + margin: 0 0 0 20px; +} + +div#comments textarea { + width: 98%; + height: 160px; +} + +div#comments div.help { + margin: 20px 20px 10px 0; + background-color: #ccc; + color: #333; +} + +div#comments div.help p { + margin: 0; + padding: 0 0 10px 0; +} + +div#comments input, div#comments textarea { + font-family: 'Bitstream Vera Sans', 'Arial', sans-serif; + font-size: 13px; + color: black; + background-color: #aaa; + border: 1px solid #092835; +} + +div#comments input[type="reset"], +div#comments input[type="submit"] { + cursor: pointer; + font-weight: bold; + padding: 2px; + margin: 5px 5px 5px 0; + background-color: #666; + color: white; +} + +div#comments div.comment { + margin: 10px 10px 10px 20px; + padding: 10px; + border: 1px solid #0f3646; + background-color: #aaa; + color: #333; +} + +div#comments div.comment p { + margin: 5px 0 5px 0; +} + +div#comments div.comment p.meta { + font-style: italic; + color: #444; + text-align: right; + margin: -5px 0 -5px 0; +} + +div#comments div.comment h4 { + margin: -10px -10px 5px -10px; + padding: 3px; + font-size: 15px; + background-color: #888; + color: white; + border: 0; +} + +div#comments div.comment pre, +div#comments div.comment tt { + background-color: #ddd; + color: #111; + border: none; +} + +div#comments div.comment a { + color: #fff; + text-decoration: underline; +} + +div#comments div.comment blockquote { + margin: 10px; + padding: 10px; + border-left: 1px solid #0f3646; + /*border: 1px solid #0f3646; + background-color: #071c25;*/ +} + +div#comments em.important { + color: #d00; + font-weight: bold; + font-style: normal; +}*/ + +/* :::: SUGGEST CHANGES :::: */ +div#suggest-changes-box input, div#suggest-changes-box textarea { + border: 1px solid #ccc; + background-color: white; + color: black; +} + +div#suggest-changes-box textarea { + width: 99%; + height: 400px; +} + + +/* :::: PREVIEW :::: */ +div.preview { + background-image: url(style/preview.png); + padding: 0 20px 20px 20px; + margin-bottom: 30px; +} + + +/* :::: INDEX PAGE :::: */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.5em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; +} + +/* :::: GENINDEX STYLES :::: */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* :::: GLOBAL STYLES :::: */ + +p.subhead { + font-weight: bold; + margin-top: 20px; +} + +a:link:active { color: #ff0000; } +a:link:hover { background-color: #bbeeff; } +a:visited:hover { background-color: #bbeeff; } +a:visited { color: #551a8b; } +a:link { color: #0000bb; } + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: avantgarde, sans-serif; + font-weight: bold; +} + +div.body h1 { font-size: 180%; } +div.body h2 { font-size: 150%; } +div.body h3 { font-size: 120%; } +div.body h4 { font-size: 120%; } + +a.headerlink, +a.headerlink, +a.headerlink, +a.headerlink, +a.headerlink, +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; + visibility: hidden; +} + +*:hover > a.headerlink, +*:hover > a.headerlink, +*:hover > a.headerlink, +*:hover > a.headerlink, +*:hover > a.headerlink, +*:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover, +a.headerlink:hover, +a.headerlink:hover, +a.headerlink:hover, +a.headerlink:hover, +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; +} + +div.body td { + text-align: left; +} + +ul.fakelist { + list-style: none; + margin: 10px 0 10px 20px; + padding: 0; +} + +/* "Footnotes" heading */ +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* "Topics" */ + +div.topic { + background-color: #eee; + border: 1px solid #ccc; + padding: 0 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* Admonitions */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dd { + margin-bottom: 10px; +} + +div.admonition dl { + margin-bottom: 0; +} + +div.admonition p { + display: inline; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +table.docutils { + border: 0; +} + +table.docutils td, table.docutils th { + padding: 0 8px 2px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +dl { + margin-bottom: 15px; + clear: both; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.refcount { + color: #060; +} + +th { + text-align: left; + padding-right: 5px; +} + +pre { + font-family: monospace; + padding: 5px; + color: #00008b; + border-left: none; + border-right: none; +} + +tt { + font-family: monospace; + background-color: #ecf0f3; + padding: 0 1px 0 1px; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +.footnote:target { background-color: #ffa } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +form.comment { + margin: 0; + padding: 10px 30px 10px 30px; + background-color: #eee; +} + +form.comment h3 { + background-color: #326591; + color: white; + margin: -10px -30px 10px -30px; + padding: 5px; + font-size: 1.4em; +} + +form.comment input, +form.comment textarea { + border: 1px solid #ccc; + padding: 2px; + font-family: sans-serif; + font-size: 13px; +} + +form.comment input[type="text"] { + width: 240px; +} + +form.comment textarea { + width: 100%; + height: 200px; + margin-bottom: 10px; +} + +/* :::: PRINT :::: */ +@media print { + div.documentwrapper { + width: 100%; + } + + div.body { + margin: 0; + } + + div.sphinxsidebar, + div.related, + div.footer, + div#comments div.new-comment-box, + #top-link { + display: none; + } +} diff --git a/doc/genindex.html b/doc/genindex.html new file mode 100644 index 0000000..d7df1e0 --- /dev/null +++ b/doc/genindex.html @@ -0,0 +1,81 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Index — CAS v0.13-118 documentation</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '', + VERSION: '0.13-118', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="index" title="Index" href="" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="top" title="CAS v0.13-118 documentation" href="index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="" title="General Index" + accesskey="I">index</a></li> + <li><a href="index.html">CAS v0.13-118 documentation</a> »</li> + </ul> + </div> + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + + <h1 id="index">Index</h1> + + + + <hr /> + + + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + + + + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="" title="General Index" + accesskey="I">index</a></li> + <li><a href="index.html">CAS v0.13-118 documentation</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2009, Adam Stokes. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.5.1. + </div> + </body> +</html> \ No newline at end of file diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..5ee6297 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,266 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Core Analysis System (CAS) — CAS v0.13-118 documentation</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '', + VERSION: '0.13-118', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="top" title="CAS v0.13-118 documentation" href="" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li><a href="">CAS v0.13-118 documentation</a> »</li> + </ul> + </div> + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + + <div class="section" id="core-analysis-system-cas"> +<h1>Core Analysis System (CAS)<a class="headerlink" href="#core-analysis-system-cas" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<div class="section" id="description"> +<h3>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3> +<p>CAS provides a user the ability to configure an environment for core analysis +quickly. All the hassles of matching kernel versions and machine architecture +types to core dumps are automatically detected and processed.</p> +</div> +<div class="section" id="prerequisites"> +<h3>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h3> +<p>CAS needs at least <strong>Python 2.4</strong> to run. For systems that are not running +Fedora 9 or later (this would include RHEL 4/5) the EPEL repo needs to be +installed. Visit <a class="reference external" href="https://fedoraproject.org/wiki/EPEL">EPEL</a> to enable +this repository.</p> +<p>Optionally install <a class="reference external" href="http://fedorahosted.org/func">Func</a> +for automatic processing on other architecture specific systems. This +can easily be installed via <cite>yum</cite>:</p> +<div class="highlight-python"><pre>$ yum install func</pre> +</div> +<p>Storage size can be determined based on how many kernel-debuginfo to be stored +and how many core dumps and their filesize will be processed. Typically, it is +recommended for at least 1TB for cores and another 500GB for debuginfo’s.</p> +<p>Since analyzing cores requires the same architecture specific systems the core +was generated on there will need to be systems available of those same types +in order for analyzation to work properly.</p> +<p>Finally, root access to the CAS server.</p> +</div> +<div class="section" id="configuration"> +<h3>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h3> +<p>CAS comes with one main configuration file which is located at <tt class="docutils literal"><span class="pre">/etc/cas.conf</span></tt>. +The overall contents of this file is shown below, further down we will break up +each section and describe its meaning:</p> +<div class="highlight-python"><pre>[settings] +kernels=/mnt/kernels +rpms=/var/db/cas/rpms.db +rpmFilter=.*kernel-debuginfo-[0-9].*\.rpm +debugs=/cores/debugs +debugLevel=DEBUG +workDirectory=/cores/processed +servers=/var/db/cas/servers.db +jobs=/var/db/cas/jobs.db +mailServer=mail.example.com +[advanced] +# crash_32=/usr/local/i386/crash</pre> +</div> +<p><tt class="docutils literal"><span class="pre">kernels</span></tt>: (<strong>Required</strong>) Describes the location of where kernel-debuginfo packages are to be +stored. This can range anywhere from an nfs mount, samba share, local disk or +any other type of media the cas server can access.</p> +<p><tt class="docutils literal"><span class="pre">rpms</span></tt>: (<strong>Required</strong>) Database which houses the processing of kernel-debuginfo and stores the +necessary information for CAS to properly match core dumps.</p> +<p><tt class="docutils literal"><span class="pre">rpmFilters</span></tt>: (<strong>Required</strong>) This is a emacs based regular expression which is essentially +passed to a find command to locate the various kernel-debuginfo packages defined +in <tt class="docutils literal"><span class="pre">kernels</span></tt> directive.</p> +<p><tt class="docutils literal"><span class="pre">debugs</span></tt>: (<strong>Required</strong>) A temporary directory in which to store the extracted vmlinux files +from the kernel-debuginfo packages for processing. Another solution would be to +alter this to point an existing directory like <tt class="docutils literal"><span class="pre">/tmp</span></tt>, for instance.</p> +<p><tt class="docutils literal"><span class="pre">debugLevel</span></tt>: As the name suggest it will set the debug level for CAS output. +Currently the only accepted values are <tt class="docutils literal"><span class="pre">DEBUG|INFO</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">workDirectory</span></tt>: (<strong>Required</strong>) Defines where all processed cores will be placed. This mount +point will need to have the most storage assigned to it. Depending on how many +cores are processed in a given timeframe this area will fill up quickly.</p> +<p><tt class="docutils literal"><span class="pre">servers</span></tt>: If func is installed and configured all associated servers will +be stored here.</p> +<p><tt class="docutils literal"><span class="pre">jobs</span></tt>: Contains information on current jobs being processed and eventually +what jobs are in the queue.</p> +<p><tt class="docutils literal"><span class="pre">mailServer</span></tt>: If wanting output of CAS processing email to a certain address +this directive needs to be set. <tt class="docutils literal"><span class="pre">Note</span></tt> that the mail server should not +require smtp authentication.</p> +<p><tt class="docutils literal"><span class="pre">crash_32</span></tt>: Primarily used on x86_64 systems to process x86 cores. If x86 +version of crash is installed this directive can be set to the crash binary +and CAS will automatically process x86 cores on a x86_64 machine. <tt class="docutils literal"><span class="pre">Note</span></tt> this +is only available if the CAS server is a x86_64 machine.</p> +</div> +</div> +<div class="section" id="setup"> +<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2> +<div class="section" id="preparing-cas-server"> +<h3>Preparing CAS Server<a class="headerlink" href="#preparing-cas-server" title="Permalink to this headline">¶</a></h3> +<p>To install the CAS package simply type:</p> +<div class="highlight-python"><pre>$ yum install cas</pre> +</div> +<p>Once installed edit <tt class="docutils literal"><span class="pre">/etc/cas.conf</span></tt> as root using any preferred text editor. +As described above the required directives need to be altered to suit the +environment in question.</p> +<p>In this example, <tt class="docutils literal"><span class="pre">/mnt/kernels</span></tt> is an nfs mount which houses the kernel-debuginfo +packages. <tt class="docutils literal"><span class="pre">/cores</span></tt> is where all processed cores are stored and <tt class="docutils literal"><span class="pre">/tmp</span></tt> is the +temporary storage for collecting the necessary data from the kernel-debuginfos. +A mail server is setup within the environment to email CAS results and this +optional directive is shown to reflect that. Finally, the CAS server is an x86_64 +machine and the environment will be processing x86 cores, therefore, the directive +for this is uncommented and path to the x86 crash binary is given. <tt class="docutils literal"><span class="pre">Note</span></tt> there +is information provided within the configuration file for installing the x86 crash +to a different location.</p> +<p>Altering the configuration to reflect the above assumptions would show the +following:</p> +<div class="highlight-python"><pre>[settings] +kernels=/mnt/kernels +rpms=/var/db/cas/rpms.db +rpmFilter=.*kernel-debuginfo-[0-9].*\.rpm +debugs=/tmp +debugLevel=DEBUG +workDirectory=/cores +servers=/var/db/cas/servers.db +jobs=/var/db/cas/jobs.db +mailServer=mail.cas-server.com +[advanced] +crash_32=/usr/local/i386/crash</pre> +</div> +<p>Now that the configuration file is altered and <tt class="docutils literal"><span class="pre">/mnt/kernels</span></tt> should be populated +with kernel-debuginfo rpm’s the next section will describe running CAS.</p> +</div> +<div class="section" id="running-cas"> +<h3>Running CAS<a class="headerlink" href="#running-cas" title="Permalink to this headline">¶</a></h3> +<p>First, one or two administrative tasks need to be run. The required task is to build +a database for all the data gathered from the kernel-debuginfo packages.:</p> +<div class="highlight-python"><pre>$ cas-admin -b</pre> +</div> +<p>If <tt class="docutils literal"><span class="pre">Func</span></tt> is installed and several systems are deployed for CAS to use run:</p> +<div class="highlight-python"><pre>$ cas-admin -s</pre> +</div> +<p>At this point CAS is configured and looking at the output of CAS help there are +a few options to pass:</p> +<div class="highlight-python"><pre>Usage: cas [opts] args + +Options: + -h, --help show this help message and exit + -i IDENTIFIER, --identifier=IDENTIFIER + Unique ID for core + -f FILENAME, --file=FILENAME + Filename + -e EMAIL, --email=EMAIL + Define email for results (must be valid!) + -m, --modules Extract associated kernel modules</pre> +</div> +<p>CAS prepares its directory hierarchy based on the <tt class="docutils literal"><span class="pre">identifier</span></tt> this option is +therefore required. <tt class="docutils literal"><span class="pre">filename</span></tt> is also required as it tells CAS exactly which +core to process and associate with <tt class="docutils literal"><span class="pre">identifier</span></tt>. If wanting email results from +CAS simply pass it the email parameter.</p> +<p>An example, of a user wanting to process a corefile named <tt class="docutils literal"><span class="pre">vmcore.12345</span></tt>:</p> +<div class="highlight-python"><pre>$ cas -i 12345 -f vmcore.12345 -e user(a)cas-server.com</pre> +</div> +<p>In the above example an assumption is made that <tt class="docutils literal"><span class="pre">12345</span></tt> is associated to some +form of ticketing system so to keep things organized an identifier was set of +that number.</p> +<p>The directory hierarchy for the current job should look like <tt class="docutils literal"><span class="pre">/cores/12345</span></tt>. +In addition to the processing of core files there is also a <tt class="docutils literal"><span class="pre">process</span> <span class="pre">log</span></tt> contained +within this directory for each job processed. If multiple jobs for the same identifier +are issued they are placed within a sub directory marked by the current timestamp +and the relevant data associated with it.</p> +<p>The last option worth mentioning is for core analyst who are needing to work +within the core that requires one of the kernel modules loaded during the crash. +This can be extracted by passing the <tt class="docutils literal"><span class="pre">modules</span></tt> parameter in the CAS execution +statement. <tt class="docutils literal"><span class="pre">Note</span></tt> the <tt class="docutils literal"><span class="pre">modules</span></tt> parameter is not heavily used but can be +useful when analyzing filesystem issues and the like.</p> +<p>From this point on CAS will download, process, and email the results of its +initial analysis to the specified email address. From there further instructions +are provided in either the email or the <tt class="docutils literal"><span class="pre">process</span> <span class="pre">log</span></tt> on how to access and analyze +the core.</p> +</div> +</div> +</div> +<div class="section" id="resources"> +<h1>Resources<a class="headerlink" href="#resources" title="Permalink to this headline">¶</a></h1> +<ul class="simple"> +<li><a class="reference external" href="http://fedorahosted.org/cas">CAS Wiki</a></li> +<li><a class="reference external" href="https://fedorahosted.org/mailman/listinfo/cas">Mailing list</a></li> +<li><a class="reference external" href="https://fedorahosted.org/releases/c/a/cas/">Upstream releases</a></li> +<li>Checkout latest from Git, <tt class="docutils literal"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">git://git.fedorahosted.org/cas.git</span></tt></li> +</ul> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="">Core Analysis System (CAS)</a><ul> +<li><a class="reference external" href="#introduction">Introduction</a><ul> +<li><a class="reference external" href="#description">Description</a></li> +<li><a class="reference external" href="#prerequisites">Prerequisites</a></li> +<li><a class="reference external" href="#configuration">Configuration</a></li> +</ul> +</li> +<li><a class="reference external" href="#setup">Setup</a><ul> +<li><a class="reference external" href="#preparing-cas-server">Preparing CAS Server</a></li> +<li><a class="reference external" href="#running-cas">Running CAS</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference external" href="#resources">Resources</a></li> +</ul> + + <h3>This Page</h3> + <ul class="this-page-menu"> + <li><a href="_sources/index.txt">Show Source</a></li> + </ul> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li><a href="">CAS v0.13-118 documentation</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2009, Adam Stokes. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.5.1. + </div> + </body> +</html> \ No newline at end of file diff --git a/doc/objects.inv b/doc/objects.inv new file mode 100644 index 0000000..e0a1817 --- /dev/null +++ b/doc/objects.inv @@ -0,0 +1,3 @@ +# Sphinx inventory version 1 +# Project: CAS +# Version: 0.13 diff --git a/doc/search.html b/doc/search.html new file mode 100644 index 0000000..e2cb21b --- /dev/null +++ b/doc/search.html @@ -0,0 +1,83 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Search — CAS v0.13-118 documentation</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '', + VERSION: '0.13-118', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <script type="text/javascript" src="_static/searchtools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="" /> + <link rel="top" title="CAS v0.13-118 documentation" href="index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li><a href="index.html">CAS v0.13-118 documentation</a> »</li> + </ul> + </div> + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <h1 id="search-documentation">Search</h1> + <p> + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. + </p> + <form action="" method="get"> + <input type="text" name="q" value="" /> + <input type="submit" value="search" /> + <span id="search-progress" style="padding-left: 10px"></span> + </form> + + <div id="search-results"> + + </div> + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li><a href="index.html">CAS v0.13-118 documentation</a> »</li> + </ul> + </div> + + <div class="footer"> + © Copyright 2009, Adam Stokes. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.5.1. + </div> + <script type="text/javascript" src="searchindex.js"></script> + + </body> +</html> \ No newline at end of file diff --git a/doc/searchindex.js b/doc/searchindex.js new file mode 100644 index 0000000..6096119 --- /dev/null +++ b/doc/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({desctypes:{},terms:{all:0,identifi:0,help:0,execut:0,show:0,text:0,mnt:0,workdirectori:0,i386:0,abil:0,heavili:0,hierarchi:0,follow:0,disk:0,find:0,paramet:0,content:0,onli:0,samba:0,locat:0,system:0,kernel:0,also:0,configur:0,solut:0,specif:0,should:0,other:0,analyz:0,mail:0,tell:0,main:0,local:0,worth:0,match:0,depend:0,opt:0,crash:0,variou:0,python:0,timestamp:0,overal:0,initi:0,"break":0,mention:0,vmcore:0,upstream:0,ticket:0,now:0,relev:0,requir:0,introduct:0,like:0,organ:0,level:0,edit:0,list:0,authent:0,server:0,easili:0,necessari:0,either:0,have:0,contain:0,debug:0,output:0,architectur:0,where:0,mount:0,mean:0,wiki:0,x86_64:0,set:0,dump:0,some:0,direct:0,emac:0,result:0,pass:0,download:0,further:0,extract:0,tmp:0,shown:0,detect:0,mailserv:0,collect:0,databas:0,section:0,access:0,version:0,listinfo:[],debuglevel:0,determin:0,email:0,machin:0,core:0,assumpt:0,run:0,advanc:0,gener:0,each:0,usag:0,given:0,here:0,job:0,base:0,prerequisit:0,address:0,releas:0,org:0,come:0,sinc:0,valu:0,popul:0,sub:0,last:0,"500gb":0,admin:0,current:0,http:[],keep:0,vmlinux:0,etc:0,instanc:0,yum:0,includ:0,mani:0,typic:0,com:0,assign:0,first:0,load:0,rang:0,via:0,simpli:0,repositori:0,primarili:0,point:0,onc:0,modul:0,within:0,prefer:0,number:0,automat:0,crash_32:0,down:0,filenam:0,instruct:0,least:0,path:0,instal:0,next:0,storag:0,size:0,differ:0,git:0,mailman:[],describ:0,would:0,area:0,associ:0,question:0,two:0,messag:0,mark:0,avail:0,few:0,editor:0,rpm:0,recommend:0,hassl:0,addit:0,type:0,"final":0,store:0,rhel:0,files:0,media:0,from:0,properli:0,option:0,name:0,debuginfo:0,smtp:0,suit:0,thei:0,specifi:0,ani:0,administr:0,"var":0,"1tb":0,func:0,exactli:0,analyst:0,those:0,must:0,info:0,made:0,look:0,hous:0,provid:0,checkout:0,setup:0,work:0,uniqu:0,alter:0,defin:0,below:0,can:0,abov:0,visit:0,quickli:0,root:0,epel:0,timefram:0,later:0,conf:0,process:0,certain:0,dure:0,arg:0,share:0,anywher:0,accept:0,packag:0,exit:0,exist:0,uncom:0,file:0,need:0,fedorahost:0,sever:0,fill:0,queue:0,multipl:0,form:0,want:0,thing:0,suggest:0,user:0,when:0,same:0,note:0,how:0,valid:0,statement:0,build:0,which:0,command:0,eventu:0,prepar:0,enabl:0,analysi:0,therefor:0,express:0,resourc:0,x86:0,corefil:0,clone:0,who:0,what:0,reflect:0,most:0,regular:0,temporari:0,log:0,deploi:0,usr:0,data:0,fedora:0,repo:0,task:0,essenti:0,binari:0,filesystem:0,directori:0,gather:0,descript:0,issu:0,inform:0,exampl:0,environ:0,place:0,thi:0,anoth:0,rpmfilter:0,order:0,latest:0},titles:["Core Analysis System (CAS)"],modules:{},descrefs:{},filenames:["index"]}) \ No newline at end of file

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

cas February 2009