From 7272b59458c02286e1d246ffa09de7386f0d942e Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Fri, 9 Jun 2017 21:19:10 +0100 Subject: Rework monkey docs into markdown --- docs/using-monkey.md | 306 +++++++++++++++++++++++++++++---------------------- 1 file changed, 175 insertions(+), 131 deletions(-) (limited to 'docs') 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 -- cgit v1.2.3