Permalink
Browse files

Some documenting of the UI and the API

More need to be done
  • Loading branch information...
1 parent d1e9fd5 commit 20be989fb2f3e837f09917e0dd8b53fd070216cd @cognominal committed Jun 24, 2012
Showing with 58 additions and 13 deletions.
  1. +58 −13 README.md
View
@@ -15,8 +15,11 @@ Coffeescript is used to convert `.coffee` files in `.js` ones.
# Next steps yet to be done
+* Display the rule used to reduce the current text (still need css)
* Bug jnthn/pmichaud to get parse tree dumping in Perl 6
-* Display the rule used to reduce the current text
+* Install zbrew on MBP and open a NTA port
+* Setup a github page.
+* Parse path bar need to be scrollable
* Serve the docco correspondance file with the parse tree
* Support many highlighted view ports (use class instead if id to identify relevant HTML elements
* Use express to serve the files (SFW will use express anyway)
@@ -33,22 +36,62 @@ Coffeescript is used to convert `.coffee` files in `.js` ones.
Note: to install SFW, I created a gist https://gist.github.com/2887964
+# User interface
-# Highlighting
+We call `lite` the code viewport. Lite stands for literate editor.
+Lite has two modes, the folded mode and the full mode. So we say
+a "folded lite" or a "full lite" to denote such a viewport depending
+on its mode. In folded lite, only the code pane is visile.
+So far, only the full mode is implemented.
+
+In full lite, from top to bottom, the view port is constituted of 3 panes.
+The parse path pane (P3), the rule pane and the code pane.
+At any given time, some text chunk in the code panel is current. When the
+code was parsed, according to the grammar for that code, some sequence of rules was used to reduce that current text chunk. The last rule of that sequence is the leaf rule.
+
+When moving the mouse over the code panel, or clicking in it, the currrent
+text chunk changes so the parse path and the rule panes are updated
+accordingly.
+
+
+# API
+
+The loading of a lite is done thru an ajax call that brings a json object
+constitued of thre subobjects. We call it a lite object.
+The `parseTree` subobject is the parse tree,
+the `rules` subobject is the grammar broken in rules, the `docco` subobject is
+the partial mapping of rule names to docco css names for highlighting.
+
+Note that the rules subobject may eventually be a lite object as well so
+that the rule pane will be a folded lite viewport with a partial view of
+a grammar; The view being the current rule. Clicking on that pane will
+bring the grammar as code in the enclosing viewport. Clicking again will bring
+the grammar of the grammar. An history mechanism
+should be implemented so that we can bring back the original code.
+
+Note that, for highlighting purpose, the relevant rule may be a parent of the
+leaf rule. Say, that the code panel contains json code and the current text
+chunk has been reduced by the `str` rule. The static highlighting will be associated with the string `rule`, not `str`.
+
+
+ `token string { \" ~ \" ( <str> | \\ <str_escape> )* }`
+ `token str { <-["\\\t\n]>+ }`
+
+
+## Highlighting
We will support two kinds of highlighting. The traditional one is
called SH (Static Hilighting). With SH you can readily identify
token by some CSS attribute, usually a color. DH (Dynamic Hilighting)
is proper to brews and show how a file is parsed. DH comes in addition to SH and changes with user interaction, so its name.
-## Highlighting internals
+### Highlighting internals
HC is short for the highlighted code in a given viewport.
HV denote a viewport that show HC.
A file is parsed and a json tree is generated that represents the corresponding
-parse tree. Depending on options, one can get either a full parse tree or just a
-sequence of tokens. The full parse tree is necessary for dynamic highlighting
+parse tree. Depending on options, one can get either a full parse tree or just a sequence of tokens. The full parse tree is necessary for dynamic highlighting
but a full file displayed this way would result on gigantic web pages.
@@ -58,8 +101,8 @@ text parsed by that rule gets the associated class attribute
So with the following docco object
- `docco =
- string: 's'`
+ `docco =`
+ ` string: 's'`
An element generated for a reduction caused by the rule `string` will look like
@@ -71,11 +114,13 @@ DH will be very costly in term of browser ressources. So at a given time
only part of the code will be displayed as such and the rest will
be in DH. But we want to be able to instantly convert in SH.
-HTML5 allows to store anything in an html element attribute which names starts by "data". We will divide the HC in chunks. Each chunks will store the corresponding
-json deep parse in its data attribute. When mousing out a DH chunks, it will be
-converted back in SH. WHen mousing in a SH chunk it will be converted in DH.
+HTML5 allows to store anything in an html element attribute which names starts
+by "data". We will divide the HC in chunks. Each chunks will store the
+corresponding json deep parse in its data attribute. When mousing out a DH
+chunks, it will be converted back in SH. WHen mousing in a SH chunk it will be
+converted in DH.
-This can be done in the client. The server will just say what sub parse trees should be chunks.
+This can be done in the client. The server will just say what sub parse trees should be chunks.
# Multiple goals
@@ -93,11 +138,11 @@ Many of them must be downloaded via "install package"
* Git : to work with the eponymous version control system
* SublimeServer : We need to serve the files with a web server (versus acessing them thru the file system) so as to serve some of them using ajax
-## Stuff to present
+### Stuff to present
How SublimeServer serves all the folder of the current projet.
linters that run in background.
-## License
+# License
Dual licensed under the MIT or GPL Version 2 licenses.

0 comments on commit 20be989

Please sign in to comment.