users-guide.xml

<?xml version="1.0"?>
<book xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation='http://www.docbook.org/xsd/4.4/docbook.xsd' >
<!-- :indentSize=2:tabSize=2: -->
<bookinfo>
  <title>CoffeeScript SideKick Plugin Guide</title>
  <authorgroup>
    <author><firstname>Marc</firstname><surname>Häfner</surname></author>
  </authorgroup>

  <legalnotice>
    <title>Legal Notice</title>
    <para>
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1 or
      any later version published by the Free Software Foundation; with no
      <quote>Invariant Sections</quote>, <quote>Front-Cover Texts</quote> or
      <quote>Back-Cover Texts</quote>, each as defined in the license. A copy
      of the license can be found in the file
      <filename>COPYING.DOC.txt</filename> included with jEdit.
    </para>
  </legalnotice>
</bookinfo>

<chapter id="intro"><title>Introduction</title>
  <para>
    This plugin provides a simple SideKick parser for the
    <ulink url="http://coffeescript.org/">CoffeeScript</ulink> language.
  </para>
  <para>
    A modified version of CoffeeScript 1.6.3 is used for parsing.
    The Sidekick tree is constructed from the resulting AST.
  </para>
</chapter>

<chapter id="options"><title>Options</title>
  <glosslist>
    <glossentry>
      <glossterm>Show parser errors in ErrorList</glossterm>
      <glossdef><para>
        Syntax errors encountered while parsing will be forwarded to the
        Error List.</para></glossdef>
    </glossentry>
    <glossentry>
      <glossterm>Display function parameters</glossterm>
      <glossdef><para>
        Display a simplified version of the parameter definition, without
        default values.
        </para><para>
        Destructuring parameters are partially supported: In objects only
        the lookup keys are displayed. If a key in an array is to complex it
        will be replaced by <code>&lt;?&gt;</code>.</para></glossdef>
    </glossentry>
    <glossentry>
      <glossterm>Show docco-style headings</glossterm>
      <glossdef><para>
        Show Markdown headings in single-line comments in the structure tree.
      </para></glossdef>
    </glossentry>
    <glossentry>
      <glossterm>Show icons</glossterm>
      <glossdef><para>
        Show icons in the SideKick tree, mimicking Eclipse Java style.
      </para></glossdef>
    </glossentry>
    <glossentry>
      <glossterm>Show prefix for hidden and class members</glossterm>
      <glossdef><para>
        Prefix hidden members with a minus (<code>-</code>) and class members
        with an at symbol (<code>@</code>).
        </para><para>
        (Hidden members are functions and subclasses in a class that are not
        assigned as a prototype property.)</para></glossdef>
    </glossentry>
    <glossentry>
      <glossterm>Display node type</glossterm>
      <glossdef><para>
        Append the type to classes (<code>&lt;class&gt;</code>) and tasks
        (<code>&lt;task&gt;</code>).</para></glossdef>
    </glossentry>
  </glosslist>
</chapter>

<chapter id="parser"><title>SideKick Parser</title>
  <itemizedlist><title>Recognized constructs</title>
    <listitem>
      <para>
        Class declarations
        <programlisting>
            class C
        </programlisting>
      </para>
    </listitem>
    <listitem>
      <para>
        Assignments of class and code to variables or properties
        (including conditional assignments)
        <programlisting>
          f = (x, y, z) ->
          C = class
          o.f = (a, b)->
          f ?= () ->
        </programlisting>
      </para>
    </listitem>
    <listitem>
      <para>
        Property assignments inside class declarations
        <programlisting>
          class C
            @static: (a, b) ->
            method: (x, y, z) ->
            D: class
        </programlisting>
      </para>
    </listitem>
    <listitem>
      <para>
        Task definitions in a Cakefile
        <programlisting>
          task "build", "builds the source", -> ...
        </programlisting>
      </para>
    </listitem>
  </itemizedlist>
  <para>
    These must be either top level constructs or within previously recognized
    constructs. They may not be parenthesised or otherwise wrapped (e.g.
    inside call parameters).
  </para>
  <formalpara><title>The structure tree</title><para>
    Represents the source structure (which is not necessarily the functional structure).
  </para></formalpara><para>
    The name of a tree node is the first (leftmost) recognizable assignment or
    the "real" class name. Property assignments will result in a dotted name.
    <informalexample><simplelist><member>
      <code>exports['E'] = D = class</code> will show up as a single node
      <computeroutput>exports.E</computeroutput>.
    </member><member>
      <code>exports['E'] = D = class C</code> will result in a node
      <computeroutput>C</computeroutput>.
    </member></simplelist></informalexample>
  </para>
</chapter>

<chapter id="compile"><title>Compile action</title>
  <para>
    This plugin provides an action <guilabel>Compile selection with
    CoffeeScript</guilabel> which can be assigned to a keyboard shortcut or
    a toolbar button. It is intended to allow a preview of the compiler output
    (and not as a build tool).
  </para>
  <para>
    The action compiles text from selection or the buffer (if nothing is
    selected) and opens the generated JavaScript in a new buffer. If the
    compilation fails errors are displayed in the ErrorList.
  </para>
</chapter>

<chapter id="problems"><title>Known problems and limitations</title>
  <para>Aside from above restrictions these problems (still) exist:
    <itemizedlist>
      <listitem>
        <para>
          Parsing is quite slow as it happens in Rhino. It is therefore not
          advisable to let SideKick parse on keystrokes.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>extents</code> of class definitions are not supported / shown.
        </para>
      </listitem>
    </itemizedlist>
  </para>
</chapter>

<chapter id="license"><title>License and Acknowledgments</title>
  <para>
    This software relies upon and incorporates large parts of CoffeeScript by
    Jeremy Ashkenas and others.
    Both are released under a <ulink url="http://opensource.org/licenses/MIT">
    MIT License.</ulink>
  </para>
</chapter>
</book>