Merge pull request #327 from sshanks-kx/refactor

refactor

Author: jburrKX

docs/architecture/index.md

@@ -7,9 +7,9 @@ keywords: hdb, kdb+, q, rdb, tick, tickerplant, streaming
 
 A kdb+ tick based archecture can be used to capture, process and analyse vasts amount of real-time and historical data.
 
-The following diagram illustrates the components that are often found in a vanilla kdb+ tick setup:
+The following diagram illustrates the components that are often found in a vanilla kdb+ tick setup:<br>
 
-![architecture](../img/architecture.png)
+![architecture](../img/tick_arch.svg)
 
 ## Components
 

docs/architecture/rq.md

@@ -30,6 +30,8 @@ If known/common queries can be designed, the RDB can load additional scripts to
 
 ### End-of-day
 
+![RDB_end-of-day](../img/rdb_end_of_day.svg)
+
 The end-of-day event is governed by the tickerplant process. The tickerplant calls the RDB [`.u.end`](#uend) function when this event occurs.
 The main end-of-day event for an RDB is to save todays data from memory to disk, clear its tables and uses IPC to instruct the HDB to be aware of a new days dataset for it to access.
 
@@ -42,6 +44,10 @@ The function [`.u.rep`](#urep) is then used to [replay the log](../kb/logging.md
 
 !!! Note "The RDB should be able to access the tickerplant log from a directory on the same machine. The RDB/tickerplant can be changed to reside on different hosts but this increases the resources needed to transmit the log file contents over the network."
 
+The following diagram shows the steps taken by an RDB to recover from a TP log:
+
+![RDB_end-of-day](../img/TP_log_recovery.svg)
+
 ## Usage
 
 ```bash
@@ -84,12 +90,12 @@ Where
 
 ### .u.end
 
-Perform end-of-day actions of saving tables to disk, clearing tables and running reload on HDB instance to make it aware of new day of data.
+Perform [end-of-day actions](end-of-day) of saving tables to disk, clearing tables and running reload on HDB instance to make it aware of new day of data.
 
 ```q
 .u.end[x]
 ```
-Where x is the date that has ended.
+Where x is the date that has ended, as a date atom type.
 
 Actions performed:
 
@@ -103,7 +109,7 @@ Actions performed:
 
 ### .u.rep
 
-Initialise RDB by creating tables, which is then populated with any existing tickerplant log. Will set the HDB directory to use at end-of-day.
+Initialise RDB by creating tables, which is then [populated with any existing tickerplant log](#recovery). Sets the HDB directory to be used at end-of-day.
 
 ```q
 .u.rep[x;y]

docs/architecture/uq.md

@@ -134,13 +134,13 @@ Where
 * `y` is list of syms used to filter table data, with empty sym representing for all table data
 
 If `x` is empty symbol, client is subscribed to all known tables using `y` criteria. This is achieved by calling .u.sub for each table in [`.u.t`](#variables). 
-It then returns a list of all the return values provided by .u.sub (i.e. a list of pairs comprising of table name and table definition).
-
-An error is returned if the table does not exist.
-
 For the subscribing  client, any previous registered in the given tables are removed prior to reinstating new criteria provided i.e. calls [`.u.del`](#udel).
+Calls [`.u.add`](#uadd) to record the client subscription.
 
-Calls [`.u.add`](#uadd) to record the client subscription and passes the returned values to client.
+Returns 
+* a two item list if x is an indivial table name. First item is the table name subscribed to as a symbol. Second item is an empty table (table schema).
+* a list of two item lists as described above for each individual table, if x is an empty symbol (i.e. subscribe to all tables)
+* an error if the table does not exist.
 
 ### .u.end
 

docs/basics/funsql.md

@@ -10,6 +10,12 @@ keywords: delete, exec, functional, kdb+, q, select, sql, update
 
 The functional forms of [`delete`](../ref/delete.md), [`exec`](../ref/exec.md), [`select`](../ref/select.md) and [`update`](../ref/update.md) are particularly useful for programmatically-generated queries, such as when column names are dynamically produced. 
 
+Functional form is an alternative to using a [qSQL template](qsql.md) to construct a query. For example, the folowing are equivalent:
+```q
+q)select n from t
+q)?[t;();0b;(enlist `n)!enlist `n]
+```
+
 !!! info "Performance"
 
     The q interpreter parses `delete`, `exec`, `select`, and `update` into their equivalent functional forms, so there is no performance difference.

docs/basics/peach.md

@@ -138,7 +138,7 @@ Each secondary thread has its own heap, a minimum of 64MB.
 
 Since V2.7 2011.09.21, [`.Q.gc[]`](../ref/dotq.md#gc-garbage-collect) in the main thread collects garbage in the secondary threads too.
 
-Automatic garbage collection within each thread (triggered by a wsfull, or hitting the artificial heap limit as specified with [`-w`](cmdline.md#-w-workspace) on the command line) is executed only for that particular thread, not across all threads.
+Automatic garbage collection within each thread (triggered by a [`wsfull`](../basics/errors.md#wsfull)), or hitting the artificial heap limit as specified with [`-w`](cmdline.md#-w-workspace) on the command line) is executed only for that particular thread, not across all threads.
 
 Symbols are internalized from a single memory area common to all threads.
 

docs/basics/qsql.md

@@ -5,8 +5,6 @@ keywords: exec, delete, kdb+, q, query, select, sql, update, upsert
 ---
 # QSQL query templates
 
-
-
 <div markdown="1" class="typewriter">
 [delete](../ref/delete.md)  delete rows or columns from a table
 [exec](../ref/exec.md)    return columns from a table, possibly with new columns
@@ -17,9 +15,6 @@ keywords: exec, delete, kdb+, q, query, select, sql, update, upsert
 The query templates of qSQL share a query syntax that varies from the [syntax of q](syntax.md) and closely resembles [conventional SQL](https://www.w3schools.com/sql/).
 For many use cases involving ordered data it is significantly more expressive.
 
-:fontawesome-brands-wikipedia-w:
-[Structured Query Language](https://en.wikipedia.org/wiki/SQL "Wikipedia")
-
 
 ## Template syntax
 

docs/basics/syscmds.md

@@ -342,10 +342,10 @@ Executing [`.Q.gc[]`](../ref/dotq.md#qgc-garbage-collect) additionally attempts
 Since V3.3 2015.08.23 (Linux only) unused pages in the heap are dropped from RSS during `.Q.gc[]`.
 
 When q is denied additional address space from the OS, it invokes `.Q.gc[]` and retries the request to the OS. 
-Should that fail, it will exit with `'wsfull`.
+If the subsequent attempt fail, the request exits with [`'wsfull`](../basics/errors.md#wsfull).
 
-When secondary threads are configured and `.Q.gc[]` is invoked in the main thread it will automatically invoke `.Q.gc[]` in each secondary thread. 
-If the call is instigated in a secondary thread – i.e., not the main thread – it will affect that thread’s local heap only.
+When secondary threads are configured and `.Q.gc[]` is invoked in the main thread, `.Q.gc[]` is automatically invoked in each secondary thread. 
+If the call is instigated in a secondary thread, it affects that thread’s local heap only.
 
 !!! detail "Notes on the allocator"