diff options
Diffstat (limited to 'doc')
36 files changed, 939 insertions, 510 deletions
diff --git a/doc/CCCwork.txt b/doc/CCCwork.txt new file mode 100644 index 00000000..1ea5d20e --- /dev/null +++ b/doc/CCCwork.txt @@ -0,0 +1,153 @@ +Last review: August 04, 2009 --jcid + + +---------------------------- +Internal working for the CCC +---------------------------- + + +HTTP protocol +------------- + + + Query: | + . + 1B --> 1B 1B --> 1B --> | -------------. + .----. .----. .----. . | +I |Capi| |http| | IO | | | + '----' '----' '----' . | + 1F <-- 1F 1F <-- 1F | V + . + | [Server] + Answer: . + + 2B --> 2B 2B --> 2B | | + .----. .----. .----. . | +II |Capi| |Dpi | | IO | | | + '----' '----' '----' . | + 2F <-- 2F 2F <-- 2F <-- | <------------' + . + | + +* a_Capi_open_url() builds both the Answer and Query chains at +once (Answer first then Query), to ensure a uniform structure +that avoids complexity (e.g. race conditions). + +* Http_get() sets a callback for the DNS hostname resolve. +Normally it comes later, but may also by issued immediately if +the hostname is cached. + +* The socket FD is passed by means of OpSend by the http module +once the remote IP is known and the socket is connected. + + + +Function calls for HTTP CCC +--------------------------- + + a_Capi_open_url + if (reload) + Capi OpStart 2B (answer) [Capi] --> [dpi] --> [IO] + Capi OpStart 1B (query) [Capi] --> [http] --> [IO] + Http_get + a_Cache_open_url + if URL_E2EReload -> prepare reload + if cached + client enqueue + delayed process queue + else + Cache_entry_add + client enqueue + + -//-> + a_Http_dns_cb + Http_connect_socket + OpSend FD, BCK + OpSend FD, FWD + Http_send_query + a_Http_make_query_str + OpSend, BCK + IO_submit + a_IOwatch_add_fd (DIO_WRITE, ...) + + + Note about 'web' structures. They're created using a_Web_new(). +The web.c module keeps a list of valid webs, so anytime you're +unsure of a weak reference to 'web', it can be checked with +a_Web_valid(web). + + + +------------ +Dpi protocol +------------ + + + Query: | + . + 1B --> 1B 1B --> 1B --> | -------------. + .----. .----. .----. . | +I |Capi| |Dpi | | IO | | | + '----' '----' '----' . | + 1F <-- 1F 1F <-- 1F | V + . + | [Server] + . + Answer (same as HTTP): | | + . | + 2B --> 2B 2B --> 2B | | + .----. .----. .----. . | +II |Capi| |Dpi | | IO | | | + '----' '----' '----' . | + 2F <-- 2F 2F <-- 2F <-- | <------------' + . + | + + +CCC Construction: + + a_Capi_open_url() calls a_Capi_dpi_send_cmd() when the URL +belongs to a dpi and it is not cached. + + a_Capi_dpi_send_cmd() builds both the Answer and Query chains +at once (Answer first then Query), in the same way as HTTP does. +Note that the answer chain is the same for both, and the query +chain only differs in the module in the middle ([http] or [dpi]). + + +Function calls for DPI CCC +-------------------------- + + a_Capi_open_url + a_Capi_dpi_send_cmd + Capi OpStart 2B (answer) [Capi] --> [dpi] --> [IO] + Capi OpStart 1B (query) [Capi] --> [http] --> [IO] + a_Cache_open_url + [...] + + +Normal termination: + + When the dpi server is done, it closes the FD, and OpEnd flows +from IO to Capi (answer branch). When in Capi, capi propagates +OpEnd to the query branch. + +Abnormal termination: + + The transfer may be aborted by a_Capi_conn_abort_by_url(). The +OpAbort is not yet standardized and has an ad-hoc implementation. +One idea is to have OpAbort always propagate BCK and then FWD and +to jump into the other chain when it gets to [Capi]. + + +Debugging CCC +------------- + + A simple way to "look" inside it, is to "#define VERBOSE 1" in +chain.c, and then to follow its work with a printed copy of the +diagrams in this document. + + Each new data request generates a CCC, so if you want to debug, +it's good to refine the testcase to the minimum possible number +of connections. + diff --git a/doc/Cache.txt b/doc/Cache.txt index ac1ecf87..4e885df2 100644 --- a/doc/Cache.txt +++ b/doc/Cache.txt @@ -1,5 +1,5 @@ June 2000, --Jcid - Last update: Oct 2004 + Last update: Jul 09 ------- CACHE @@ -12,28 +12,21 @@ rendering and networking. calls the cache or the dpi routines depending on the type of request. - Every URL must be requested using a_Capi_open_url, no matter -if it is a http, file, dpi or whatever type of request. The capi -asks the dpi module for dpi URLs and the Cache for everything -else. + Every URL must be requested using a_Capi_open_url, which +sends the request to the cache if the data is cached, to dillo's +http module for http: URLs, and through dillo's DPI system for +other URLs. Here we'll document non dpi requests. - The cache, at its turn, sends the requested-data from memory -(if cached), or opens a new network connection (if not cached). - - This means that no mattering whether the answer comes from -memory or the net, the client requests it through the capi -wrapper, in a single uniform way. - ---------------- CACHE PHILOSOPHY ---------------- - Dillo's cache is very simple, every single resource that's -retrieved (URL) is kept in memory. NOTHING is saved. This is -mainly for three reasons: + Dillo's cache is very simple; every single resource that's +retrieved (URL) is kept in memory. NOTHING is saved to disk. +This is mainly for three reasons: - Dillo encourages personal privacy and it assures there'll be no recorded tracks of the sites you visited. @@ -42,7 +35,7 @@ no recorded tracks of the sites you visited. serve as caches. - If you still want to have cached stuff, you can install an -external cache server (as WWWOFFLE), and benefit from it. +external cache server (such as WWWOFFLE), and benefit from it. --------------- @@ -51,15 +44,14 @@ external cache server (as WWWOFFLE), and benefit from it. Currently, dillo's cache code is spread in different sources: mainly in cache.[ch], dicache.[ch] and it uses some other -functions from mime.c, Url.c and web.c. +functions from mime.c and web.cc. - Cache.c is the principal source, and it also is the main + Cache.c is the principal source, and it also is the one responsible for processing cache-clients (held in a queue). -Dicache.c is the "decompressed image cache" and it holds the -original data and its corresponding decompressed RGB -representation (more on this subject in Images.txt). +Dicache.c is the interface to the decompressed RGB representations +of currently-displayed images held in DW's imgbuf. - Url.c, mime.c and web.c are used for secondary tasks; as + mime.c and web.cc are used for secondary tasks such as assigning the right "viewer" or "decoder" for a given URL. @@ -67,7 +59,7 @@ assigning the right "viewer" or "decoder" for a given URL. A bit of history ---------------- - Some time ago, the cache functions, URL retrieving and + Some time ago, the cache functions, URL retrieval and external protocols were a whole mess of mixed code, and it was getting REALLY hard to fix, improve or extend the functionality. The main idea of this "layering" is to make code-portions as @@ -76,32 +68,34 @@ improved or replaced without affecting the rest of the browser. An interesting part of the process is that, as resources are retrieved, the client (dillo in this case) doesn't know the -Content-Type of the resource at request-time. It only gets known -when the resource header is retrieved (think of http), and it -happens when the cache has the control so, the cache sets the -proper viewer for it! (unless the Callback function is specified -with the URL request). +Content-Type of the resource at request-time. It only becomes known +when the resource header is retrieved (think of http). This +happens when the cache has control, so the cache sets the +proper viewer for it (unless the Callback function was already +specified with the URL request). You'll find a good example in http.c. - Note: Files don't have a header, but the file handler inside -dillo tries to determine the Content-Type and sends it back in -HTTP form! + Note: All resources received by the cache have HTTP-style headers. + The file/data/ftp DPIs generate these headers when sending their + non-HTTP resources. Most importantly, a Content-Type header is + generated based on file extension or file contents. ------------- Cache clients ------------- - Cache clients MUST use a_Cache_open_url to request an URL. The + Cache clients MUST use a_Capi_open_url to request an URL. The client structure and the callback-function prototype are defined, in cache.h, as follows: struct _CacheClient { - gint Key; /* Primary Key for this client */ - const char *Url; /* Pointer to a cache entry Url */ - guchar *Buf; /* Pointer to cache-data */ - guint BufSize; /* Valid size of cache-data */ + int Key; /* Primary Key for this client */ + const DilloUrl *Url; /* Pointer to a cache entry Url */ + int Version; /* Dicache version of this Url (0 if not used) */ + void *Buf; /* Pointer to cache-data */ + uint_t BufSize; /* Valid size of cache-data */ CA_Callback_t Callback; /* Client function */ void *CbData; /* Client function data */ void *Web; /* Pointer to the Web structure of our client */ @@ -124,28 +118,15 @@ Key-functions descriptions -------------------------- ································································ -int a_Cache_open_url(const char *Url, CA_Callback_t Call, void *CbData) +int a_Cache_open_url(void *Web, CA_Callback_t Call, void *CbData) - if Url is not cached + if Web->url is not cached Create a cache-entry for that URL Send client to cache queue - Initiate a new connection else Feed our client with cached data ································································ -ChainFunction_t a_Url_get_ccc_funct(const char *Url) - - Scan the Url handlers for a handler that matches - If found - Return the CCC function for it - else - Return NULL - - * Ex: If Url is an http request, a_Http_ccc is the matching -handler. - -································································ ---------------------- Redirections mechanism @@ -177,9 +158,9 @@ Notes to document it in more detail later (source is commented). Currently I have a drawing to understand it; hope the ASCII translation serves the same as the original. - If you're planning to understand the cache process troughly, -write me a note, just to assign a higher priority on further -improving of this doc. + If you're planning to understand the cache process thoroughly, +write me a note and I will assign higher priority to further +improvement of this doc. Hope this helps! diff --git a/doc/Cookies.txt b/doc/Cookies.txt index c43cacc4..a8e82a83 100644 --- a/doc/Cookies.txt +++ b/doc/Cookies.txt @@ -1,21 +1,23 @@ Jan 2002, Jörgen Viksell - jorgen.viksell@telia.com, Jorge Arellano Cid -- -Last update: October 2008 +Last update: March 2010 ================== Cookies in Dillo ================== -Supported: old Netscape style, RFC 2109, RFC 2965. +Dillo's cookies implementation is guided by ongoing work by the HTTP State WG +( http://www.ietf.org/dyn/wg/charter/httpstate-charter ) to specify current +real-world cookies usage. Cookies are handled by a dpi (plugin) which shares them between your instances of Dillo. +Currently, cookie limits are: 20 per domain, and 1200 in total. + When the dpi exits, cookies that you have ACCEPTed are saved to ~/.dillo/cookies.txt, and ACCEPT_SESSION cookies are forgotten. -(Currently the only limit to the amount of cookies to save to disk is -a maximum of 20 per domain.) The dpi normally exits after a period of inactivity, but you can force it to exit with the command "dpidc stop". @@ -30,12 +32,14 @@ Out of the box, dillo rejects all cookies. If you want to accept certain cookies, you can specify rules for different domains in the file ~/.dillo/cookiesrc. The syntax looks like: +#host action DEFAULT DENY -slashdot.org ACCEPT +fltk.org ACCEPT .host.com ACCEPT_SESSION +Line 0: Comment line begins with '#'. Line 1: Deny all cookies from all domains not otherwise specified. -Line 2: Accept all cookies from slashdot.org, and save them to +Line 2: Accept all cookies from fltk.org, and save them to ~/.dillo/cookies.txt when the cookies dpi exits. Line 3: Accept all cookies from all subdomains of host.com, but do not save them when the dpi exits. diff --git a/doc/Dillo.txt b/doc/Dillo.txt index 47f89780..b9ef0513 100644 --- a/doc/Dillo.txt +++ b/doc/Dillo.txt @@ -24,30 +24,30 @@ developers. Dillo can be viewed as the sum of five main parts: 1.- Dillo Widget: A custom widget, FLTK2 based, that holds the -neccesary data structures and mechanisms for graphical rendering. +necessary data structures and mechanisms for graphical rendering. (Described in Dw*.txt, dw*.c files among the sources.) 2.- Dillo Cache: Integrated with a signal driven Input/Output engine that handles file descriptor activity, the cache acts as the main abstraction layer between rendering and networking. Every URL, whether cached or not, must be retrieved using -a_Cache_open_url (Described briefly in Cache.txt, source -contained in cache.c). - IO is described in IO.txt (recommended), source in IO/. +a_Capi_open_url (Described briefly in Cache.txt, source +contained in capi.c). + IO is described in IO.txt (recommended), source in src/IO/. 3.- The HTML parser: A streamed parser that joins the Dillo Widget and the Cache functionality to make browsing possible -(Described in HtmlParser.txt, source mainly inside html.c). +(Described in HtmlParser.txt, source mainly inside html.cc). 4.- Image processing code: The part that handles image -retrieving, decoding, caching and displaying. (Described in -Images.txt. Sources: image.c, dw_image.c, dicache.c, gif.c, +retrieval, decoding, caching and displaying. (Described in +Images.txt. Sources: image.c, dw/image.cc, dicache.c, gif.c, jpeg.c and png.c) 5.- The dpi framework: a gateway to interface the browser with external programs (Example: the bookmarks server plugin). Dpi spec: http://www.dillo.org/dpi1.html - + ------------------------- HOW IS THE PAGE RENDERED? @@ -55,34 +55,27 @@ Dpi spec: http://www.dillo.org/dpi1.html (A short description of the internal function calling process) - When the user requests a new URL, a_Interface_entry_open_url + When the user requests a new URL, a_UIcmd_open_url is queried to do the job; it calls a_Nav_push (The highest level URL dispatcher); a_Nav_push updates current browsing history and calls Nav_open_url. Nav_open_url closes all open connections by -calling a_Interface_stop and a_Interface_stop, and then calls -a_Capi_open_url wich calls a_Cache_open_url (or the dpi module if +calling a_Bw_stop_clients, and then calls +a_Capi_open_url which calls a_Cache_open_url (or the dpi module if this gateway is used). - If Cache_search hits (due to a cached url :), the client is + If Cache_entry_search hits (due to a cached url :), the client is fed with cached data, but if the URL isn't cached yet, a new CCC -(Concomitant Control Chain) is created and commited to fetch the -URL. Note that a_Cache_open_url will return the requested URL, -whether cached or not. +(Concomitant Control Chain) is created and committed to fetch the +URL. The next CCC link is dynamically assigned by examining the -URL's protocol. It can be: - - a_Http_ccc - a_File_ccc - a_About_ccc - a_Plugin_ccc (not implemented yet) - +URL's protocol. It can be a_Http_ccc or a_Dpi_ccc. - If we have a HTTP URL, a_Http_ccc will succeed, and the http + If we have an HTTP URL, a_Http_ccc will succeed, and the http module will be linked; it will create the proper HTTP query and link the IO module to submit and deliver the answer. - Note that as the Content-type of the URL is not always known + Note that as the Content-Type of the URL is not always known in advance, the answering branch decides where to dispatch it to upon HTTP header arrival. @@ -94,7 +87,7 @@ called for each tag (to parse and call the appropriate methods) and the whole page is contructed in a streamed way. Somewhere in the middle of it, resize and repaint functions are activated and idle functions draw to screen what has been -processed. +processed. (The process for images is described in Images.txt) diff --git a/doc/Dpid.txt b/doc/Dpid.txt index 8f69843e..bf9e8222 100644 --- a/doc/Dpid.txt +++ b/doc/Dpid.txt @@ -1,6 +1,6 @@ Aug 2003, Jorge Arellano Cid, Ferdi Franceschini -- -Last update: Dec 2004 +Last update: Nov 2009 ------ @@ -14,7 +14,7 @@ Nomenclature: dpi: generic term referring to dillo's plugin system (version1). - dpi1: + dpi1: specific term for dillo's plugin spec version 1. at: http://www.dillo.org/dpi1.html @@ -39,27 +39,24 @@ Nomenclature: never run more than one instance of a server plugin at a time. filter plugin: - Any program/script that can read or write to stdio. If you can write a - shell script you can write one of these (see examples at the end). + A dpi program that reads from stdin and writes to stdout, and that + exits after its task is done (they don't remain as server plugins). Warning, dpid will run multiple instances of filter plugins if requested. - This is safe if the plugin only writes to stdout which is what the filter - type dpis do at the moment. ----------- About dpid: ----------- * dpid is a program which manages dpi connections. - * dpid is a daemon that serves dillo using unix domain - sockets (UDS). + * dpid is a daemon that serves dillo using IDS sockets. * dpid launches dpi programs and arranges socket communication between the dpi program and dillo. The concept and motivation is similar to that of inetd. The -plugin manager (dpid) listens for a service request on a Unix -domain socket and returns the socket name of a plugin that -handles the service. It also watches sockets of inactive plugins -and starts them when a connection is requested. +plugin manager (dpid) listens for a service request on a socket +and returns the socket/port pair of a plugin that handles the +service. It also watches sockets of inactive plugins and starts +them when a connection is requested. ----------------------------------------------------------- @@ -72,9 +69,9 @@ problems (briefly outlined here): * When having two or more running instances of Dillo, one should prevail, and take control of dpi managing (but all dillos carry the managing code). - * If the managing dillo exits, it must pass control to another + * If the managing-dillo exits, it must pass control to another instance, or leave it void if there's no other dillo running! - * The need to synchronise all the running instances of + * The need to synchronize all the running instances of dillo arises. * If the controlling instance finishes and quits, all the dpi-program PIDs are lost. @@ -83,7 +80,7 @@ problems (briefly outlined here): * Forks can be expensive (Dillo had to fork its dpis). * When a managing dillo exits, the new one is no longer the parent of the forked dpis. - * If the Unix domain sockets for the dpis were to be named + * If Unix domain sockets for the dpis were to be named randomly, it gets very hard to recover their names if the controlling instance of dillo exits and another must "take over" the managing. @@ -109,12 +106,12 @@ What does dpid handle? * Different implementations of the same service dpi programs ("dpis") are just an implementation of a - service. There's no problem in having more than one for the - same service. + service. There's no problem in implementing a different one + for the same service (e.g. downloads). * Upgrading a service: to a new version or implementation without requiring - bringing down the dpid or patching dillo's core. + patching dillo's core or even bringing down the dpid. And finally, being aware that this design can support the @@ -124,8 +121,8 @@ following functions is very helpful: ------------------------------------------------------------ * "one demand/one response" man, preferences, ... * "resident while working" downloads, mp3, ... - * "resident until TERM signal" bookmarks, ... - + * "resident until exit request" bookmarks, ... + * "one client only" cd burner, ... * "one client per instance" man, ... * "multiple clients/one instance" downloads, cookies ... @@ -136,12 +133,12 @@ Features -------- * Dpi programs go in: "EPREFIX/dillo/dpi" or "~/.dillo/dpi". The binaries are named <name>.dpi as "bookmarks.dpi" and <name>.filter.dpi as in - "hello.filter.dpi". The ".filter" plugins simply read and write to stdio - and can be implemented with a shell script easily. + "hello.filter.dpi". The ".filter" plugins simply read from stdin + and write to stdout. * Register/update/remove dpis from list of available dpis when a - <dpi cmd='register_all'> is received. - * dpid terminates when it receives a <dpi cmd='DpiBye'> command. - * dpis can be terminated with a <dpi cmd='DpiBye'> command. + 'register_all' command is received. + * dpid terminates when it receives a 'DpiBye' command. + * dpis can be terminated with a 'DpiBye' command. * dpidc control program for dpid, currently allows register and stop. @@ -151,36 +148,7 @@ todo: These features are already designed, waiting for implementation: - * How to register/update/remove/ individual dpis? - * How to kill dpis? (signals) - - How: - - A useful and flexible way is to have a "control program" for -dpid (it avoids having to find its PID among others). - - Let's say: - - dpidc [register | upgrade | stop | ...] - - It can talk to a dpid UDS that serves for that (the same that -dillo would use). That way we may also have a dpidc dpi! :-) - - Seriously, what I like from this approach is that it is very -flexible and can be implemented incrementally ("dpidc register" -is enough to start). - - It also avoids the burden of having to periodically check the -dpis directory structure for changes). - - It also lets shell scripts an easy way to do the "dirty" work -of installing dpis; as is required with distros' package -systems. - -<note> - How do we tell a crashed dpi? That's the question. - We're thinking about using the "lease" concept (as in JINI). -</note> + * dpidc remove // May be not necessary after all... ----------------- @@ -193,14 +161,11 @@ o on startup dpid reads dpidrc for the path to the dpi directory o both directories are scanned for the list of available plugins. ~/.dillo/dpi overrides system-wide dpis. -o ~/.dillo/dpi_socket_dir is then checked for the name of the dpi socket - directory, if dpi_socket_dir does not exist it will be created. - -o next it creates Unix domain sockets for the available plugins and - then listens for service requests on its own socket (dpid.srs) +o next it creates internet domain sockets for the available plugins and + then listens for service requests on its own socket, and for connections to the sockets of inactive plugins. -o dpid returns the name of a plugin's socket when a client (dillo) +o dpid returns the port of a plugin's socket when a client (dillo) requests a service. o if the requested plugin is a 'server' then @@ -210,7 +175,7 @@ o if the requested plugin is a 'server' then o if the requested plugin is a 'filter' then 1) dpid accepts the connection - 2) duplicates the connection on stdio + 2) maps the socket fd to stdin/stdout (with dup2) 3) forks and starts the plugin 4) continues to watch the socket for new connections @@ -226,7 +191,7 @@ dpi service process diagram (I) .--- s1 s2 s3 ... sn - | + | [dpid] [dillo] | '--- srs @@ -236,7 +201,7 @@ dpi service process diagram (II) .--- s1 s2 s3 ... sn - | + | [dpid] [dillo] | | '--- srs ------------------' @@ -262,7 +227,7 @@ dpi service process diagram .[dpid] | [dillo] . | | | . '--- srs '---------------' - . + . .............[dpi program] when s3 has activity (incoming data), dpid forks the dpi @@ -271,7 +236,7 @@ dpi service process diagram (V) .--- s1 s2 (s3) ... sn - | + | [dpid] [dillo] | | '--- srs .---------------' @@ -285,170 +250,80 @@ communication process takes place until the task is done. When the dpi program exits, dpid resumes listening on the socket (s3). ------------------------------------------------ -How are the unix-domain-sockets for dpis named? ------------------------------------------------ - - Let's say we have two users, "fred" and "joe". - - When Fred's dillo starts its dpid, the dpid creates the -following directory (rwx------): - - /tmp/fred-XXXXXX - - using mkdtemp(). - - and saves that filename within "~/.dillo/dpi_socket_dir". - - That way, another dillo instance of user Fred can easily find -the running dpid's service request socket at: - - /tmp/fred-XXXXXX/dpid.srs - - (because it is saved in "~/.dillo/dpi_socket_dir"). - - Now, we have a dpi directory per user, and its permissions are -locked so only the user has access, thus the following directory -tree structure should pose no problems: - - /tmp/fred-XXXXXX/bookmarks - /downloads - /cookies - /ftp - ... - dpid.srs - - If user Joe starts his dillo, the same happens for him: - - /tmp/joe-XXXXXX/bookmarks - /downloads - /cookies - /ftp - ... - dpid.srs - - - What should dpid do at start time: - - Check if both, ~/.dillo/dpi_socket_dir and its directory, exist - (it can also check the ownership and permissions). - - If (both exist) - use them! - else - delete ~/.dillo/dpi_socket_dir - create another /tmp/<user>-XXXXXX directory - save the new directory name into ~/.dillo/dpi_socket_dir - (we could also add some paranoid level checks) - - To some degree, this scheme solves the tmpnam issue, different -users of dillo at the same time, multiple dillo instances, -polluting /tmp (cosmetic), and reasonably accounts for an -eventual dillo or dpid crash. - - It has worked very well so far! - - -------------------------------- So, how do I make my own plugin? -------------------------------- - First, at least, read the "Developing a dillo plugin" section -of dpi1 spec! :-) + Maybe the simplest way to get started is to understand a few +concepts and then to use the hands-on method by using/modifying +the hello dpi. It's designed as an example to get developers +started. - Note that the dpi1 spec may not be absolutely accurate, but the -main ideas remain. + --------- + Concepts: + --------- - Once you've got the concepts, contrast them with the drawings -in this document. Once it all makes sense, start playing with -hello.dpi, you can run it by starting dillo with - dillo dpi:/hello/ -or entering - dpi:/hello/ -as the url. Then try to understand how it works (use the drawings) -and finally look at its code. + * Dillo plugins work by communicating two processes: dillo + and the dpi. + * The underlying protocol (DPIP) has a uniform API which is + powerful enough for both blocking and nonblocking IO, and + filter or server dpis. + * The simplest example is one-request one-answer (for example + dillo asks for a URL and the dpi sends it). You'll find + this and more complex examples in hello.c - Really, the order is not that important, what really matters is -to do it all. + First, you should get familiar with the hello dpi as a user: - Start modifying hello.dpi, and then some more. When you feel -like trying new things, review the code of the other plugins for -ideas. + $dillo dpi:/hello/ - The hardest part is to try to modify the dpi framework code -inside dillo; you have been warned! It already supports a lot of -functionality, but if you need to do some very custom stuff, try -extending the "chat" command. + Once you've played enough with it, start reading the well +commented code in hello.c and start making changes! ---------------------------------- -Examples: Simple 'filter' plugins ---------------------------------- + --------------- + Debugging a dpi + --------------- - For a quick and dirty introduction to dpis try the following shell scripts. + The simplest way is to add printf() feedback using the MSG* +macros. You can start the dpid by hand on a terminal to force +messages to go there. - #!/bin/sh + Sometimes more complex dpis need more than MSG*. In this case +you can use gdb like this. - read -d'>' dpip_tag # Read dillo's request + 1.- Add an sleep(20) statement just after the dpi starts. + 2.- Start dillo and issue a request for your dpi. This will + get your dpi started. + 3.- Standing in the dpi source directory: + ps aux|grep dpi + 4.- Take note of the dpi's PID and start gdb, then: + (gdb) attach <PID> + 5.- Continue from there... - # Don't forget the empty line after the Content-type - cat <<EOF - <dpi cmd='start_send_page' url='dpi:/hi/hi.filter.dpi'> - Content-type: text - EOF + ------------ + Final Notes: + ------------ - echo Hi - - Of course you should use html in a real application (perl makes this easy). + 1.- If you already understand the hello dpi and want to try +something more advanced: - A more useful example uses the "si" system info viewer: + * bookmarks.c is a good example of a blocking server + * file.c is an advanced example of a server handling multiple + non-blocking connections with select(). - #!/bin/sh - # si - System Information Viewer + 2.- Multiple instances of a filter plugin may be run +concurrently, this could be a problem if your plugin records data +in a file, however it is safe if you simply write to stdout. +Alternatively you could write a 'server' plugin instead as they +are guaranteed not to run concurrently. - read -d'>' dpip_tag - - # We don't need to send the Content-type because "si --html" does this - # for us. - cat <<EOF - <dpi cmd='start_send_page' url='dpi:/si/si.dpi.filter'> - EOF - - si --html - - just make sure that you have si installed or you wont get far. - -To try out the examples create two directories for the scripts under your home directory as follows: - mkdir -p ~/.dillo/dpi/hi - mkdir -p ~/.dillo/dpi/si - -then create the scripts and put them in the dpi service directories so that you end up with - ~/.dillo/dpi/hi/hi.filter.dpi - ~/.dillo/dpi/si/si.filter.dpi - -Don't forget to make them executable. - -If dpid is already running register the new plugins with - dpidc register - -You can now test them by entering - dpi:/hi/ -or - dpi:/si/ -as the url. Or simply passing the url to dillo on startup - - dillo dpi:/si/ + 3.- The hardest part is to try to modify the dpi framework code +inside dillo; you have been warned! It already supports a lot of +functionality, but if you need to do some very custom stuff, try +extending the "chat" command, or asking in dillo-dev. - You can edit the files in place while dpid is running and reload them in -dillo to see the result, however if you change the file name or add a new -script you must run 'dpidc register'. -WARNING -Multiple instances of a filter plugin may be run concurrently, this could be a -problem if your plugin records data in a file, however it is safe if you simply -write to stdout. Alternatively you could write a 'server' plugin instead as -they are guaranteed not to run concurrently. - >>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< + >>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< diff --git a/doc/HtmlParser.txt b/doc/HtmlParser.txt index ec64164d..2eb8be63 100644 --- a/doc/HtmlParser.txt +++ b/doc/HtmlParser.txt @@ -1,5 +1,5 @@ October 2001, --Jcid - Last update: Dec 2004 + Last update: Jul 2009 --------------- THE HTML PARSER @@ -11,7 +11,7 @@ and plain text also. It has parsing 'modes' that define its behaviour while working: typedef enum { - DILLO_HTML_PARSE_MODE_INIT, + DILLO_HTML_PARSE_MODE_INIT = 0, DILLO_HTML_PARSE_MODE_STASH, DILLO_HTML_PARSE_MODE_STASH_AND_BODY, DILLO_HTML_PARSE_MODE_BODY, @@ -22,12 +22,12 @@ behaviour while working: The parser works upon a token-grained basis, i.e., the data stream is parsed into tokens and the parser is fed with them. The -process is simple: whenever the cache has new data, it gets +process is simple: whenever the cache has new data, it is passed to Html_write, which groups data into tokens and calls the -appropriate functions for the token type (TAG, SPACE or WORD). +appropriate functions for the token type (tag, space, or word). Note: when in DILLO_HTML_PARSE_MODE_VERBATIM, the parser -doesn't try to split the data stream into tokens anymore, it +doesn't try to split the data stream into tokens anymore; it simply collects until the closing tag. ------ @@ -65,44 +65,52 @@ TOKENS As it's a common mistake for human authors to mistype or forget one of the quote marks of an attribute value; the parser solves the problem with a look-ahead technique - (otherwise the parser could skip significative amounts of - well written HTML). + (otherwise the parser could skip significant amounts of + properly-written HTML). * WORD --> Html_process_word - A word is anything that doesn't start with SPACE, and that's + A word is anything that doesn't start with SPACE, that's outside of a tag, up to the first SPACE or tag start. SPACE = ' ' | \n | \r | \t | \f | \v ----------------- -THE PARSING STACK +THE PARSING STACK ----------------- The parsing state of the document is kept in a stack: - struct _DilloHtml { + class DilloHtml { [...] - DilloHtmlState *stack; - gint stack_top; /* Index to the top of the stack [0 based] */ - gint stack_max; + lout::misc::SimpleVector<DilloHtmlState> *stack; [...] }; struct _DilloHtmlState { - char *tag; - DwStyle *style, *table_cell_style; - DilloHtmlParseMode parse_mode; - DilloHtmlTableMode table_mode; - gint list_level; - gint list_number; - DwWidget *page, *table; - gint32 current_bg_color; - }; + CssPropertyList *table_cell_props; + DilloHtmlParseMode parse_mode; + DilloHtmlTableMode table_mode; + bool cell_text_align_set; + DilloHtmlListMode list_type; + int list_number; + + /* TagInfo index for the tag that's being processed */ + int tag_idx; + + dw::core::Widget *textblock, *table; + /* This is used to align list items (especially in enumerated lists) */ + dw::core::Widget *ref_list_item; + + /* This is used for list items etc; if it is set to TRUE, breaks + have to be "handed over" (see Html_add_indented and + Html_eventually_pop_dw). */ + bool hand_over_break; + }; Basically, when a TAG is processed, a new state is pushed into the 'stack' and its 'style' is set to reflect the desired @@ -73,7 +73,7 @@ are found in: Closing the TCP connection: The four packet-sending closing sequence of the TCP protocol. - + In a WAN context, every single item of this list has an associated delay that is non deterministic and often measured in seconds. If we add several connections per browsed page (each one @@ -96,7 +96,7 @@ The traditional (blocking) approach packets that belong to other connections may be arriving, and have to wait for service. - Web browsers handle many small transactions, + Web browsers handle many small transactions, if waiting times are not overlapped the latency perceived by the user can be very annoying. @@ -219,7 +219,7 @@ arrives, a call-back function is called, and the program resumes what it was doing at DNS-request time. The interesting thing is that the call-back happens in the main thread, while the child thread simply exits when done. This is implemented through a -server-channel design. +server-channel design. The server channel @@ -252,7 +252,7 @@ Basically, a socket file descriptor of AF_INET type is requested and set to non-blocking I/O. When the DNS server has resolved the name, the socket connection process begins by calling connect(2); {We use the Unix convention of identifying the manual section - where the concept is described, in this case + where the concept is described, in this case section 2 (system calls).} which returns immediately with an EINPROGRESS error. @@ -311,7 +311,7 @@ an error condition). ---------------------- Closing the connection ---------------------- - + Closing a TCP connection requires four data segments, not an impressive amount but twice the round trip time, which can be substantial. When data retrieval finishes, socket closing is @@ -370,7 +370,7 @@ passed to the I/O engine. 'ExtData' MAY be provided. 'Status', 'FD' and 'GioCh' are set by I/O engine internal -routines. +routines. When there is new data in the file descriptor, 'IO_callback' gets called (by glib). Only after the I/O engine finishes @@ -383,7 +383,7 @@ The I/O engine transfer buffer The 'Buf' and 'BufSize' fields of the request structure provide the transfer buffer for each operation. This buffer must be set by the client (to increase performance by avoiding copying -data). +data). On reads, the client specifies the amount and where to place the retrieved data; on writes, it specifies the amount and source diff --git a/doc/Images.txt b/doc/Images.txt index 96e09579..6a36e6f5 100644 --- a/doc/Images.txt +++ b/doc/Images.txt @@ -1,4 +1,4 @@ - December 2007, --Jcid + January 2009, --Jcid ------ IMAGES @@ -27,22 +27,24 @@ passed to the widget (DwImage) and drawn in a streamed way. Note that INDEXED images are also decoded into RGB format. Html_tag_open_img // IMG element processing - Html_add_new_image // Reat attributes, create image, add to HTML page - Html_load_image // Tells cache to retrieve image + Html_add_new_image // Read attributes, create image, add to HTML page a_Image_new // Create a 'DilloImage' data structure, to coordinate // decoded image-data transfer to an 'Imgbuf'. Html_add_widget // Adds the dw::Image to the page + Html_load_image // Tells cache to retrieve image --------------------- Fetching from the net --------------------- -* a_Cache_open_url initiates the resource request, and when +* a_Capi_open_url initiates the resource request, and when finally the answer arrives, the HTTP header is examined for MIME type and either the GIF or PNG or JPEG decoder is set to handle the incoming data stream. - Decoding functions: a_Gif_image, a_Jpeg_image and a_Png_image. + + Decoding functions: + a_Gif_callback, a_Jpeg_callback and a_Png_callback. * The decoding function calls the following dicache methods as the data is processed (listed in order): @@ -50,58 +52,62 @@ the data is processed (listed in order): a_Dicache_set_parms a_Dicache_set_cmap (only for indexed-GIF images) a_Dicache_write + a_Dicache_new_scan (MAY be called here or after set_cmap) a_Dicache_close + * The dicache methods call the necessary functions to connect with the widget code. This is done by calling image.c functions: a_Image_set_parms a_Image_set_cmap a_Image_write + a_Image_new_scan a_Image_close - -* The functions in image.c make the required a_Dw_image_... -calls. + +* The functions in image.c make the required Dw calls. ------------------------- Fetching from the dicache ------------------------- -* a_Cache_open_url tests the cache for the image, and directly -enqueues a cache client for it, without asking the network for -the data. When the client queue is processed (a bit later), the -decoder is selected based on the cache entry Type. +* a_Capi_open_url() tests the cache for the image, and the cache, +via a_Cache_open_url(), enqueues a client for it, without asking +the network for the data. When the client queue is processed (a +bit later), Dicache_image() is set as the callback. -* When the decoder is called, it tests the dicache for the image; -if the image is found, then it sets a_Dicache_callback as the -handling function and gets out of the way (no image decoding is -needed). +* When Dicache_image() is called, it sets the proper image data +decoder (RGB) and its data structure based on the entry's Type. +Then it substitutes itself with a_Dicache_callback() as the +handling function, and gets out of the way. -* Later on, the DwImage buffer is set to reference the -dicache-entry's buffer and the rest of the functions calls is -driven by a_Dicache_callback. +* Thenceforth the rest of the functions calls is driven by +a_Dicache_callback(). ----------- Misc. notes ----------- -* Repeated images generate new cache clients, but only one of -them (the first) is handled with a_Dicache_* functions, the rest -is done with a_Dicache_callback.. +* Repeated images generate new cache clients, but they may share +the imgbuf. + Note: Currently there's no proper support for transparent +images (i.e. decode to RGBA), but most of the time they render +the background color OK. This is: when first loaded, repeated +images share a background color, but when cached they render +correctly ;-). There's no point in trying to fix this because the +correct solution is to decode to RGBA and let the toolkit (FLTK) +handle the transparency. -* The cache-client callback is set when the Content-type of the -image is got. It can be: a_Png_image, a_Gif_image or a_Jpeg_image -Those are called 'decoders' because their main function is to -translate the original data into RGB format. +* The first cache-client callback (Dicache_image()) is set when +the Content-type of the image is got. -* Later on, the decoder can substitute itself, if it finds the -image has been already decoded, with a_Dicache_callback function. -This avoids decoding it twice. +* Later on, when there's a shared imgbuf, the dicache's logic +avoids decoding it multiple times and reuses what's already done. * The dicache-entry and the Image structure hold bit arrays that -represent which rows had been decoded. +represent which rows have been decoded. * The image processing can be found in the following sources: @@ -111,7 +117,7 @@ represent which rows had been decoded. - dw/image.{cc,hh} * Bear in mind that there are four data structures for image -code: +code: - DilloImage (image.hh) - DICacheEntry (dicache.h) diff --git a/doc/Imgbuf.txt b/doc/Imgbuf.txt index 1039ff9e..f4a56660 100644 --- a/doc/Imgbuf.txt +++ b/doc/Imgbuf.txt @@ -135,9 +135,9 @@ What happens in different situations: scaler is not yet in the list, it is added, and a local scaler is created. - - - + + - There are three images in the page, i1a, i1b, and i2. I1a and i1b refer to the same image recource, represented by the root image buffer diff --git a/doc/Makefile.am b/doc/Makefile.am index 9000fec0..d644393b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,7 @@ +dist_doc_DATA = user_help.html +man_MANS = dillo.1 EXTRA_DIST = \ + $(man_MANS) \ index.doc \ lout.doc \ dw-map.doc \ diff --git a/doc/NC_design.txt b/doc/NC_design.txt index 6932b9cf..380787f6 100644 --- a/doc/NC_design.txt +++ b/doc/NC_design.txt @@ -1,13 +1,13 @@ _________________________________________________________________ - + Naming&Coding design _________________________________________________________________ - + Dillo's code is divided into modules. For instance: bookmark, cache, dicache, gif. - - Lets think of a module named "menu", then: + + Let's think of a module named "menu", then: * Every internal routine of the module, should start with "Menu_" prefix. * "Menu_" prefixed functions are not meant to be called from outside @@ -15,66 +15,113 @@ * If the function is to be exported to other modules (i.e. it will be called from the outside), it should be wrapped with an "a_" prefix. - + For instance: if the function name is "Menu_create", then it's an internal function, but if we need to call it from the outside, then it should be renamed to "a_Menu_create". - + Why the "a_" prefix? Because of historical reasons. - And it reads better "a_Menu_create" than "d_Menu_create" cause the + And "a_Menu_create" reads better than "d_Menu_create" because the first one suggests "a Menu create" function! - + Another way of understanding this is thinking of "a_" prefixed functions as Dillo's internal library, and the rest ("Menu_" prefixed in our example) as a private module-library. - - Indentation: Source code must be indented with 3 blank spaces, no Tabs. + + Indentation: + + Source code must be indented with 3 blank spaces, no Tabs. Why? Because different editors expand or treat tabs in several ways; 8 spaces being the most common, but that makes code really wide and we'll try to keep it within the 80 columns bounds (printer friendly). - + + You can use: indent -kr -sc -i3 -bad -nbbo -nut -l79 myfile.c + Function commenting: - + Every single function of the module should start with a short comment - that explains it's purpose; three lines must be enough, but if you + that explains its purpose; three lines must be enough, but if you think it requires more, enlarge it. -/* - * Try finding the url in the cache. If it hits, send the contents - * to the caller. If it misses, set up a new connection. - */ -int a_Cache_open_url(const char *url, void *Data) -{ - ... - ... - ... -} - - We also have the BUG: and todo: tags. + /* + * Try finding the url in the cache. If it hits, send the contents + * to the caller. If it misses, set up a new connection. + */ + int a_Cache_open_url(const char *url, void *Data) + { + ... + ... + ... + } + + We also have the BUG:, TODO:, and WORKAROUND: tags. Use them within source code comments to spot hidden issues. For instance: -/* BUG: this counter is not accurate */ -++i; + /* BUG: this counter is not accurate */ + ++i; + + /* TODO: get color from the right place */ + a = color; + + /* WORKAROUND: the canonical way of doing it doesn't work yet. */ + ++a; ++a; ++a; + + Function length: + + Let's try to keep functions within the 45 lines boundary. This eases + code reading, following, understanding and maintenance. + + Functions with a single exit: + + It's much easier to follow and maintain functions with a single exit + point at the bottom (instead of multiple returns). The exception to + the rule are calls like dReturn_if_fail() at its head. + + dlib functions: + + * Dillo uses dlib extensively in its C sources. Before starting + to code something new, a good starting point is to check what + this library has to offer (check dlib/dlib.h). + * Memory management must be done using dNew, dNew0, dMalloc, dFree + and their relatives. + * For debugging purposes and error catching (not for normal flow): + dReturn_if_fail, dReturn_val_if_fail etc. are encouraged. + * The MSG macro is extensively used to output additional information + to the calling terminal. + + _________________________________________________________________ + + C++ + + Source code in C++ should follow the same rules with these exceptions: + + * Class method names are camel-cased and start with lowercase + e.g. appendInputMultipart + * Classes and types start uppercased + e.g. class DilloHtmlReceiver + * Class methods don't need to prefix its module name + e.g. links->get() + + We also try to keep the C++ relatively simple. Dillo does use + inheritance and templates, but that's about all. -/* todo: get color from the right place */ -a = color; _________________________________________________________________ - + What do we get with this? - + * A clear module API for Dillo; every function prefixed "a_" is to be used outside the module. - * A way for identifying where the function came from (the + * A way to identify where the function came from (the capitalized word is the module name). - * An inner ADT (Abstract data type) for the module. That can be + * An inner ADT (Abstract data type) for the module that can be isolated, tested and replaced independently. * A two stage instance for bug-fixing. You can change the exported function algorithms while someone else fixes the internal module-ADT! * A coding standard ;) _________________________________________________________________ - + Naming&Coding design by Jorge Arellano Cid @@ -1,15 +1,21 @@ -README: Last update Oct 2008 --jcid +README: Last update Jul 2009 - This documents need a review. They were current with dillo1 and -now, with dillo2, most of them are obsolete, specially Dw*txt, but -Dw2 is fully documented in html using doxygen. +These documents cover dillo's internals. +For user help, see http://www.dillo.org/dillo2-help.html - The other documents will be reviewed when I have some time. They -will give you an overview of what's going on but take them with a -pinch of salt. +-------------------------------------------------------------------------- - Of course I'd like to have these as doxygen files too! -If somebody wants to make this convertion, please let me know +These documents need a review. +*.txt were current with Dillo1, but many have since become more or + less out-of-date. +*.doc are doxygen source for the Dillo Widget (dw) component, and + were written for Dillo2. + +They will give you an overview of what's going on, but take them +with a pinch of salt. + + Of course I'd like to have *.txt as doxygen files too! +If somebody wants to make this conversion, please let me know to assign higher priority to updating these docs. -- @@ -31,16 +37,14 @@ Jorge.- Cookies.txt Explains how to enable cookies Current Dpid.txt Dillo plugin daemon Current -------------------------------------------------------------------------- - [This documents cover dillo's internal working. They're NOT a user manual] - -------------------------------------------------------------------------- - * Ah!, there's a small program (srch) within the src/ dir. It searches + * BTW, there's a small program (srch) within the src/ dir. It searches tokens within the whole code (*.[ch]). It has proven very useful. Ex: ./srch a_Image_write ./srch todo: - * Please submit your patches with 'diff -pru'. + * Please submit your patches with 'hg diff'. Happy coding! diff --git a/doc/Selection.txt b/doc/Selection.txt index 08fe0abc..7904bd94 100644 --- a/doc/Selection.txt +++ b/doc/Selection.txt @@ -26,7 +26,7 @@ The widget must construct simple iterators (DwIterator), which will be transferred to extended iterators (DwExtIterator), see below for more details. All event handling functions have the same signature, the arguments in detail are: - + - DwIterator *it the iterator pointing on the item under the mouse pointer, - gint char_pos the exact (character) position within diff --git a/doc/dillo.1 b/doc/dillo.1 new file mode 100644 index 00000000..6e96cf99 --- /dev/null +++ b/doc/dillo.1 @@ -0,0 +1,101 @@ +.TH dillo 1 "August 5, 2010" "version 2.2" "USER COMMANDS" +.SH NAME +dillo \- web browser +.SH SYNOPSIS +.B dillo +.RI [ OPTION ]... +.RB [ \-\- ] +.RI [ URL | FILE ]... +.SH DESCRIPTION +.PP +Dillo is a lightweight graphical web browser that aims to be secure. +It handles HTTP internally, and FILE, FTP, and +DATA URIs are handled through a plugin system (dpi). In addition, +.I INSECURE +HTTPS support can be enabled. Both FTP and Dillo's download manager use the +.BR wget (1) +downloader. +.PP +Dillo displays HTML, text, PNG, JPEG, and GIF files. +It handles cookies, basic authentication, proxying, and some CSS. +.PP +Framesets are displayed as links to frames, and there is currently +no support for javascript or video. +.SH OPTIONS +.TP +\fB\-f\fR, \fB\-\-fullwindow\fR +Start in full window mode: hide address bar, navigation buttons, menu, and +status bar. +.TP +\fB\-g\fR, \fB\-\-geometry \fIGEO\fR +Set initial window position where \fIGEO\fR is +\fIW\fBx\fIH\fR[{\fB+\-\fR}\fIX\fR{\fB+\-\fR}\fIY\fR]. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display this help text and exit. +.TP +\fB\-l\fR, \fB\-\-local\fR +Don't load images for these URL(s). +.TP +\fB\-v\fR, \fB\-\-version\fR +Display version info and exit. +.TP +\fB\-x\fR, \fB\-\-xid \fIXID\fR +Open first Dillo window in an existing window whose window ID is \fIXID\fR. +.SH EXIT STATUS +.TP +.B 0 +No error. +.TP +.B 1 +Internal error. +.TP +.B 2 +Error in command line arguments. +.SH ENVIRONMENT +.TP +.BR "HOME " "(or " "HOMEDRIVE " "and " "HOMEPATH " "on Cygwin)" +User's home directory. +.TP +.B http_proxy +URL of proxy to send HTTP traffic through. +.SH FILES +.TP +.I dpid +Dillo plugin daemon +.TP +.I dpidc +Control program for dpid. +.TP +.I ~/.dillo/bm.txt +User bookmarks +.TP +.I ~/.dillo/certs/ +Saved certificates for HTTPS. +.TP +.I ~/.dillo/cookies.txt +Stored cookies +.TP +.I ~/.dillo/cookiesrc +Cookie settings +.TP +.I ~/.dillo/dillorc +Configuration file. +.TP +.I ~/.dillo/dpid_comm_keys +Keys used in dpi daemon communication. +.TP +.I ~/.dillo/dpidrc +Contains name of directory containing dpis, and associates +dpi files with protocols. +.TP +.I ~/.dillo/keysrc +Keybindings. +.TP +.I ~/.dillo/style.css +User style sheet +.SH SEE ALSO +.BR wget (1) +.PP +Dillo website: +.B http://www.dillo.org diff --git a/doc/dw-changes.doc b/doc/dw-changes.doc index b76e9433..7050df9a 100644 --- a/doc/dw-changes.doc +++ b/doc/dw-changes.doc @@ -17,10 +17,6 @@ Related to the FLTK port, there have been many changes, this is a <li> The central class managing the widget tree is not anymore GtkDwViewport, but dw::core::Layout. - <li> There are multiple views (implementations of dw::core::View). - Typically, you keep a reference on dw::core::Layout and a "main" - view (a viewport). - <li> Drawing is done via dw::core::View, a pointer is passed to dw::core::Widget::draw. @@ -91,7 +87,7 @@ The old documentation has been moved to: <tr><td>remarks on specific widgets <td>respective source files: dw::Bullet, dw::core::ui::Embed <tr><td rowspan="2">DwImage.txt - <td>signals <td>dw::core::Widget::LinkReceiver + <td>signals <td>dw::core::Layout::LinkReceiver <tr><td>rest <td>dw::Image, \ref dw-images-and-backgrounds <tr><td colspan="2">Imgbuf.txt <td>dw::core::Imgbuf, @@ -106,4 +102,4 @@ The old documentation has been moved to: <tr><td colspan="2">Selection.txt <td>dw::core::SelectionState </table> -*/
\ No newline at end of file +*/ diff --git a/doc/dw-example-screenshot.png b/doc/dw-example-screenshot.png Binary files differnew file mode 100644 index 00000000..a4d37903 --- /dev/null +++ b/doc/dw-example-screenshot.png diff --git a/doc/dw-images-and-backgrounds.doc b/doc/dw-images-and-backgrounds.doc index c4991807..bb55aca5 100644 --- a/doc/dw-images-and-backgrounds.doc +++ b/doc/dw-images-and-backgrounds.doc @@ -109,7 +109,7 @@ digraph G { } "DICache Entry" -> ImageRenderer [headlabel="*", taillabel="1"]; - "DICache Entry" -> Imgbuf [headlabel="1", taillabel="1"]; + "DICache Entry" -> Imgbuf [headlabel="1", taillabel="1"]; BgRenderer -> Imgbuf [headlabel="1", taillabel="*"]; BgRenderer -> BgAllocation [headlabel="*", taillabel="1"]; diff --git a/doc/dw-layout-views.doc b/doc/dw-layout-views.doc index f064c671..d1118489 100644 --- a/doc/dw-layout-views.doc +++ b/doc/dw-layout-views.doc @@ -4,23 +4,18 @@ Rendering of Dw is done in a way resembling the model-view pattern, at least formally. Actually, the counterpart of the model, the layout (dw::core::Layout), does a bit more than a typical model, namely the layouting (delegated to the widget tree, see \ref dw-layout-widgets), -and the views do a bit less than a typical view, i.e. only the actual +and the view does a bit less than a typical view, i.e. only the actual drawing. Additionally, there is a structure representing common properties of -the platform, views generally work only together with one specific -platform. A platform is typically related to the underlying UI +the platform. A platform is typically related to the underlying UI toolkit, but other uses may be thought of. -This design helps to archieve three important goals: +This design helps to archieve two important goals: <ul> -<li> It makes different views of the same document simple, e.g. the - normal viewport and the preview window. - <li> Abstraction of the actual drawing, by different implementations - of dw::core::View. Most important, there must be a viewport, but - some other views are possible, e.g. a preview window. + of dw::core::View. <li> It makes portability simple. </ul> @@ -29,7 +24,7 @@ This design helps to archieve three important goals: <h2>Viewports</h2> Although the design implies that the usage of viewports should be -fully transparent to the layout module, this cannot be fully archived, +fully transparent to the layout module, this cannot be fully achieved, for the following reasons: <ul> @@ -41,15 +36,10 @@ for the following reasons: the size of a viewport, the text within should be rewrapped. </ul> -Therefor, dw::core::Layout keeps track of the viewport size, the +Therefore, dw::core::Layout keeps track of the viewport size, the viewport position, and even the thickness of the scrollbars, they are -relevant, see below for more details. These sizes are always equal in -all views. However, a given view may not use viewports at all, and -there may be the case, that no view related to a layout uses -viewports, in this case, the viewport size is not defined at all. - -(The case, that there is no viewport at all, is currently not well -defined, but this case does not occur currently within dillo.) +relevant, see below for more details. +If a viewport is not used, however, the size is not defined. Whether a given dw::core::View implementation is a viewport or not, is defined by the return value of dw::core::View::usesViewport. If this @@ -75,7 +65,7 @@ of the viewport. Views using viewports must </ol> Applications of scrolling positions (anchors, test search etc.) are -handled by the layout, in a way fully transparent to the views. +handled by the layout, in a way fully transparent to the view. <h3>Scrollbars</h3> @@ -86,11 +76,10 @@ respectively. If they are not needed, they are hidden, to save screen space. Since scrollbars decrease the usable space of a view, dw::core::Layout -must know how much space they take. Each view returns, via +must know how much space they take. The view returns, via dw::core::View::getHScrollbarThickness and dw::core::View::getVScrollbarThickness, how thick they will be, when -visible. The total space difference is then the maximum of all values, -which the views return. +visible. Viewport sizes, which denote the size of the viewport widgets, include scrollbar thicknesses. When referring to the viewport \em excluding @@ -100,7 +89,7 @@ the area, which is used to display the canvas. <h2>Drawing</h2> A view must implement several drawing methods, which work on the whole -canvas. If it is neccesary to convert them (e.g. into +canvas. If it is necessary to convert them (e.g. into dw::fltk::FltkViewport), this is done in a way fully transparent to dw::core::Widget and dw::core::Layout, instead, this is done by the view implementation. @@ -115,8 +104,8 @@ There exist following situations: <li> A widget requests a redraw: In this case, the widget will delegate this to the layout (dw::core::Layout::queueDraw), which - delegates it to all views (dw::core::View::queueDraw). - Typically, the views will queue these requests, for efficiency. + delegates it to the view (dw::core::View::queueDraw). + Typically, the view will queue these requests for efficiency. <li> A widget requests a resize: This case is described below, in short, dw::core::View::queueDrawTotal is called for the view. @@ -160,10 +149,9 @@ flickering. <h2>Sizes</h2> -Generally, all views show the same layout, which has a given size -(canvas size). In the simplest case, views do not have an influence on -the canvas size, so that they are just told about changes of the -canvas size, by a call to dw::core::View::setCanvasSize. This happens +In the simplest case, the view does not have any influence on +the canvas size, so it is told about changes of the +canvas size by a call to dw::core::View::setCanvasSize. This happens in the following situations: <ul> @@ -177,28 +165,26 @@ in the following situations: <h3>Viewports</h3> -Furthermore, viewport sizes and scrollbar thicknesses are always the -same. There are two cases, in which the viewport size changes: +There are two cases where the viewport size changes: <ul> <li> As an reaction on a user event, e.g. when the user changes the - window size. In this case, the affected view delegates this + window size. In this case, the view delegates this change to the layout, by calling - dw::core::Layout::viewportSizeChanged. All other views are - told about this, by calling dw::core::Layout::setViewportSize. + dw::core::Layout::viewportSizeChanged. <li> The viewport size may also depend on the visibility of UI widgets, which depend on the world size, e.g scrollbars, - generally called "viewport markers". This is described in an own + generally called "viewport markers". This is described in a separate section. </ul> After the creation of the layout, the viewport size is undefined. When -a view is attached to a layout, and this view is already to be able to -define its viewport size, it may already call +a view is attached to a layout, and this view can already specify +its viewport size, it may call dw::core::Layout::viewportSizeChanged within the implementation of -dw::core::Layout::setLayout. If not, it may do this, as soon as the -viewport size gets known. +dw::core::Layout::setLayout. If not, it may do this as soon as the +viewport size is known. Generally, the scrollbars have to be considered. If e.g. an HTML page is rather small, it looks like this: @@ -267,4 +253,4 @@ This results in the following rules: is done anymore. </ol> -*/
\ No newline at end of file +*/ diff --git a/doc/dw-layout-widgets.doc b/doc/dw-layout-widgets.doc index f5b0ed06..d488efd8 100644 --- a/doc/dw-layout-widgets.doc +++ b/doc/dw-layout-widgets.doc @@ -81,7 +81,7 @@ different situations: <ol> <li> Adding an anchor is inititiated by a specific widget method, e.g. dw::Textblock::addAnchor. Here, dw::core::Widget::addAnchor must be - called, + called, <li> Whenever the position of an anchor is changed, dw::core::Widget::changeAnchor is called (typically, this is done @@ -107,14 +107,11 @@ In two cases, a widget has to be drawn: </ol> In both cases, drawing is done by the implementation of -dw::core::Widget::draw. Generally, a widget draws into different views -(see \ref dw-layout-views), the view to draw into is passed as the -first argument. In the first case, only the view, which causes the -expose event, is passed, in the second case, dw::core::Widget::draw is -called multiple times, once for each view connected to the layout. +dw::core::Widget::draw, which draws into the view. + Each view provides some primitive methods for drawing, most should be -obvious. Notice that the views do not know anything about dillo +obvious. Note that the views do not know anything about dillo widgets, and so coordinates have to be passed as canvas coordinates. A widget may only draw in its own allocation. If this cannot be @@ -144,7 +141,7 @@ void Foo::draw (dw::core::View *view, dw::core::Rectangle *area) } \endcode -Clipping views are expensive, so they should be avoided, when possible. +Clipping views are expensive, so they should be avoided when possible. The second argument to dw::core::Widget::draw is the region, which has to be drawn. This may (but needs not) be used for optimization. @@ -169,9 +166,9 @@ dw-widget-sizes.) <h2>Mouse Events</h2> -A widget may process mouse events. The views (\ref dw-layout-views) -pass mouse events to the layout, which then passes them to the -widgtes. There are two kinds of mouse events: +A widget may process mouse events. The view (\ref dw-layout-views) +passes mouse events to the layout, which then passes them to the +widgets. There are two kinds of mouse events: <ul> <li>events returning bool, and @@ -221,9 +218,9 @@ in which the mouse pointer is now ("new widget"). The following paths are calculated: <ol> -<li> the path from the old widget to the nearest common anchestor of the old +<li> the path from the old widget to the nearest common ancestor of the old and the new widget, and -<li> the path from this anchestor to the new widget. +<li> the path from this ancestor to the new widget. </ol> For the widgets along these paths, dw::core::Widget::enterNotifyImpl @@ -232,7 +229,7 @@ and dw::core::Widget::leaveNotifyImpl are called. <h3>Signals</h3> If a caller outside of the widget is interested in these events, he -can connect a dw::core::Widget::EventReceiver. For those events with a +can connect a dw::core::Layout::LinkReceiver. For those events with a boolean return value, the results of the signal emission is regarded, i.e. the delegation of an event to the parent of the widget can be stopped by a signal receiver returning true, even if the widget method @@ -267,4 +264,4 @@ background colors to parts of a widget (as dw::Table does for rows), it must call dw::core::Widget::setBgColor for the children inside this part. -*/
\ No newline at end of file +*/ diff --git a/doc/dw-overview.doc b/doc/dw-overview.doc index 2414a5da..8c740635 100644 --- a/doc/dw-overview.doc +++ b/doc/dw-overview.doc @@ -108,13 +108,13 @@ A short overview: <ul> <li> dw::core::Layout is the central class, it manages the widgets and the - views, and provides delegation methods for the platform. + view, and provides delegation methods for the platform. <li> The layouting is done by a tree of widgets (details are described in \ref dw-layout-widgets), also the drawing, which is finally delegated - to the views. + to the view. -<li> The views (implementations of dw::core::View) provide primitive methods +<li> The view (implementation of dw::core::View) provides primitive methods for drawing, but also have an influence on the canvas size (via size hints). See \ref dw-layout-views for details. @@ -147,11 +147,11 @@ files: A complete map can be found at \ref dw-map. -<ul> +<ul> <li> For learning, how to use Dw, read \ref dw-usage and related documents, dw::core::style, dw::core::ui and \ref dw-images-and-backgrounds. <li> Advanced topics are described in \ref dw-layout-widgets, \ref dw-widget-sizes and \ref dw-layout-views. </ul> -*/
\ No newline at end of file +*/ diff --git a/doc/dw-size-of-widget.png b/doc/dw-size-of-widget.png Binary files differnew file mode 100644 index 00000000..eda93ee1 --- /dev/null +++ b/doc/dw-size-of-widget.png diff --git a/doc/dw-style-box-model.png b/doc/dw-style-box-model.png Binary files differnew file mode 100644 index 00000000..aa65ecb7 --- /dev/null +++ b/doc/dw-style-box-model.png diff --git a/doc/dw-style-length-absolute.png b/doc/dw-style-length-absolute.png Binary files differnew file mode 100644 index 00000000..6b4d8389 --- /dev/null +++ b/doc/dw-style-length-absolute.png diff --git a/doc/dw-style-length-percentage.png b/doc/dw-style-length-percentage.png Binary files differnew file mode 100644 index 00000000..15b36958 --- /dev/null +++ b/doc/dw-style-length-percentage.png diff --git a/doc/dw-style-length-relative.png b/doc/dw-style-length-relative.png Binary files differnew file mode 100644 index 00000000..d54d99b5 --- /dev/null +++ b/doc/dw-style-length-relative.png diff --git a/doc/dw-textblock-collapsing-spaces-1-1.png b/doc/dw-textblock-collapsing-spaces-1-1.png Binary files differnew file mode 100644 index 00000000..d528dfb2 --- /dev/null +++ b/doc/dw-textblock-collapsing-spaces-1-1.png diff --git a/doc/dw-textblock-collapsing-spaces-1-2.png b/doc/dw-textblock-collapsing-spaces-1-2.png Binary files differnew file mode 100644 index 00000000..483e79d1 --- /dev/null +++ b/doc/dw-textblock-collapsing-spaces-1-2.png diff --git a/doc/dw-textblock-collapsing-spaces-2-1.png b/doc/dw-textblock-collapsing-spaces-2-1.png Binary files differnew file mode 100644 index 00000000..0a03ea80 --- /dev/null +++ b/doc/dw-textblock-collapsing-spaces-2-1.png diff --git a/doc/dw-textblock-collapsing-spaces-2-2.png b/doc/dw-textblock-collapsing-spaces-2-2.png Binary files differnew file mode 100644 index 00000000..b89c6254 --- /dev/null +++ b/doc/dw-textblock-collapsing-spaces-2-2.png diff --git a/doc/dw-usage.doc b/doc/dw-usage.doc index d0aa8d36..913a4862 100644 --- a/doc/dw-usage.doc +++ b/doc/dw-usage.doc @@ -20,7 +20,7 @@ As described in \ref dw-overview, the following objects are needed: <li> some widgets (for this example, only a simple dw::Textblock). </ul> -First of all, the necessary #include's: +First of all, the necessary \#include's: \code #include <fltk/Window.h> @@ -39,7 +39,7 @@ int main(int argc, char **argv) { \endcode -As the first object, the platform is instanciated: +As the first object, the platform is instantiated: \code dw::fltk::FltkPlatform *platform = new dw::fltk::FltkPlatform (); @@ -109,7 +109,7 @@ defined, here dw::core::style::Color::createSimple must be called: Finally, the style for the widget is created: \code - dw::core::style::Style *widgetStyle = + dw::core::style::Style *widgetStyle = dw::core::style::Style::create (layout, &styleAttrs); \endcode @@ -258,7 +258,7 @@ There are three dw::core::View implementations for FLTK: overview of the whole canvas. <li> dw::fltk::FltkFlatView is a "flat" view, i.e. it does not support - scrolling. It is used for HTML buttons, see + scrolling. It is used for HTML buttons, see dw::fltk::ui::FltkComplexButtonResource and especially dw::fltk::ui::FltkComplexButtonResource::createNewWidget for details. </ul> diff --git a/doc/dw-viewport-with-scrollbar.png b/doc/dw-viewport-with-scrollbar.png Binary files differnew file mode 100644 index 00000000..7ac62de3 --- /dev/null +++ b/doc/dw-viewport-with-scrollbar.png diff --git a/doc/dw-viewport-without-scrollbar.png b/doc/dw-viewport-without-scrollbar.png Binary files differnew file mode 100644 index 00000000..8aa20fec --- /dev/null +++ b/doc/dw-viewport-without-scrollbar.png diff --git a/doc/dw-widget-sizes.doc b/doc/dw-widget-sizes.doc index 989eb83c..c93ce541 100644 --- a/doc/dw-widget-sizes.doc +++ b/doc/dw-widget-sizes.doc @@ -102,7 +102,7 @@ passed to the calles are </ul> Generally, the values should define the available space for the -widget. +widget. A widget, which depends on size hints, should call dw::core::Widget::queueResize, when apropriate. @@ -183,4 +183,4 @@ This way, a widget can exactly keep track on size changes, and so implement resizing in a faster way. A good example on how to use this is dw::Textblock. -*/
\ No newline at end of file +*/ diff --git a/doc/fltk-problems.doc b/doc/fltk-problems.doc index 3e8c401f..6f20c44d 100644 --- a/doc/fltk-problems.doc +++ b/doc/fltk-problems.doc @@ -5,19 +5,6 @@ Current problems: <ul> -<li> dw::fltk::FltkViewport::draw should only draw the region, for which e.g. - an expose event was received. - -<li> dw::fltk::FltkViewport::queueDraw will collect data, which has to be - redrawn. Currently, it calls redraw (DAMAGE_EXPOSE), can this be changed, - so that dw::fltk::FltkViewport::draw will distinguish between the two - cases? - -<li> For Scrolling, something similar applies, only parts of the viewport - have to be redrawn. - -<li> Also for Scrolling, it is necessary to copy parts of the window. - <li> How should dw::fltk::FltkViewport::cancelQueueDraw be implemented? <li> If the value of a scrollbar is changed by the program, not the user, @@ -27,12 +14,7 @@ Current problems: <li> Also, the problems with the widgets seems to work. Also sure? -<li> When drawing, clipping of 32 bit values seems to work. - -<li> Who is responsable for clearing before drawing? - -<li> The embedded buttons are not redrawn, when pressing the mouse button - on them. +<li> When drawing, clipping of 32 bit values is not working properly. <li> The item group within a selection widget (menu) should not be selectable. </ul> @@ -74,11 +56,6 @@ perhaps different implementations for different window systems could be used. Then, it is for X necessary to use GCs with clipping masks. -<h2>Lower Priority</h2> - -There needs to be an XEmbed implementation. - - <h2>dw::fltk::ui::ComplexButton</h2> Unfortunately, FLTK does not provide a button with Group as parent, so @@ -106,7 +83,7 @@ The following changes should be applied manually. <h3>Changes in fltkcomplexbutton.hh</h3> -First of all, the #define's for avoiding multiple includes: +First of all, the \#define's for avoiding multiple includes: \code -#ifndef fltk_ComplexButton_h // fltk_Button_h formerly @@ -133,7 +110,7 @@ at the end. Then, the namespace is changed: at the beginning and -\code +\code -} +} // namespace ui +} // namespace fltk @@ -151,7 +128,7 @@ at the end. Most important, the base class is changed: and -\code +\code -class FL_API ComplexButton : public Widget { +class ComplexButton: public ::fltk::Group +{ @@ -167,10 +144,10 @@ namespace conflict: <h3>Changes in fltkcomplexbutton.cc</h3> -First, #include's: +First, \#include's: \code - + #include <fltk/events.h> #include <fltk/damage.h> -#include <fltk/ComplexButton.h> // <fltk/Button.h> formerly @@ -216,4 +193,4 @@ dw::fltk::ui::ComplexButton::draw()): } \endcode -*/
\ No newline at end of file +*/ diff --git a/doc/uml-legend.doc b/doc/uml-legend.doc index 14a64e7d..90294ef6 100644 --- a/doc/uml-legend.doc +++ b/doc/uml-legend.doc @@ -119,10 +119,10 @@ In this example, </ul> -<h2>Template Instanciations</h2> +<h2>Template Instantiations</h2> -Template instanciations are shown as own classes/interfaces, the -instanciation by the template is shown by a yellow dashed arrow: +Template instantiations are shown as own classes/interfaces, the +instantiation by the template is shown by a yellow dashed arrow: \dot digraph G { diff --git a/doc/user_help.html b/doc/user_help.html new file mode 100644 index 00000000..296b0c5a --- /dev/null +++ b/doc/user_help.html @@ -0,0 +1,298 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <title> Help for Dillo </title> +</head> + +<body bgcolor='#778899' text='#000000'> + + <table bgcolor="#70a0c0" border="1" cellpadding="5"> + <tr><td><h1>Help for Dillo 2.2</h1> + </table> + <p> + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=5> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Basics:</font></h4> + </td></tr> + + <tr><td WIDTH="100%" bgcolor="#70a0c0"> + <ul> + <li>You can tell a link from plain content by the hand-shaped cursor. + <li> Besides browsing the web, Dillo also has basic file browsing + capabilities included. So, entering <a href="file:">file:</a> in your + Dillo URL window will give you the contents of your current + working directory, and <a href="file:~">file:~</a> entered in the + same place will point your Dillo browser right to your home + directory... + <li> Dillo, at this stage of development, is <u>not</u> not ready + to render pages that use <b><font color="#5040a0">frames</font></b>. + Nevertheless, it comes with a tiny handler (lynx/w3m-like) that will + let you choose which frame to visit, one by one. + <li> Dillo has <b><font color="#5040a0">context + sensitive menus</font></b> using the right mouse button + (available on pages, links, images, forms, the Back + and Forward buttons, and the bug meter). + <li> Some of the functions in Dillo are handled by independent + processes. For instance, downloads come through <em>wget</em>. + If Dillo exits, the download can continue (more details + below). + </ul> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Usage:</font></h4> + </td></tr> + + <tr><td BGCOLOR="#70a0c0"> + <ul> + <li> You can scroll around your Dillo main window using + CTRL+{PgUp|PgDwn|Home|End} or using the mouse middle button + or mouse wheel. If nothing happens when keys are pressed, try + <b> <font color="#5040a0">focusing</font></b> your Dillo main + window first by clicking it (not on any link!:)). + <li> You can use the space key as PgDn, and {'b' | 'B'} as PgUp.</li> + <li> Similarly, you can use "<b>,</b>" and "<b>.</b>" as shortcuts for + forward and backward buttons (mnemonic: those + keys are usually labeled "<" and ">"). + <li> <b>Configuration:</b> If you want to change Dillo's + appearance or behaviour, look at the options in your + <b><font color="#5040a0">dillorc</font></b> + file (if you don't have a copy in your ~/.dillo/ directory, get it + <a href='http://www.dillo.org/dillorc'>here</a>). + <li> Clicking the "Reload" button always requests an end-to-end reload + of the page currently viewed, but it will *not* reload embedded + images during this process. + <li> Dialogs can be closed with the ESC key. + <li> If you want to try a different control panel, right-click over the + search button until you find one that suits your needs, then make + it the default in your <code>dillorc</code> file. + <li> The whole window area can be used to display the page. Just hit + Ctrl-Space! + </ul> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Downloads:</font></h4> + </td></tr> + + <tr><td BGCOLOR="#70a0c0"> + <p> + Downloads are made using <b><font color="#5040a0">wget</font></b> + with a FLTK2-based GUI wrapper, through the Dillo plugin (dpi) framework. + If you close the browser window, downloads will continue. + <p> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Find text:</font></h4> + </td></tr> + + <tr><td bgcolor="#70a0c0"> + <p> + This one is very useful; + it can be found in the right-mouse-button menu<br> + Find text is tuned for speed so don't hesitate to use it even for minimal + searches. + <p> + <u>Semantics:</u> + <ul> + <li> You can search for substrings, words and sentences. </li> + <li> To find a substring or word, just enter its text. </li> + <li> To find a left-aligned substring, prepend it with a space. </li> + <li> To find a right-aligned substring, append a space to it.</li> + <li> To find full words only, prepend and append spaces to them. </li> + <li> To find a sentence, enter the words and remember that the above rules + apply for every word in it. </li> + </ul> + <p> + Dillo will scroll the page and highlight found text! + <p> + <small>Default shortcut: [CTRL]+"F".</small> + + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Copy&Paste:</font></h4> + </td></tr> + + <tr><td bgcolor="#70a0c0"> + <p> + Just hold down the left mouse button and move to select the + area to copy. To paste, go to the target application and + press the middle mouse button. + <p> + If you want to select more than one screen, hold the mouse button + down and scroll with PgUp, PgDn or the arrow keys. + <P> + If you want to paste an URL into Dillo, do it on the "clear-URL" + button (the "X" next to the location bar). + <p> + Note: If it doesn't work, please try again. There's a bug lurking there. + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Navigation history:</font></h4> + </td></tr> + + <tr><td bgcolor="#70a0c0"> + <p> + Currently, navigation history supports the navigation-stack model; just + right-click on the Back or Forward buttons and they will pop up! + <p> <u>Remember:</u> + <ul> + <li> These history menus are relative to the current page. </li> + <li> They show the page-title but the status bar shows the URL. </li> + <li> Left-click jumps to the selected item. </li> + <li> Middle-click opens the item in a new browser tab/window. </li> + </ul> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Cookies:</font></h4> + </td></tr> + + <tr><td bgcolor="#70a0c0"> + <p> + Due to privacy concerns, cookies are disabled by default. + That is, if you just compile and use dillo, it will reject + every single cookie sent to it! + <p> + If you want to enable cookies in dillo, just + <a href="http://www.dillo.org/Cookies.txt">set up a <code>cookiesrc</code> + file</a>. + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Tabs:</font></h4> + </td></tr> + + <tr><td bgcolor="#70a0c0"> + <p> + Dillo has tabbed browsing. Just middle click to open a link or submit a + form in a new tab. It will be automatically focused. If you want to + customize this behaviour, adjust these dillorc options: + <ul> + <li><code>middle_click_opens_new_tab</code> + <li><code>focus_new_tab</code> + </ul> + Press SHIFT to temporarily reverse the focusing behaviour. + <p> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Images-off mode:</font></h4> + </td></tr> + <tr><td bgcolor="#70a0c0"> + <p> + You can browse without images now: + <ul> + <li>There is an option in the Tools menu to disable automatic image loading. + An image's alt text (or <code>[IMG]</code> placeholder) will appear in the + page. + <li>If you want to load an individual image, left click on its text. + <li>You can set "no images" as the default mode in dillorc. + </ul> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Bookmarks:</font></h4> + </td></tr> + + <tr><td bgcolor="#70a0c0"> + <p> + Bookmarks are handled by the Dillo plugin + (<a href='http://www.dillo.org/dpi1.html'>dpi</a>) framework. + This should be transparent to the end user. Please note that: + <ul> + <li>It is a good idea to keep a backup of your + <code>~/.dillo/bm.txt</code> + <li>The server will stay alive after closing dillo. + <li>You can stop the server by sending it a KILL signal. Dillo + will automatically restart it when it is needed. + <li>If you don't have root access, install <em>dpid</em> and + the <em>dpis</em> + inside your <code>~/.dillo/</code> directory as explained + in the README file. + </ul> + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Bug Meter:</font></h4> + </td></tr> + <tr><td bgcolor="#70a0c0"> + <p> + Dillo's <a href='http://www.dillo.org/help/bug_meter.html'>bug meter</a> + shows the number of + <b><font color="#5040a0">detected bugs</font></b> inside the + page. The bugs are caught at parsing time, so the + error messages also show the line where they occur and provide a + <b><font color="#5040a0">hint</font></b> of what was expected instead! + <p> + The primary purpose of the bug meter is to + <b><font color="#5040a0">help</font></b> webmasters and page + authors to polish the contents of their sites with a view to making + them standards-compliant. + <p> + The bug meter is located at the lower right corner of + Dillo. Left-click to see the messages, right-click for a menu. + </td></tr> + </table> + + <table WIDTH="100%" BORDER=1 CELLSPACING=0 CELLPADDING=3> + <tr ALIGN=LEFT VALIGN=TOP><td bgcolor="wheat"> + <h4><font color="green">Keyboard shortcuts:</font></h4> + </td></tr> + <tr><td bgcolor="#70a0c0"> +<table border=1 width="100%"> +<tr><th>Shortcut <th>Mnemonic <th>Function +<tr><td>Ctrl-L <td>Location <td>enter a new URL +<tr><td>Ctrl-F <td>Find <td>find text +<tr><td>Ctrl-S <td>Search <td>search the web +<tr><td>Ctrl-R <td>Reload <td>reload current page +<tr><td>Ctrl-N <td>New <td>New browser window +<tr><td>Ctrl-T <td>Tab <td>New tab +<tr><td>Ctrl-Q <td>Quit <td>quit tab/window +<tr><td>Ctrl-O <td>Open <td>Open file +<tr><td>Ctrl-B <td>Bookmarks <td>view bookmarks +<tr><td>Ctrl-Space <td>"more space!" <td>Hide/show controls +<tr><td>Back or "<b>,</b>" <td>< <td>previous page +<tr><td>Shift-Back or "<b>.</b>" <td>> <td>next page +<tr><td>Esc <td>escape <td>close dialog +<tr><td>Alt-F <td>File <td>file menu +<tr><td>Alt-X <td>eXit <td>exit Dillo +<tr><td>Shift-Right <td>Right <td>Next tab +<tr><td>Shift-Left <td>Left <td>Previous tab +<tr><td>Ctrl-TabKey <td>TabKey <td>Next tab +<tr><td>Shift-Ctrl- TabKey <td>TabKey <td>Previous tab +</table> +<p> +You can change the bindings using a +<code>~/.dillo/<a href="http://www.dillo.org/keysrc">keysrc</a></code> +file. + </td></tr> + </table> + +</body> +</html> |
