summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/using-monkey.md306
1 files changed, 175 insertions, 131 deletions
diff --git a/docs/using-monkey.md b/docs/using-monkey.md
index 53f912e4d..b1bd643bf 100644
--- a/docs/using-monkey.md
+++ b/docs/using-monkey.md
@@ -1,111 +1,106 @@
---------------------------------------------------------------------------------
- Usage Instructions for Monkey NetSurf 13 March 2011
---------------------------------------------------------------------------------
+Usage Instructions for Monkey NetSurf
+=====================================
- This document provides usage instructions for the Monkey version of
- NetSurf.
+This document provides usage instructions for the Monkey version of NetSurf.
- Monkey NetSurf has been tested on Ubuntu.
+Monkey NetSurf has been tested on Ubuntu and Debian.
Overview
-========
+--------
- What it is
- ----------
+### What it is
- The NetSurf Monkey front end is a developer debug tool used to
- test how the core interacts with the user interface. It allows
- the developers to profile NetSurf and to interact with the core
- directly as though the developer were a front end.
+The NetSurf Monkey front end is a developer debug tool used to test how the
+core interacts with the user interface. It allows the developers to profile
+NetSurf and to interact with the core directly as though the developer were a
+front end.
- What it is not
- --------------
+### What it is not
- Monkey is not a tool for building web-crawling robots or indeed
- anything other than a debug tool for the NetSurf developers.
+Monkey is not a tool for building web-crawling robots or indeed anything other
+than a debug tool for the NetSurf developers.
- How to interact with nsmonkey
- -----------------------------
+### How to interact with `nsmonkey`
- In brief, monkey will produce tagged output on stdout and expect
- commands on stdin. Windows are numbered and for the most part
- tokens are space separated. In some cases (e.g. title or status)
- the final element on the output line is a string which might have
- spaces embedded within it. As such, output from nsmonkey should be
- parsed a token at a time, so that when such a string is encountered,
- the parser can stop splitting and return the rest.
+In brief, `nsmonkey` will produce tagged output on stdout and expect
+commands on stdin. Windows are numbered and for the most part
+tokens are space separated. In some cases (e.g. title or status)
+the final element on the output line is a string which might have
+spaces embedded within it. As such, output from `nsmonkey` should be
+parsed a token at a time, so that when such a string is encountered,
+the parser can stop splitting and return the rest.
- Commands to Monkey are namespaced. For example commands related to
- browser windows are prefixed by WINDOW.
+Commands to `nsmonkey` are namespaced. For example commands related to
+browser windows are prefixed by `WINDOW`.
- Top level tags for nsmonkey
- ---------------------------
+### Top level tags for `nsmonkey`
- QUIT
+* `QUIT`
- WINDOW
+* `WINDOW`
- Top level response tags for nsmonkey
- ------------------------------------
+### Top level response tags for nsmonkey
- GENERIC
+* `GENERIC`: Generic messages such as poll loops etc.
- WARN, ERROR, DIE
+* `WARN`, `ERROR`, `DIE`: Error messages of varying importance
- WINDOW
+* `WINDOW`: Anything about browser windows in general
- DOWNLOAD_WINDOW
+* `DOWNLOAD_WINDOW`: Anything about the download window.
- SSLCERT
+* `SSLCERT`: Anything about SSL certificates
- 401LOGIN
+* `401LOGIN`: Anything about HTTP Basic Authentication logins
- PLOT
+* `PLOT`: Plot calls which come from the core.
- In the below, %something% indicates a substitution made by Monkey.
+In the below, _%something%_ indicates a substitution made by Monkey.
- %url% will be a URL
- %id% will be an opaque ID
- %n% will be a number
- %bool% will be TRUE or FALSE
- %str% is a string and will only ever be at the end of an output line.
+* _%url%_ will be a URL
+* _%id%_ will be an opaque ID
+* _%n%_ will be a number
+* _%bool%_ will be TRUE or FALSE
+* _%str%_ is a string and will only ever be at the end of an output line.
- Warnings, errors etc
- --------------------
+### Warnings, errors etc
- Warnings (tagged WARN) come from the NetSurf core.
- Errors (tagged ERROR) tend to come from Monkey's parsers
- Death (tagged DIE) comes from the core and kills Monkey dead.
+* Warnings (tagged `WARN`) come from the NetSurf core.
+* Errors (tagged `ERROR`) tend to come from Monkey's parsers
+* Death (tagged `DIE`) comes from the core and kills Monkey dead.
Commands
-========
+--------
- Generic commands
- ----------------
+### Generic commands
+
+* `QUIT`
- QUIT
Cause monkey to quit cleanly.
This will cleanly destroy open windows etc.
- Window commands
- ---------------
+### Window commands
+
+* `WINDOW NEW` [_%url%_]
- WINDOW NEW [%url%]
Create a new browser window, optionally giving the core
a URL to immediately navigate to.
- Minimally you will receive a WINDOW NEW WIN %id% response.
+ Minimally you will receive a `WINDOW NEW WIN` _%id%_ response.
+
+* `WINDOW DESTROY` _%id%_
- WINDOW DESTROY %id%
Destroy the given browser window.
- Minimally you will recieve a WINDOW DESTROY WIN %id% response.
+ Minimally you will receive a `WINDOW DESTROY WIN` _%id%_ response.
+
+* `WINDOW GO` _%id%_ _%url%_ [_%url%_]
- WINDOW GO %id% %url% [%url%]
Cause the given browser window to visit the given URL.
Optionally you can give a referrer URL to also use (simulating
a click in the browser on a link).
Minimally you can expect throbber, url etc responses.
- WINDOW REDRAW %id% [%num% %num% %num% %num%]
+* `WINDOW REDRAW` _%id%_ [_%num% %num% %num% %num%_]
+
Cause a browser window to redraw. Optionally you can give a
set of coordinates to simulate a partial expose of the window.
Said coordinates are in traditional X0 Y0 X1 Y1 order.
@@ -113,209 +108,258 @@ Commands
should take into account the scroll offsets when issuing this
command.
Minimally you can expect redraw start/stop messages and you
- can likely expect some number of PLOT results.
+ can likely expect some number of `PLOT` results.
+
+* `WINDOW RELOAD` _%id%_
- WINDOW RELOAD %id%
Cause a browser window to reload its current content.
Expect responses similar to a GO command.
Responses
-=========
+---------
- Generic messages
- ----------------
+### Generic messages
+
+* `GENERIC STARTED`
- GENERIC STARTED
Monkey has started and is ready for commands
- GENERIC CLOSING_DOWN
+* `GENERIC CLOSING_DOWN`
+
Monkey has been told to shut down and is doing so
- GENERIC FINISHED
+* `GENERIC FINISHED`
+
Monkey has finished and will now exit
- GENERIC LAUNCH URL %url%
+* `GENERIC LAUNCH URL` _%url%_
+
The core asked monkey to launch the given URL
- GENERIC THUMBNAIL URL %url%
+* `GENERIC THUMBNAIL URL` _%url%_
+
The core asked monkey to thumbnail a content without
a window.
- GENERIC POLL BLOCKING
- GENERIC POLL TIMED nnnn
+* `GENERIC POLL BLOCKING`
+* `GENERIC POLL TIMED` _%n%_
+
Monkey reached a point where it could sleep waiting for
commands or scheduled timeouts. No fetches nor redraws
were pending. If there are no timeouts or other pending
jobs then this will be a BLOCKING poll, otherwise the number
given is in milliseconds.
- Window messages
- ---------------
+### Window messages
- WINDOW NEW WIN %id% FOR %id% CLONE %id% NEWTAB %bool%
- The core asked Monkey to open a new window. The IDs for 'FOR' and
- 'CLONE' are core window IDs, the WIN id is a Monkey window ID.
+* `WINDOW NEW WIN` _%id%_ `FOR` _%id%_ `CLONE` _%id%_ `NEWTAB` _%bool%_
+
+ The core asked Monkey to open a new window. The IDs for `FOR` and
+ `CLONE` are core window IDs, the `WIN` id is a Monkey window ID.
+
+* `WINDOW SIZE WIN` _%id%_ `WIDTH` _%n%_ `HEIGHT` _%n%_
- WINDOW SIZE WIN %id% WIDTH %n% HEIGHT %n%
The window specified has been set to the shown width and height.
- WINDOW DESTROY WIN %id%
+* `WINDOW DESTROY WIN` _%id%_
+
The core has instructed Monkey to destroy the named window.
- WINDOW TITLE WIN %id% STR %str%
+* `WINDOW TITLE WIN` _%id%_ `STR` _%str%_
+
The core supplied a titlebar title for the given window.
- WINDOW REDRAW WIN %id%
+* `WINDOW REDRAW WIN` _%id%_
+
The core asked that Monkey redraw the given window.
- WINDOW GET_DIMENSIONS WIN %id% WIDTH %n% HEIGHT %n%
+* `WINDOW GET_DIMENSIONS WIN` _%id%_ `WIDTH` _%n%_ `HEIGHT` _%n%_
+
The core asked Monkey what the dimensions of the window are.
Monkey has to respond immediately and returned the supplied width
and height values to the core.
- WINDOW NEW_CONTENT WIN %id%
+* `WINDOW NEW_CONTENT WIN` _%id%_
+
The core has informed Monkey that the named window has a new
content object.
- WINDOW NEW_ICON WIN %id%
- The core has informed Monkey that the named window hsa a new
+* `WINDOW NEW_ICON WIN` _%id%_
+
+ The core has informed Monkey that the named window has a new
icon (favicon) available.
- WINDOW START_THROBBER WIN %id%
+* `WINDOW START_THROBBER WIN` _%id%_
+
The core asked Monkey to start the throbber for the named
window. This indicates to the user that the window is busy.
- WINDOW STOP_THROBBER WIN %id%
+* `WINDOW STOP_THROBBER WIN` _%id%_
+
The core asked Monkey to stop the throbber for the named
window. This indicates to the user that the window is finished.
- WINDOW SET_SCROLL WIN %id% X %n% Y %n%
+* `WINDOW SET_SCROLL WIN` _%id%_ `X` _%n%_ `Y` _%n%_
+
The core asked Monkey to set the named window's scroll offsets
to the given X and Y position.
- WINDOW UPDATE_BOX WIN %id% X %n% Y %n% WIDTH %n% HEIGHT %n%
+* `WINDOW UPDATE_BOX WIN` _%id%_ `X` _%n%_ `Y` _%n%_ `WIDTH` _%n%_ `HEIGHT` _%n%_
+
The core asked Monkey to redraw the given portion of the content
display. Note these coordinates refer to the content, not the
viewport which Monkey is simulating.
- WINDOW UPDATE_EXTENT WIN %id% WIDTH %n% HEIGHT %n%
+* `WINDOW UPDATE_EXTENT WIN` _%id%_ `WIDTH` _%n%_ `HEIGHT` _%n%_
+
The core has told us that the content in the given window has a
total width and height as shown. This allows us (along with the
window's width and height) to know the scroll limits.
- WINDOW SET_STATUS WIN %id% STR %str%
+* `WINDOW SET_STATUS WIN` _%id%_ `STR` _%str%_
+
The core has told us that the given window needs its status bar
updating with the given message.
- WINDOW SET_POINTER WIN %id% POINTER %id%
+* `WINDOW SET_POINTER WIN` _%id%_ `POINTER` _%id%_
+
The core has told us to update the mouse pointer for the given
window to the given pointer ID.
- WINDOW SET_SCALE WIN %id% SCALE %n%
+* `WINDOW SET_SCALE WIN` _%id%_ `SCALE` _%n%_
+
The core has asked us to scale the given window by the given scale
factor.
- WINDOW SET_URL WIN %id% URL %url%
+* `WINDOW SET_URL WIN` _%id%_ `URL` _%url%_
+
The core has informed us that the given window's URL bar needs
updating to the given url.
- WINDOW GET_SCROLL WIN %id% X %n% Y %n%
+* `WINDOW GET_SCROLL WIN` _%id%_ `X` _%n%_ `Y` _%n%_
+
The core asked Monkey for the scroll offsets. Monkey returned the
numbers shown for the window named.
- WINDOW SCROLL_START WIN %id%
+* `WINDOW SCROLL_START WIN` _%id%_
+
The core asked Monkey to scroll the named window to the top/left.
- WINDOW POSITION_FRAME WIN %id% X0 %n% Y0 %n% X1 %n% Y1 %n%
+* `WINDOW POSITION_FRAME WIN` _%id%_ `X0` _%n%_ `Y0` _%n%_ `X1` _%n%_ `Y1` _%n%_
+
The core asked Monkey to position the named window as a frame at
the given coordinates of its parent.
- WINDOW SCROLL_VISIBLE WIN %id% X0 %n% Y0 %n% X1 %n% Y1 %n%
+* `WINDOW SCROLL_VISIBLE WIN` _%id%_ `X0` _%n%_ `Y0` _%n%_ `X1` _%n%_ `Y1` _%n%_
+
The core asked Monkey to scroll the named window until the
indicated box is visible.
- WINDOW PLACE_CARET WIN %id% X %n% Y %n% HEIGHT %n%
+* `WINDOW PLACE_CARET WIN` _%id%_ `X` _%n%_ `Y` _%n%_ `HEIGHT` _%n%_
+
The core asked Monkey to render a caret in the named window at the
indicated position with the indicated height.
- WINDOW REMOVE_CARET WIN %id%
+* `WINDOW REMOVE_CARET WIN` _%id%_
+
The core asked Monkey to remove any caret in the named window.
- WINDOW SCROLL_START WIN %id% X0 %n% Y0 %n% X1 %n% Y1 %n%
+* `WINDOW SCROLL_START WIN` _%id%_ `X0` _%n%_ `Y0` _%n%_ `X1` _%n%_ `Y1` _%n%_
+
The core asked Monkey to scroll the named window to the start of
the given box.
- WINDOW SELECT_MENU WIN %id%
+* `WINDOW SELECT_MENU WIN` _%id%_
+
The core asked Monkey to produce a selection menu for the named
window.
- WINDOW SAVE_LINK WIN %id% URL %url% TITLE %str%
+* `WINDOW SAVE_LINK WIN` _%id%_ `URL` _%url%_ `TITLE` _%str%_
+
The core asked Monkey to save a link from the given window with
the given URL and anchor title.
- WINDOW THUMBNAIL WIN %id% URL %url%
+* `WINDOW THUMBNAIL WIN` _%id%_ `URL` _%url%_
+
The core asked Monkey to render a thumbnail for the given window
which is currently at the given URL.
- WINDOW REDRAW WIN %id% START
- WINDOW REDRAW WIN %id% STOP
- The core wraps redraws in these messages. Thus PLOT responses can
+* `WINDOW REDRAW WIN` _%id%_ `START`
+
+ and
+
+ `WINDOW REDRAW WIN` _%id%_ `STOP`
+
+ The core wraps redraws in these messages. Thus `PLOT` responses can
be allocated to the appropriate window.
- Download window messages
- ------------------------
+### Download window messages
+
+* `DOWNLOAD_WINDOW CREATE DWIN` _%id%_ `WIN` _%id%_
- DOWNLOAD_WINDOW CREATE DWIN %id% WIN %id%
The core asked Monkey to create a download window owned by the
given browser window.
- DOWNLOAD_WINDOW DATA DWIN %id% SIZE %n% DATA %str%
+* `DOWNLOAD_WINDOW DATA DWIN` _%id%_ `SIZE` _%n%_ `DATA` _%str%_
+
The core asked Monkey to update the named download window with
the given byte size and data string.
- DOWNLOAD_WINDOW ERROR DWIN %id% ERROR %str%
+* `DOWNLOAD_WINDOW ERROR DWIN` _%id%_ `ERROR` _%str%_
+
The core asked Monkey to update the named download window with
the given error message.
- DOWNLOAD_WINDOW DONE DWIN %id%
+* `DOWNLOAD_WINDOW DONE DWIN` _%id%_
+
The core asked Monkey to destroy the named download window.
- SSL Certificate messages
- ------------------------
+### SSL Certificate messages
+
+* `SSLCERT VERIFY CERT` _%id%_ `URL` _%url%_
- SSLCERT VERIFY CERT %id% URL %url%
The core asked Monkey to say whether or not a given SSL
certificate is OK.
- 401 Login messages
- ------------------
+> TODO: Implement the rest of the SSL certificat verification behaviour
+
+### 401 Login messages
+
+* `401LOGIN OPEN M4` _%id%_ `URL` _%url%_ `REALM` _%str%_
- 401LOGIN OPEN M4 %id% URL %url% REALM %str%
The core asked Monkey to ask for identification for the named
realm at the given URL.
- Plotter messages
- ----------------
+> TODO: Implement support to control the 401LOGIN process
- Note, Monkey won't clip coordinates, but sometimes the core does.
+### Plotter messages
+
+> **Note, Monkey won't clip coordinates, but sometimes the core does.**
+
+* `PLOT CLIP X0` _%n%_ `Y0` _%n%_ `X1` _%n%_ `Y1` _%n%_
- PLOT CLIP X0 %n% Y0 %n% X1 %n% Y1 %n%
The core asked Monkey to clip plotting to the given clipping
rectangle (X0,Y0) (X1,Y1)
- PLOT TEXT X %n% Y %n% STR %str%
+* `PLOT TEXT X` _%n%_ `Y` _%n%_ `STR` _%str%_
+
The core asked Monkey to plot the given string at the
given coordinates.
- PLOT LINE X0 %n% Y0 %n% X1 %n% Y1 %n%
+* `PLOT LINE X0` _%n%_ `Y0` _%n%_ `X1` _%n%_ `Y1` _%n%_
+
The core asked Monkey to plot a line with the given start
and end coordinates.
- PLOT RECT X0 %n% Y0 %n% X1 %n% Y1 %n%
+* `PLOT RECT X0` _%n%_ `Y0` _%n%_ `X1` _%n%_ `Y1` _%n%_
+
The core asked Monkey to plot a rectangle with the given
coordinates as the corners.
- PLOT BITMAP X %n% Y %n% WIDTH %n% HEIGHT %n%
+* `PLOT BITMAP X` _%n%_ `Y` _%n%_ `WIDTH` _%n%_ `HEIGHT` _%n%_
+
The core asked Monkey to plot a bitmap at the given
coordinates, scaled to the given width/height.
+
+> TODO: Check if other things are implemented and add them to the docs