/usr/share/doc/pida/html/handbook.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.2.1" />
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
}

strong {
  font-weight: bold;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1 {
  border-bottom: 2px solid silver;
}
h2 {
  border-bottom: 2px solid silver;
  padding-top: 0.5em;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revision {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble,
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock {
  margin-right: 0%;
}
div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock > div.content {
  padding-left: 2.0em;
}

div.attribution {
  text-align: right;
}
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
}

div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
}

div.verseblock div.content {
  white-space: pre;
}

div.imageblock div.content { padding-left: 0; }
div.imageblock img { border: 1px solid silver; }
span.image img { border-style: none; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: italic;
}
dd > *:first-child {
  margin-top: 0;
}

ul, ol {
    list-style-position: outside;
}
ol.olist2 {
  list-style-type: lower-alpha;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}

div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hlist td {
  padding-bottom: 5px;
}
td.hlist1 {
  vertical-align: top;
  font-style: italic;
  padding-right: 0.8em;
}
td.hlist2 {
  vertical-align: top;
}

@media print {
  div#footer-badges { display: none; }
}

/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-content {
  padding-left: 2.0em;
}

div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
</script>
<title>PIDA Handbook</title>
</head>
<body>
<script>
</script>
<style>
div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
</style>
<div class="header">
<h1>PIDA Handbook</h1>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="preamble">
<div class="sectionbody">
<p>PIDA is an IDE (integrated development environment). PIDA is different from
other IDEs in that it will use the tools that are already available rather than
attempting to reinvent each one. PIDA is written in Python with the PyGTK
toolkit, and although it is designed to be used to program in any language, PIDA
has fancy Python IDE features.</p>
<p>This document describes PIDA features and usage. It is aimed at providing help
for new comers and advanced users. Developer documentation is available in other
sources for those who want to hack PIDA.</p>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/caution.png" alt="Caution" />
</td>
<td class="content">Since PIDA is still being actively worked on, this manual is still
incomplete and will grow with time.</td>
</tr></table>
</div>
<div class="quoteblock">
<div class="quoteblock-content">
<div class="verseblock">
<div class="content">&lt;tito&gt; aa_: PIDA is an acronym ?
&lt;Zapek&gt; PIDA Is Da Acronym
&lt;mnemoc&gt; Python Integrated Developmenet Architecture iirc
&lt;aa_&gt; Zapek: I like it</div></div>
<div class="attribution">
&#8212; #pida on freenode.net
</div></div></div>
</div>
</div>
<h2><a id="introduction"></a>1. Introduction</h2>
<div class="sectionbody">
<p>There are many IDE around, and some are very good. But lots of them are also
<em>closed</em> in the sense that they are limited in terms of extensibility or
communication with other tools. On the other hand, some of you may want to
change your editor for anything else, even if you have to rely on external tools
to complete its features.</p>
<p>PIDA was designed with these problems in mind. PIDA's <em>motto</em> is to reuse the
tools that proved to be useful and solid, and to provide the glue for them. PIDA
is written in Python with <strong>PyGTK</strong>, is easily extensible through plug-ins and can
embed any editor provided someone writes an adapter for it.</p>
<p>PIDA has a number of unique features, such as</p>
<ul>
<li>
<p>
Embedding Vim, Emacs or any editor.
<br />[Of course, the editor has to provide a way to communicate with for
external programs. <strong>Moo</strong>, <strong>Scite</strong>, and probably <strong>GEdit</strong> could be candidates]<br />
</p>
</li>
<li>
<p>
Using any version control system.
</p>
</li>
</ul>
</div>
<h2><a id="requirements"></a>2. Requirements</h2>
<div class="sectionbody">
<p>Because of the nature of PIDA there are a number of tools that may optionally
be used, but are not absolutely required. The list of requirements is
therefore split into absolute and relative requirements.</p>
<h3>2.1. Absolute Requirements</h3>
<div class="title">Python</div>
<p>Python is the programming language PIDA is written in. PIDA requires any
version of Python greater than or equal to 2.4. Python is available from
the `Python Web Site`_ or more likely packaged for your distribution. Most
desktop Linuxes come with Python preinstalled.</p>
<div class="title">PyGTK</div>
<p>PyGTK are the Python bindings for the GTK toolkit. Note that you will also
need to have GTK installed for them to work. These are available from the
`PyGTK Web Site`<em> and the `GTK Web Site`</em> or more likely packaged by your
Linux distribution.</p>
<div class="title">Kiwi</div>
<p>Kiwi is a helper library for PyGTK. It was decided a while ago that there should
not be a duplication in effort in creating common widgets and patterns withing
PyGTK programs. For this reason common things exist in Kiwi, and PIDA developers
contribute fixes back upstream to Kiwi. Kiwi is available in the contrib
directory of the source code. It is recommended to use this version if at all
possible. It contains no changes from the original, but it is ensured to have
all the latest fixes.</p>
<div class="title">VTE</div>
<p>VTE is a GTK terminal widget that is used by gnome-terminal. PIDA uses this for
many things, and since it is in most distributions that Gnome is in, we have
made it an absolute requirement.</p>
<h3>2.2. Compilation Requirements</h3>
<div class="title">Python development headers</div>
<p>These are usually available in your distribution as python-dev. They are the
headers required for building python extensions.</p>
<div class="title">PyGTK development headers</div>
<p>These are required to build the external moo_stub extension, and are usually
available in your distribution as pygtk-dev or pygtk-devel etc. packages.</p>
</div>
<h2><a id="installation"></a>3. Installation</h2>
<div class="sectionbody">
<p>PIDA is still not considered finalised by its authors. The most recent version
lies in SVN repository, but milestones are available though to provide a
snapshot of the development to the less adventurers.</p>
<h3><a id="installation_compilation"></a>3.1. Compilation from sources</h3>
<p>The source code comes with a standard Python installation method.</p>
<div class="title">Build</div>
<p>The build step is necessary even when running from source so as to ensure that
the extensions are built.</p>
<div class="listingblock">
<div class="content">
<pre><tt>python setup.py build</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="title">Debian Users</div>
<p>Due to the location of headers on Debian, users must first:</p>
<div class="listingblock">
<div class="content">
<pre><tt>export PKG_CONFIG_PATH=/usr/lib/pkgconfig/python2</tt></pre>
</div></div>
</td>
</tr></table>
</div>
<div class="title">Install</div>
<p>Installation is the recommended method of running PIDA. Running from source
should be reserved for people who know what they are doing.</p>
<div class="listingblock">
<div class="content">
<pre><tt>python setup.py install</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<p>you may need to use sudo or equivalent to obtain superuser access if you are
installing to a global location.</p>
</td>
</tr></table>
</div>
<div class="title">Run from source</div>
<p>First copy the moo_stub.so (that was built in the build stage) from the build/
directory somewhere into PYTHONPATH or the working directory. Then execute:</p>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<p>Running from source is generally reserved for developers of PIDA, or those
people who really know what they are doing. It is very useful to be able to
make a change and test it immediately. It is not recommended to use this as a
general running method.</p>
</td>
</tr></table>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>run-pida.sh</tt></pre>
</div></div>
<h3>3.2. Obtaining the development source code</h3>
<p>The current development version is hosted on Google Code Subversion repository.
You can use the following command to anonymously check the latest source code.</p>
<div class="listingblock">
<div class="content">
<pre><tt>svn checkout http://pida.googlecode.com/svn/trunk/ pida</tt></pre>
</div></div>
<p>PIDA can be executed from its source directory as outlined above.</p>
<h3><a id="installation_packages"></a>3.3. Distribution packages</h3>
<p>Though there is still a long way before PIDA can be considered mature, it is
already packaged by several Linux and BSD(FIXME?) distributions. Use the
guidelines of your distribution to install or remove PIDA from your system.</p>
<div class="tableblock">
<table rules="none"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table: Known distributions that provide PIDA</caption>
<col width="160" />
<col width="262" />
<col width="137" />
<thead>
  <tr>
    <th align="left">
    Distribution
    </th>
    <th align="left">
    Distribution version
    </th>
    <th align="left">
    PIDA version
    </th>
  </tr>
</thead>
<tbody valign="top">
  <tr>
    <td align="left">
    Debian
    </td>
    <td align="left">
    Etch (<em>stable</em>)
    </td>
    <td align="left">
    0.3.1
    </td>
  </tr>
  <tr>
    <td align="left">
    Debian
    </td>
    <td align="left">
    Lenny (<em>testing</em>)
    </td>
    <td align="left">
    0.4.4
    </td>
  </tr>
  <tr>
    <td align="left">
    Debian
    </td>
    <td align="left">
    Sid (<em>unstable</em>)
    </td>
    <td align="left">
    0.4.4
    </td>
  </tr>
  <tr>
    <td align="left">
    Gentoo
    </td>
    <td align="left">
    FIXME.
    </td>
    <td align="left">
    FIXME.
    </td>
  </tr>
  <tr>
    <td align="left">
    Ubuntu
    </td>
    <td align="left">
    Breezy Badger
    </td>
    <td align="left">
    0.2.2
    </td>
  </tr>
  <tr>
    <td align="left">
    Ubuntu
    </td>
    <td align="left">
    Dapper Drake
    </td>
    <td align="left">
    0.2.2
    </td>
  </tr>
  <tr>
    <td align="left">
    Ubuntu
    </td>
    <td align="left">
    Edgy Eft
    </td>
    <td align="left">
    0.3.1
    </td>
  </tr>
  <tr>
    <td align="left">
    Ubuntu
    </td>
    <td align="left">
    Feisty Fawn
    </td>
    <td align="left">
    0.3.1
    </td>
  </tr>
  <tr>
    <td align="left">
    Ubuntu
    </td>
    <td align="left">
    Gutsy
    </td>
    <td align="left">
    0.4.4
    </td>
  </tr>
</tbody>
</table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/important.png" alt="Important" />
</td>
<td class="content">There are chances that the version packaged is a bit outdated. Please
consider trying to install the most recent version before reporting a bug. You
can either compile pida from sources or try to use a package prepared for a more
recent version of your distribution.</td>
</tr></table>
</div>
<h3><a id="installation_windows"></a>3.4. MS Windows</h3>
<p>FIXME.</p>
<p>Some pointers on how to install PIDA dependencies can be found on <a href="http://code.google.com/p/pida/wiki/WindowsInstallation">http://code.google.com/p/pida/wiki/WindowsInstallation</a></p>
<h3><a id="installation_mac"></a>3.5. Mac OS X</h3>
<p>FIXME.</p>
</div>
<h2><a id="getting_started"></a>4. Getting started</h2>
<div class="sectionbody">
<p>FIXME.</p>
<h3><a id="getting_started_wizard"></a>4.1. First run wizard</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">This feature is planned for a future version of PIDA, which is still undetermined yet.</td>
</tr></table>
</div>
<h3><a id="getting_started_window"></a>4.2. The PIDA window</h3>
<p>Like any other IDE, PIDA provides in one window all the tools you need to edit
your files, compile your programs, invoke external tools, explore a project
space or a file hierarchy, and so on. The PIDA window is organized with a menu,
a toolbar, multiple views and a status bar. Many of these elements are optional
and can be hidden or displayed at will.</p>
<h4>4.2.1. The menu bar</h4>
<dl>
<dt>
<strong>File</strong>
</dt>
<dd>
<p>
This menu offers all file related operations, like creating, saving, or closing
a document, but also all version control operations. PIDA also provides sessions
management, and the <strong>File</strong> menu permits to save the current session or load a
previous one.
</p>
</dd>
<dt>
<strong>Edit</strong>
</dt>
<dd>
<p>
This menu serves two purposes. First, it provides facilities to search documents
throughout a project, or directories. But PIDA preferences and shortcuts
settings are also modifiable from here.
</p>
</dd>
<dt>
<strong>Project</strong>
</dt>
<dd>
<p>
This menu provides version control at project level. From there, it is also
possible to modify the properties of a project and to start the configured
controllers.
</p>
</dd>
<dt>
<strong>Tools</strong>
</dt>
<dd>
<p>
Additional utilities, like a terminal and a Python shell for PIDA introspection.
</p>
</dd>
<dt>
<strong>View</strong>
</dt>
<dd>
<p>
The PIDA window can be customized from there, displaying or hiding special views
or elements like the menu bar or the tool bar. This menu also provides shortcuts
to access quickly the most important views of the window, like the file
manager.
</p>
</dd>
<dt>
<strong>Help</strong>
</dt>
<dd>
<p>
Provides only the credits window for now.
</p>
</dd>
</dl>
<h4>4.2.2. The status bar</h4>
<p>The status bar provides live information on</p>
<ul>
<li>
<p>
The current project.
</p>
</li>
<li>
<p>
The current directory browsed in the file manager.
</p>
</li>
<li>
<p>
Information on t file currently edited, like its name, encoding and size.
</p>
</li>
</ul>
<h4>4.2.3. The editor</h4>
<p>The editor is the core element of PIDA. All other views only provide utilities
to fill the missing features of the editor, or integrate important accessories
&#8212; like a debugger &#8212; or give a quick access to external tools &#8212; like a
terminal. The editor is also the central view of PIDA. All other views can be
moved around it (see <a href="#getting_started_window_views">See Views</a>).</p>
<p>PIDA can support any editor. Editor shortcuts and features directly depend on
what editor you prefer. It is possible that some features of the chosen editor
and PIDA features overlap. In this case, both can be used, but the feature
implemented by PIDA will certainly provide better integration with the other
tools of the IDE.</p>
<h4><a id="getting_started_window_views"></a>4.2.4. Views</h4>
<p>All elements in the PIDA window, except the editor, the menu bar, the toolbar
and status bar, can be moved (remember that the menu bar and the toolbar can be
hidden though).</p>
<p>FIXME: must choose carefully the vocabulary for elements of the views and keep them consistent.</p>
<h3><a id="getting_started_configuration"></a>4.3. PIDA configuration</h3>
<p>FIXME: gconf, .pida</p>
</div>
<h2><a id="services"></a>5. Core services</h2>
<div class="sectionbody">
<p>FIXME.</p>
<h3>5.1. Editor</h3>
<h4>5.1.1. Vim</h4>
<p>FIXME.</p>
<h4>5.1.2. Emacs</h4>
<p>FIXME.</p>
<h3>5.2. File Manager</h3>
<p>FIXME.</p>
<h3><a id="service_project_manager"></a>5.3. Project Manager</h3>
<p>FIXME.</p>
<h3><a id="service_terminal"></a>5.4. Terminal</h3>
<p>FIXME.</p>
<h3><a id="service_version_control"></a>5.5. Version Control</h3>
<p>FIXME.</p>
<h3>5.6. Preferences</h3>
<p>FIXME.</p>
</div>
<h2><a id="plugins"></a>6. Plug-ins</h2>
<div class="sectionbody">
<p>FIXME.</p>
<h3>6.1. Bookmark</h3>
<p>Manage bookmark (files, directories&#8230;)</p>
<h3>6.2. Checklist</h3>
<p>FIXME.</p>
<h3>6.3. GTags</h3>
<p>GNU Global Integration » Build global index, search through database</p>
<h3>6.4. Library</h3>
<p>FIXME.</p>
<h3>6.5. Man</h3>
<p>Search and browse man page</p>
<h3>6.6. PasteBin</h3>
<p>Send code to a pastebin service</p>
<h3>6.7. Python</h3>
<p>Show class/function from python file, and show compilation errors</p>
<h3>6.8. RFC</h3>
<p>Download RFC index, search and view RFC pages inside PIDA</p>
<h3>6.9. TODO</h3>
<p>Manage a personal todo list per project</p>
<h3>6.10. Trac</h3>
<p>View bugs from Trac project inside PIDA</p>
</div>
<h2>7. PIDA Service Authoring Guide</h2>
<div class="sectionbody">
<p>PIDA has a very general concept of services (you might call them plugins in
another application). In general, a service is able to define any PIDA
function, that is anything PIDA can do, a service can do it too.</p>
<p>PIDA is essentially a bunch of services bound together by a <strong>Boss</strong>. The
services are discovered from service directories and loaded by a <strong>Service
Manager</strong> for the Boss.</p>
<h3>7.1. Service Overview</h3>
<p>A service is comprised of a directory on the file system. This directory is a
Python package with data.</p>
<p>The structure of this directory is like so for a service named "myservice":</p>
<div class="listingblock">
<div class="content">
<pre><tt>    myservice/
        __init__.py
        myservice.py
        service.pida
        test_myservice.py
        data/
        glade/
        pixmaps/
        uidef/
            myservice.xml</tt></pre>
</div></div>
<h3>7.2. Creating a starter service</h3>
<p>As will be seen, there is a large amount of boiler plate involved in creating
a service, and so we have provided the creator.py script in the tools/
directory of the source distribution. You should run this with the single
argument <em>service</em> and you will be asked a few questions to complete the
process:</p>
<div class="listingblock">
<div class="title">Example: Using tools/creator.py</div>
<div class="content">
<pre><tt>ali@book:~/working/pida$ python tools/creator.py service
Please enter the path for the service [/home/ali/working/pida/pida/services]: /tmp
Please enter the Service name: MyService
Creating service my service in /tmp</tt></pre>
</div></div>
<h3>7.3. Individual Components</h3>
<h4>7.3.1. myservice.py</h4>
<p>This is the file containing the Python code for the service. It is a Python
module and should contain an attribute <tt>`Service</tt>`, which is the Class which
will be instantiated as the service.</p>
<p>The service class has a number of class attributes which describe its
behaviour. These behaviours are:</p>
<ul>
<li>
<p>
Configuration
</p>
</li>
<li>
<p>
Commands
</p>
</li>
<li>
<p>
Events
</p>
</li>
<li>
<p>
Features
</p>
</li>
<li>
<p>
Actions
</p>
</li>
</ul>
<div class="title">Configuration</div>
<p>This is the global configuration options for the service.</p>
<div class="title">Commands</div>
<p>Commands are the external interface for the service. They can be called by any
other service, and this decoupling is cleaner than expecting, and calling an
actual method on a service.</p>
<div class="title">Events</div>
<p>Events are an asynchronous call back for the service. Any other service can
subscribe to an event explicitly, and by subscribing is notified when an event
occurs.</p>
<div class="title">Features</div>
<p>Features are behaviours that a service expects other services to provide for
it. If this makes no sense, imagine a situation in which a file-manager
service expects any service to subscribe to its right-click menu on a file. In
this way, the actions provided on that right-click menu are decentralized from
the menu itself, and can be provided anywhere. This is very similar to a
classical (e.g. Trac) <strong>extension point</strong>.</p>
<div class="title">Actions</div>
<p>Actions are gtk.Actions and are used in the user interface. An action maps
directly to a single toolbar and menu action, and contains the necessary
information to create this user interface item from it, including label, stock
image etc.</p>
<h4>7.3.2. Other files and directories</h4>
<div class="title"><em>init</em>.py</div>
<p>This file is required so that Python recognises the directory as a legitimate
Python package.</p>
<div class="title">service.pida</div>
<p>This empty file is just present to identify the package as a PIDA service.</p>
<div class="title">data/</div>
<p>This directory should contain any data files for the service that are not
included in the other resource directories.</p>
<div class="title">glade/</div>
<p>This directory contains the glade files for the service's views. Although
views can be created using Python-only, it is recommended for more detailed
plugin views that they use glade.</p>
<div class="title">pixmaps/</div>
<p>This directory should contain any custom pixmaps for the service. These can be
used in any way.</p>
<div class="title">uidef/</div>
<p>This directory should contain the UI Definition XML files for the service.
These are gtk.UIManager XML files, and define the menu bar and toolbar items
for the service. The file myservice.xml is automatically loaded by PIDA, but
others can exist in this directory and could be used to populate popup menus
or to be further merged with the standard UI defnition.</p>
<h3>7.4. Service Options</h3>
<p>Options are currently stored in the GConf database. They are registered at
activation time of the service. Each service has its own directory in the GConf
database at /apps/pida/service_name. On registering the options, if they do not
exist, they are set to the default value.</p>
<p>Service options are defined in the service's OptionsConfig. This class should be
the options_config attribute of the service class, and should subclass
pida.options.OptionsConfig.</p>
<p>The OptionsConfig has a method named create_options, which is called on service
activation. This method should contain the calls to create_option to create the
options. The signature for create_option is:</p>
<div class="listingblock">
<div class="content">
<pre><tt>create_option(name, label, type, default, documentation)</tt></pre>
</div></div>
<p>For example:</p>
<div class="listingblock">
<div class="content">
<pre><tt>class MyServiceOptions(OptionsConfig):

    def create_options(self):
        self.create_option(
            'myoption',
            'myoption label',
            OTypeString,
            'default_value',
            'A string describing the option',
        )


class MyService(Service):

    options_config = MyServiceOptions</tt></pre>
</div></div>
<h3>7.5. Service Commands</h3>
<p>Commands are the external interface for a service. This interface is
specifically provided to other services for use of service activities.</p>
<h4>7.5.1. Defining Commands</h4>
<p>Commands are defined as methods on the <tt>commands_config</tt> attribute of the
Service class. This attribute should reference a subclass of
<tt>pida.core.commands.CommandsConfig</tt> class. Any method defined on that class will
be available as a command on the service.</p>
<h4>7.5.2. Calling service commands</h4>
<p>Commands are called on a service using the <tt>cmd</tt> method of a service. Calling
commands on other services must be performed through the Boss' <tt>cmd</tt> method
which takes as an additional parameter then name of the target service.</p>
<p>For example, execute a shell from a service:</p>
<div class="listingblock">
<div class="content">
<pre><tt>self.boss.cmd(
    'commander',        <b>(1)</b>
    'execute_shell',    <b>(2)</b>
)</tt></pre>
</div></div>
<ol>
<li>
<p>
The target service name
</p>
</li>
<li>
<p>
The target service command
</p>
</li>
</ol>
<h4>7.5.3. Using arguments on service commands</h4>
<p>All arguments to service commands must be passed as keyword arguments. Because
of this, they can be passed in any order after the servicename, and commandname
parameters.</p>
<p>For example, execute a shell from a service starting in an explicit directory:</p>
<div class="listingblock">
<div class="content">
<pre><tt>self.boss.cmd(
    'commander',
    'execute_shell',
    cwd = '/',
)</tt></pre>
</div></div>
<h3>7.6. Service Events</h3>
<p>The events are asynchronous call back for the service. So any other service can
subscribe its call back to an event, and it will get called back once the event
occurs.</p>
<h4>7.6.1. Events definition</h4>
<p>To create a new event, like earlier, you just need to create a new class
that you can call <em>MyServiceEvents</em>, and you bind it to your <em>MyService</em>
class doing <em>events_config = MyServiceEvents</em>.</p>
<div class="listingblock">
<div class="content">
<pre><tt>class MyServiceEvents(EventsConfig):
    def create_events(self):
        [...]
    def subscribe_foreign_events(self):
        [...]

class MyService(Service):
    events_config = MyServiceEvents</tt></pre>
</div></div>
<p>So in that example code, you can notice the two methods you need to implement
to manage your own events. You have to define in create_events all the events
your service is about to use, and in subscribe_foreign_events all the events
from other services your service needs.</p>
<h4>7.6.2. Create your own new events</h4>
<p>So, once you have your <em>EventsConfig</em> ready, you need to implement the
create_events method so you can have your own new events. Three steps
are needed to create an event :</p>
<div class="literalblock">
<div class="content">
<pre><tt>(1) You call self.create_event() on the event name
(2) You subscribe a new callback to the event you just made
(3) You implement the new event's callback so it acts when it is emitted.</tt></pre>
</div></div>
<div class="listingblock">
<div class="content">
<pre><tt>    def create_events(self):
        self.create_event('myevent')                     # (1)
        self.subscribe_event('myevent', self.on_myevent) # (2)
        self.create_event('my_foreign_event')

    def on_myevent(self,param=None):                     # (3)
        print 'myevent receipt'
        if param != None:
            print 'with param:', param</tt></pre>
</div></div>
<h4>7.6.3. Subscribe to other services' events</h4>
<p>We have seen how we can bind callbacks to events you created in
your own service. But you often need to interact with other services
as well. To do so, you need to implement the subscribe_foreign_events()
method the following way :</p>
<div class="listingblock">
<div class="content">
<pre><tt>    def subscribe_foreign_events(self):
        self.subscribe_foreign_event('editor', 'started',
                                     self.on_editor_startup)</tt></pre>
</div></div>
<p>for each event you want to bind a call back, you need to call the
subscribe_foreign_event() method. In the example above, when the editor
service launches the started event, self.on_editor_startup() gets called.</p>
<div class="listingblock">
<div class="content">
<pre><tt>self.subscribe_foreign_event('SERVICE_NAME', 'EVENT_NAME', CALLBACK_FUNCTION)</tt></pre>
</div></div>
<p>where <strong>SERVICE_NAME</strong> is the destination service, <strong>EVENT_NAME</strong> the event to bind to,
<strong>CALLBACK_FUNCTION</strong> the function to be called when the event is emitted.</p>
<p>Now suppose you want to give other services' programmers an event of your own
service. To do so, you need to call create_event() in create_events() with the
name of your event (ie see <em>my_foreign_event</em> above).</p>
<p>Then in the foreign service, in the subscribe_foreign_events() method you just
need to subscribe to the event:</p>
<div class="listingblock">
<div class="content">
<pre><tt>    def subscribe_foreign_events(self):
        self.subscribe_foreign_event('myservice', 'my_foreign_event',
                                     self.on_myservice_foreign_event)</tt></pre>
</div></div>
<p>and finally define your callback.</p>
<h4>7.6.4. Events emition</h4>
<p>Now you have defined and bound all your events in your service and all
you need is to emit them when you need them to be executed. Well, it's
fairly simple, just call the emit() method :</p>
<div class="listingblock">
<div class="content">
<pre><tt>    [...]
    self.emit('myevent')
    self.emit('myevent', param='hello world')
    self.emit('my_foreign_event')
    [...]
    self.get_service('myservice').emit('myevent')
    self.get_service('myservice').emit('myevent', param='hello from some other place')
    self.get_service('myservice').emit('my_foreign_event')
    [...]</tt></pre>
</div></div>
<p>As you can see in the examples above, emit can be used in different contexts
and with or without parameters. As a rule, every event defined can be called
using the emit() method either from your own service (ie in <em>MyService</em>) or
from someone else's service (then you use get_service().emit()).</p>
<p>If your callback function needs parameters, you need to give the options to
the emit method. You can also use, as in the above example, non-mandatory
parameters.</p>
<h3>7.7. Service Views</h3>
<p>Service views are almost anything that appears visually in PIDA (apart from the
main toolbar and menubar). All of these views belong to a service.</p>
<h4>7.7.1. Creating Views</h4>
<p>Views may be designed in Glade3, or in pure <a href="#PyGTK">[PyGTK]</a>. Each method of view
creation has its advantages and disadvantages, and these are discussed below.</p>
<h4>7.7.2. Glade3 Views</h4>
<p>Views created with Glade3 have the following advantages:</p>
<ul>
<li>
<p>
Better maintainability
</p>
</li>
<li>
<p>
Automatic signal callback connection
</p>
</li>
</ul>
<p>The glade-file itself should be places in the directory glade/ in the service
directory, and should be named appropriately so as not to conflict with any
other service glade file. The extension <tt>.glade</tt> is preferred. So, for example a
well named glade file is <tt>project-properties-editor.glade</tt>.</p>
<p>This glade file is used by subclassing <tt>pida.ui.views.PidaGladeView</tt> and setting
the gladefile attribute on the class, for example for the glade file above:</p>
<div class="listingblock">
<div class="content">
<pre><tt>from pida.ui.views import PidaGladeView

class ProjectPropertiesView(PidaGladeView):

    gladefile = 'project-properties-editor'</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">The glade file attribute omits the extension part of the file name.</td>
</tr></table>
</div>
<p>The glade-file should contain a single top-level container (usually a
<tt>gtk.Window</tt>), and this <strong>must have the same name as the glade file (without
extension</strong>.</p>
<p>The widget inside this container will be taken out of the Window and
incorporated into Pida's view.</p>
<p>All widgets in the glade view, are attached to the view instances namespace, so
that they can be accessed from the instance, for example if there is a text entry called
<tt>name_entry</tt>, the attribute <tt>self.name_entry</tt> or <tt>my_view.name_entry</tt> would
reference that entry.</p>
<p>Signals of items in the glade view are automatically connected if you provide
the correct method on the glade view. These methods are named as
<tt>on_&lt;widget_name&gt;__&lt;signal_name&gt;</tt>. For example, if there is a button on the
view called <tt>close_button</tt>, and you wish to connect to it's <tt>clicked</tt> signal,
you would provide the following method in order to automatically connect the
signal for the widget:</p>
<div class="listingblock">
<div class="content">
<pre><tt>def on_close_button__clicked(self, button):
    print '%s was clicked!' % button</tt></pre>
</div></div>
<h4>7.7.3. Pure PyGTK Views</h4>
<p>These views should subclass <tt>pida.ui.views.PidaView</tt> and should create the
necessary widgets by overriding the create_ui method. The widgets can be added
to the view by using the <tt>view.add_main_widget(widget, expand=True, fill=True)</tt>.
The widgets will be added to the top-level VBox in the view.</p>
<p>There is no signal autoconnection, and widgets behave exactly as if they had
been created with PyGTK in any other circumstance.</p>
<h4>7.7.4. Instantiating views</h4>
<p>The service can instantiate its views at any time. They should pass the instance
of the service as the first parameter to the View constructor. The service will
then be stored as the <tt>svc</tt> attribute on the view.</p>
<h4>7.7.5. Adding Views to PIDA</h4>
<p>Views are displayed at runtime by calling the <em>window</em> service's command
<em>add_view</em>. The required paned must be passed as well as the view itself.</p>
<p>The paned attribute to the command should be one of:</p>
<ul>
<li>
<p>
<tt>Buffer</tt>
</p>
</li>
<li>
<p>
<tt>Plugin</tt>
</p>
</li>
<li>
<p>
<tt>Terminal</tt>
</p>
</li>
</ul>
<p>The buffer paned is the left sidebar, the plugin paned is the right sidebar, and
the terminal paned is the bottom bar. In general the guidelines for which paned
to add views to are:</p>
<ul>
<li>
<p>
Permanent views should be added to the Buffer paned
</p>
</li>
<li>
<p>
Views relating to the current document should be added to the Buffer or
      Plugin paned
</p>
</li>
<li>
<p>
Configuration or property views should be added to the Plugin paned
</p>
</li>
<li>
<p>
Multiple view (eg terminal emulators, diffs, and web browsers), or those
      with a lot of data should be added to the Terminal paned.
</p>
</li>
</ul>
<p>An example of adding a view of type <tt>MyServiceView</tt> to the Terminal paned is as
follows:</p>
<div class="listingblock">
<div class="content">
<pre><tt># Override the start method as a hook to when the service starts
def start(self):
    view = MyServiceView(self)
    self.boss.cmd('window', 'add_view', paned='Terminal', view=view)</tt></pre>
</div></div>
<p>Numerous other examples are available in almost every service in <tt>pida.services</tt>.</p>
<h4>7.7.6. View icons and labels</h4>
<p>View icons (the image displayed on the paned button) are referred to by their
stock ID, and set as a class attribute on the view <tt>icon_name</tt>. Similarly, the
text associating the icon is set as a class attribute on the view called
'label_text`.</p>
<p>Additionally, an <tt>icon_name</tt> and/or a <tt>label_text</tt> attribute can be passed to
the view constructor, and these will be displayed as the view's label and icon
when it is added to the PIDA main view.</p>
<h3>7.8. Using custom pixmaps in services</h3>
<p>Any pixmap placed in the pixmaps directory in the service (<tt>myservice/pixmaps</tt>)
will automatically be added as a stock image and can be used by the service
using its name (without extension) for View icons or for gtk.Buttons or
gtk.Images or any other widget which take a stock_id as an argument.</p>
<h3>7.9. Links</h3>
<ol>
<li>
<p>
<a id="PyGTK"></a>[PyGTK] <a href="http://pygtk.org">PyGTK Website</a>
</p>
</li>
</ol>
</div>
<h2>8. PIDA Plugin Authoring Guide</h2>
<div class="sectionbody">
<p>PIDA plugins are very much identical to Services. Anything you can do in a
Service, you can also do in a Plugin. There are however a few minor
differences, based on the facts that:</p>
<ol>
<li>
<p>
Plugins can be loaded and unlaoded at runtime
</p>
</li>
<li>
<p>
Plugins can be published on the PIDA community and installed
</p>
</li>
</ol>
<p>PIDA uses Plugins for all non-core funcitonality, and we have been quite
strict about this, so that we can maintain a different release schedule for
the core, and individual plugins. Because of this, Plugins which you might
expect to find in a standard IDE or a standard Python IDE must be installed.
Fortunately this is a matter of a single click.</p>
<h3>8.1. The service.pida file</h3>
<p>The service.pida file in Plugins is in the <em>ini</em> format with themetadata under
the [plugin] tag. It contains metadata that is used by the
installer and by the community website. This metadata includes:</p>
<div class="tableblock">
<table rules="all"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table: Service.pida metadata</caption>
<col width="160" />
<col width="731" />
<thead>
  <tr>
    <th align="right">
    Attribute
    </th>
    <th align="right">
    Description
    </th>
  </tr>
</thead>
<tbody valign="top">
  <tr>
    <td align="right">
    plugin *
    </td>
    <td align="right">
    Technical name of plugin (only [a-z0-9_] name)
    </td>
  </tr>
  <tr>
    <td align="right">
    name *
    </td>
    <td align="right">
    Long name of plugin
    </td>
  </tr>
  <tr>
    <td align="right">
    version *
    </td>
    <td align="right">
    Version of plugin
    </td>
  </tr>
  <tr>
    <td align="right">
    author *
    </td>
    <td align="right">
    Name of author &lt;email&gt;
    </td>
  </tr>
  <tr>
    <td align="right">
    require_pida *
    </td>
    <td align="right">
    Version of PIDA
    </td>
  </tr>
  <tr>
    <td align="right">
    category *
    </td>
    <td align="right">
    Category of plugins
    </td>
  </tr>
  <tr>
    <td align="right">
    depends
    </td>
    <td align="right">
    List of dependencies
    </td>
  </tr>
  <tr>
    <td align="right">
    lastupdate
    </td>
    <td align="right">
    Date of last update
    </td>
  </tr>
  <tr>
    <td align="right">
    website
    </td>
    <td align="right">
    Website of plugin
    </td>
  </tr>
</tbody>
</table>
</div>
<p><em>* These fields are mandatory</em></p>
<div class="listingblock">
<div class="title">Example: An example service.pida file</div>
<div class="content">
<pre><tt>[plugin]
plugin = snippets
name = Snippets
author = Ali Afshar &lt;aafshar@gmail.com&gt;
version = 0.1
require_pida = 0.5
depends = ""
category = code
description = Snippets: automatically enter repetitive text</tt></pre>
</div></div>
<h3>8.2. Publishing Plugins</h3>
<p>Plugin publishing can be done from the safety of the PIDA user interface.
First you will need to create the service directory (our advice is to use the
tools/creator.py script as outlined in the service authoring guide above).
Once your plugin is created, in PIDA, select <em>Plugin Manager</em> from tools, and
select the <em>Publish</em> tab. Enter the directory containing the service, and your
username and password for the pida community website. You will be given a
chance to edit the service metadata in the user interface. When you are happy,
select the <em>Make package and upload</em> button to complete the process.</p>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">The plugin will be placed on standby, and approved by one of the developers.
Once it is approved, anyone can download it.</td>
</tr></table>
</div>
<h3>8.3. Limitations to plugins</h3>
<p>The single limitation to a plugin is that it should not (although it can)
provide events that can be subscribed to. This is because a plugin can be
loaded and unloaded at runtime, and so plugins that depend on other plugins'
events will cease to function.</p>
<p>We say <em>"should not"</em> rather than <em>"must not"</em> because you can actually do what
you like. We have a strong philosophy about not getting in your way, but be
warned that you have been warned!</p>
</div>
<h2>9. PIDA Coding Style Guidelines</h2>
<div class="sectionbody">
<p>First read <a href="#PEP8">[PEP8]</a> (the PEP on how to write readable Python code). The PEP gives
a number of good insights. The PEP gives a few options on things, and I shall
try to clarify what I prefer here. Where this document differs from PEP8_, you
should use what is presented here, unless you are a zealot in which case you
should listen to the Python people (who are cleverer than me anyway). Also
read PEP20_ while you are at it.</p>
<h3>9.1. Indenting</h3>
<p>4 Spaces, no tabs ever ever. This is not negotiable. Emacs users please check
your settings, somehow tabs creep into emacs-written code.</p>
<h3>9.2. Line Width</h3>
<p>79 characters, perhaps 78 to be safe. This is negotiable, and there are times
when 83 character lines are acceptable. You can be the judge. I am not sure
many people use 80-character terminals these days, so we can be a bit less
hard-line than the PEP.</p>
<p>You can split lines however you wish. I personally use 3 different forms of
splitting depending on the purpose.</p>
<p>Long lists, dicts, or many paramteres to a function:</p>
<div class="listingblock">
<div class="content">
<pre><tt>service_base_classes =  [
    OptionsMixin,
    commands_mixin,
    events_mixin,
    bindings_mixin,
]</tt></pre>
</div></div>
<p>Single extra bit:</p>
<div class="listingblock">
<div class="content">
<pre><tt>def really_long_method_or_function_name(first_parameter, second_paramater,
    third_parameter)</tt></pre>
</div></div>
<p>Or:</p>
<div class="listingblock">
<div class="content">
<pre><tt>def really_long_method_or_function_name(first_parameter, second_paramater,
                                        third_parameter)</tt></pre>
</div></div>
<p>It all depends on the use at the time, and we should remember to keep it
readable.</p>
<h3>9.3. Blank Lines</h3>
<p>As <a href="#PEP8">[PEP8]</a> for 2 lines between top-level classes and functions, with one line
between methods.</p>
<p>Extra blank line "to indicate logical blocks" should be avoided at all costs
in my opinion. Real logical blocks should be used to indicate logical blocks!
If you have to do this, a comment is better than a blank line.</p>
<h3>9.4. Imports</h3>
<p>Only import the function or class you want to use, for example:</p>
<div class="listingblock">
<div class="content">
<pre><tt>from pida.ui.views import PidaView, BaseView</tt></pre>
</div></div>
<p>There are a few common exceptions like:</p>
<div class="listingblock">
<div class="content">
<pre><tt>import gtk</tt></pre>
</div></div>
<p>Multiple top-level imports are fine too if you like, but best grouped by where
they are comming from:</p>
<div class="listingblock">
<div class="content">
<pre><tt>import os, sys
import gtk, gobject, pango</tt></pre>
</div></div>
<p>Remember to import in this order:</p>
<ol>
<li>
<p>
standard library imports
</p>
</li>
<li>
<p>
related third party imports
</p>
</li>
<li>
<p>
PIDA application/library specific imports
</p>
</li>
</ol>
<h3>9.5. Whitespace</h3>
<p>Yes:</p>
<div class="listingblock">
<div class="content">
<pre><tt>def foo(blah, baz):</tt></pre>
</div></div>
<p>No:</p>
<div class="listingblock">
<div class="content">
<pre><tt>def foo ( blah , baz ):

def foo(blah,baz):</tt></pre>
</div></div>
<p>(that space after a comma is basic punctuation)</p>
<p><a href="#PEP8">[PEP8]</a> has oodles on this.</p>
<h3>9.6. Docstrings</h3>
<p>I like having the triple quotes as doubles, and for them to be on empty lines,
like so:</p>
<div class="listingblock">
<div class="content">
<pre><tt>def foo():
    """
    This is the single-line docstring
    """</tt></pre>
</div></div>
<p>Docstrings are plain nice, so please try to use them for all functions. I am
guilty of being lazy, so I can't blame anyone. Also we use API generation
which uses these doc strings, so it all helps.</p>
<p>We use Pydoctor_ with ReStructured text directives for API generation, so I
guess you should look them up too.</p>
<h3>9.7. Strings</h3>
<p>Single quoted, unless you need single quotes in them, in which case use double
quotes:</p>
<div class="listingblock">
<div class="content">
<pre><tt>my_string = 'I am a banana'
my_other_string = "I am a banana's uncle"</tt></pre>
</div></div>
<h3>9.8. Naming</h3>
<ul>
<li>
<p>
Modules as lowercase single words with no underscores, except test modules
      which should start with <tt>test_</tt>.
</p>
</li>
<li>
<p>
Functions as lower_case_with_underscores.
</p>
</li>
<li>
<p>
Classes is CamelCase. (Note: I hate camel case, but it is useful, even
      in Python to know the difference between a class and a function. Why?
      You can subclass a class.)
</p>
</li>
<li>
<p>
Module-level constants all in UPPERCASE_WITH_UNDERSCORES.
</p>
</li>
</ul>
<h3>9.9. Conditional blocks</h3>
<p>This is fine:</p>
<div class="listingblock">
<div class="content">
<pre><tt>if blah:
    baz = 1
else:
    baz = 2</tt></pre>
</div></div>
<p>And better than:</p>
<div class="listingblock">
<div class="content">
<pre><tt>    baz = 2
    if blah:
        baz = 1</tt></pre>
</div></div>
<p>But I am not going to argue, needs can force you into a certain style.
Remember, readability is key.</p>
<h3>9.10. Magic</h3>
<p>I hate magic, perhaps because I am dumb. I am really wary of using some of
Python's shoot-me-in-the-foot techniques because I have to maintain the code,
so. I have made these mistakes myself, and have (hopefully learned from the
mistakes. So:</p>
<dl>
<dt>
Meta classes
</dt>
<dd>
<p>
        Never! I have yet to see a use-case for metaclasses which did not
        relate to perverting some other library or external class. I am happy
        to be enlightened.
</p>
</dd>
<dt>
Decorators
</dt>
<dd>
<p>
        Make perfect sense in some cases, but have the danger of being over
        used, so please think carefully whether you are using them to decorate
        behaviour, or just using them for the sake of it.
</p>
</dd>
<dt>
Inner classes
</dt>
<dd>
<p>
        I have yet to see a use-case that requires these.
</p>
</dd>
</dl>
<h3>9.11. Bibliography</h3>
<ol>
<li>
<p>
<a id="PEP8"></a>[PEP8] <a href="http://www.python.org/dev/peps/pep-0008/">Python Enhancement Proposal 8</a>
</p>
</li>
<li>
<p>
<a id="PEP20"></a>[PEP20] <a href="http://www.python.org/dev/peps/pep-0020/">Python Enhancement Proposal 20</a>
</p>
</li>
<li>
<p>
<a id="Pydoctor"></a>[Pydoctor] <a href="http://codespeak.net/~mwh/pydoctor/">Pydoctor Web Site</a>
</p>
</li>
</ol>
</div>
<div id="footer">
<div id="footer-text">
Last updated 28-Jul-2007 12:48:15 BST
</div>
</div>

<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){generateToc(4)}
/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, October 2006. License: GPL */

function getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
    if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
      text += i.data;
    else if (i.firstChild != null)
      text += getText(i);
  }
  return text;
}

function TocEntry(el, text, toclevel) {
  this.element = el;
  this.text = text;
  this.toclevel = toclevel;
}

function tocEntries(el, toclevels) {
  var result = new Array;
  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
  // Function that scans the DOM tree for header elements (the DOM2
  // nodeIterator API would be a better technique but not supported by all
  // browsers).
  var iterate = function (el) {
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
        var mo = re.exec(i.tagName)
        if (mo)
          result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
        iterate(i);
      }
    }
  }
  iterate(el);
  return result;
}

// This function does the work. toclevels = 1..4.
function generateToc(toclevels) {
  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "toc" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
}
/*]]>*/
</script>
</body>
</html>
pida 0.5.1-6 / usr / share / doc / pida / html / handbook.html
