/usr/share/pyshared/guppy/doc/gsl.html is in python-guppy 0.1.9-2ubuntu4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<html lang=en>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
<title></title></head>
<body>
<div>
<h1>
Guppy Specification Language
</h1>
<ul>
<li><a href='docexample.html'> Generated document example</a></li>
<li><a href='#kinds'> Kinds</a></li>
<li><a href='#example'> Example</a></li>
<li><a href='#emacsmode'> Emacs editing mode</a></li></ul>
<p> GSL is an evolving specification language, which is a part of the<a href='index.html'> Guppy-PE</a>
programming environment. I started experimenting with this
language because I felt the need to have a way to specify
documentation and tests from the same source. GSL can describe aspects
of a system, especially its API, in a way that can be automatically
converted to tests as well as to documents. The documents generated
have a formal structure for describing the formal aspects of the
specification, complemented with descriptive text from the same source
documents. A language that is similar in intent to GSL, is the
<a href='http://adl.opengroup.org/'> http://adl.opengroup.org</a>
Assertion Definition Language.
</p>
<p>
Generating tests automatically is a quite hard problem
generally. The programmer only may know best what should be tested.
At the very least, however, GSL can check that some aspects of the
documentation are in fact correct. If an object is specified to have
an attribute, it can be tested. If the kind (type) of the attribute is
also specified, it can also be tested, as far as the kind of the
attribute is specifed, and as far as it can be done within physical
limits when there are circularities and combinatorial explosions.
</p>
<p>
It is possible to use GSL to write documents that have no formal
connection to program semantics. It supplies a syntax that can proivde
a 1-1 correspondence with HTML (and XML), but is often easier to read
and write (IMHO). The syntax is a simple syntax based on dotted
indentation. There is a well defined 1-1 correspondence with a tree
structure.
</p>
<p>
This release of Guppy is not primarily concerned with GSL which
is still in a very prototypical state, it awaits probably the first
major refactoring. However, since the documentation of Heapy is
generated by GSL, something deserves to be said about the kind of
documents it has generated.
</p>
<p>
I think what wants to be explained at this point is the following.
</p><a name='kinds'>
<h3>
Kinds
</h3></a>
<p>
I am generally using the word 'kind' to stand for something that is
not a type or a class but is specified in some other way. This is
because I don't want to say type and class when I am not exactly
referring to a type or class, since it would be confusing if some
people think it means a Python type or class, someone else think it
means something else. The word 'kind' means just a kind, it is not
defined what a kind is, except for what you might think it means in
ordinary language.
</p>
<p>
Maybe a 'kind' is quite the same as what is otherwise often
called an 'interface'. Well, I am using the word 'kind' in that case
anyway since it is shorter and easier to read and write.
</p>
<p>
In GSL, a 'kind' starts as just a name for something without
any properties at all. You can however add properties to a kind
by specifying something about it. You may for example say
</p>
<pre>
.and: mykind
..attr:: attributename</pre>
<p>
This means you have added an aspect to mykind. It now means that it is
a (Python) object having an attribute named attributename. A test can
be generated from this specification. It will check an object claimed
to be of kind mykind, to make sure it really has an attribute named
attributename.
</p>
<p>
You can also add properties saying that a kind of objects or
attributes is callable, what kind of parameters it can take, and what
kind of return value it will deliver. The parameters can be specified
to be optional, named, or repeated in varous ways.
</p><a name='example'>
<h3>
Example
</h3></a>
<p> This<a href='gslexample.html'> GSL example</a> contains the source code and the generated test code for the <a href='docexample.html'> generated document</a>
example. The generated document intends to illustrate different kinds
of parameter specifications.
</p><a name='emacsmode'>
<h3> Emacs mode</h3></a>
<p>
There is an Emacs mode that supports editing of GSL files. It is
based on the Python mode. It indents with dots instead of
spaces. The mode file "gsl-mode-0.1.el" is in the distribution top
level directory and is not automatically installed.
</p>
<p> The following is taken from its builtin help texts.</p>
<pre>
GSL mode:
Major mode for editing GSL files.
To submit a problem report, enter `C-c C-b' from a
`gsl-mode' buffer. Do `C-c ?' for detailed documentation.
This mode knows about GSL dotted indentation.
Paragraphs are separated by blank lines only.
COMMANDS
key binding
--- -------
C-c Prefix Command
C-c C-v gsl-mode-version
C-c C-b gsl-submit-bug-report
C-c ? gsl-describe-mode
C-c C-r gsl-shift-region-right
C-c > gsl-shift-region-right
C-c C-l gsl-shift-region-left
C-c < gsl-shift-region-left
KINDS OF LINES
Each physical line in the file is either a `markup line'
(the line starts with a dot character '.') or a `text line'
(the line starts with some other character). Text lines starting
with a dot may be entered by quoting by a backslash ('\')).
INDENTATION
Unlike most programming languages, GSL uses indentation, and only
indentation, to specify block structure. Unlike other programming
languages the indentation is not based on blanks but on another
special character; currently this is fixed to be the '.' character.
The indentation that can be supplied automatically by GSL-mode is
just a guess: only you know the block structure you intend, so only
you can supply correct indentation.
Primarily for entering new code:
TAB indent line appropriately
LFD insert newline, then indent
The TAB and LFD keys will indent the current line to reproduce
the same indentation as the closest preceding markup line.
Primarily for reindenting existing code:
C-c C-l shift region left
C-c C-r shift region right
The indentation of the markup lines in the region is changed by +/- 1
or the argument given. Text lines in the region will not be changed.
OTHER COMMANDS
Use C-c C-v to see the current version of gsl-mode.
Use C-c C-b to submit a bug report or enhancement proposal.
This text is displayed via the C-c ? command.
HOOKS
Entering GSL mode calls with no arguments the value of the variable
`gsl-mode-hook', if that value exists and is not nil; see the `Hooks'
section of the Elisp manual for details.</pre>
<hr>Generated by <a href="http://guppy-pe.sourceforge.net/gsl.html">GSL-HTML 0.1.5</a> on Tue Jun 23 16:15:55 2009</div></body></html>
|