From 7997182cc0748ce449e29460b0534aed8013b6e8 Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Fri, 18 Sep 2020 10:34:32 +0100
Subject: [PATCH] Improve the framebuffer docs a bit

---
 docs/quick-start.md         |  2 ++
 docs/user-interface.md      |  2 +-
 docs/using-framebuffer.md   | 58 ++++++++++++++++++++++++++++++++++---
 frontends/framebuffer/gui.c |  2 +-
 4 files changed, 58 insertions(+), 6 deletions(-)

diff --git a/docs/quick-start.md b/docs/quick-start.md
index 652c3e3c1..449b956a3 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -84,6 +84,8 @@ To build the framebuffer front end, you could do:
       $ make TARGET=framebuffer
       $ ./nsfb
 
+More detailed documentation on using the [framebuffer](docs/using-framebuffer.md)
+  frontend are available.
 
 Cross Compiling
 ===============
diff --git a/docs/user-interface.md b/docs/user-interface.md
index 36b0103a9..49ca7a1ed 100644
--- a/docs/user-interface.md
+++ b/docs/user-interface.md
@@ -31,7 +31,7 @@ Frontend specific to the Haiku OS
 
 ## framebuffer
 
-There is a basic user guide for the[framebuffer](docs/using-framebuffer.md)
+There is a basic user guide for the [framebuffer](docs/using-framebuffer.md)
 
 ## gtk
 
diff --git a/docs/using-framebuffer.md b/docs/using-framebuffer.md
index 3af8f983f..98a100a1f 100644
--- a/docs/using-framebuffer.md
+++ b/docs/using-framebuffer.md
@@ -62,6 +62,56 @@ Overview
    the GTK frontend is a vastly superior choice. The framebuffer
    frontend will appear exceptionally limited on such capable systems.
 
+Running
+=======
+
+  The framebuffer frontend is executed with the nsfb command. This
+   command takes parameters to control the operation of the
+   browser. The 'Configuring' section describes the available options
+   in detail.
+
+  The selection of the display surface is controlled with the -f
+   switch, the available display surfaces can be shown by passing '?'
+   as the parameter.
+
+    $ ./nsfb -f ?
+    ./nsfb: Valid surface names are:
+    ./nsfb: ram
+    ./nsfb: sdl
+    ./nsfb: x
+    ./nsfb: vnc
+    ./nsfb: wld
+
+  The avilable surfaces are dependant on what was compiled into the
+   nsfb library.
+
+  Common issues
+  -------------
+
+  - The browser appears to "hang" with no output
+
+    This is often cause by the unintentianal selection of the debug
+     "ram" surface. In this case the browser is in fact operating but
+     the output is being rendered to a memory buffer. the solution is
+     to explictly select the intended surface using the -f switch
+
+  - The displayed browser interface has no visible icons
+
+    This is generally because the necessary resources are not availale
+     on the resource search path.
+
+  - There is no displayed text.
+
+    The font configuration is incorrect either it has been compiled
+      wrongly or the configured freetype font is not available
+
+  - The browser messages are "bad"
+
+    If the browser messages are being emited as unrecognisable short
+     text symbols or in the wrong language it is likely the Messages
+     file could not be located. This can be confirmed by looking for
+     the text "Message translations failed to load" in the verbose log
+     output (run the browser with the -v switch)
 
 Configuring
 ===========
@@ -72,11 +122,11 @@ Configuring
    for details.
 
   As with any NetSurf frontend run-time configuration is read from a
-   "Choices" file. This file is a simple key:value list and is located
-   in "${HOME}/.netsurf/Choices".
+   "Choices" file. This file is a simple key:value list and by default
+   is located in "${HOME}/.netsurf/Choices".
 
-  The standard values supported by the NetSurf core are documented in
-   the Options document. In addition to these there are a number of
+  The standard [core user options](docs/netsurf-options.md) are
+   available. In addition to the core options there are a number of
    values to control specific aspects of the framebuffer version.
 
   Toolkit Options
diff --git a/frontends/framebuffer/gui.c b/frontends/framebuffer/gui.c
index d7f22726f..934ba05c8 100644
--- a/frontends/framebuffer/gui.c
+++ b/frontends/framebuffer/gui.c
@@ -525,7 +525,7 @@ process_cmdline(int argc, char** argv)
 
 		default:
 			fprintf(stderr,
-				"Usage: %s [-f frontend] [-b bpp] url\n",
+				"Usage: %s [-f frontend] [-b bpp] [-w width] [-h height] <url>\n",
 				argv[0]);
 			return false;
 		}