English ZX Next Guide

docs/Manual_en.adoc

@@ -25,7 +25,7 @@ This program is not a replacement for the incoportaded Browser, nor offers any o
 
 === Download
 
-A ZIP file with the latest version is available following https://github.com/kounch/vscode_zx/releases/latest[this link]
+A ZIP file with the latest version is available following https://github.com/kounch/knloader/releases/latest[this link]
 
 === Software Requirements
 

docs/knloader.gde

@@ -0,0 +1,213 @@
+@title knloader Manual
+@author kounch
+@version 1.0
+@copyright Copyright (C)2020 kounch
+@date 2020/05/31
+
+@index INDEX
+
+@-------------------------------------------------------------------------------
+@node MAIN
+@next COPYRIGHT
+
+@{c}knloader Manual
+
+@{c}Version 0.1
+
+@{h1}
+
+Description
+
+Do you have a ZX Spectrum Next, but you are tired to remember which is the best
+option to launch your programs? knloader to the rescue!
+
+This a set of NextBASIC programs which you can configure to remember, and then
+use, your preferred way to launch other programs (Next/+3e Mode, 128K mode,
+USR 0, etc.). As a bonus, you can put some images (like cassette covers or
+loading screens).
+
+This program is not a replacement for the incoportaded Browser, nor offers any
+other function than to launch other programs.
+
+Below are the hyperlinks found on this node (called "MAIN" as you can see
+in the bottom-right corner).  You can click on these links with the mouse
+or navigate them with the keyboard.  @{i}Right Arrow@{ui} cycles forward
+through the links and @{i}Left Arrow@{ui} cycles backwards.  Pressing @{i}ENTER@{ui}
+will activate that link. To get back to the previous link, press @{i}B@{ui}.
+
+ @{" Copyright " LINK COPYRIGHT}
+ @{" Requirements " LINK REQUIREMENTS}
+ @{" Installation " LINK INSTALLATION}
+ @{" Use " LINK USE}
+
+Use the @{i}Up@{ui} and @{i}Down@{ui} arrows to scroll, @{i}SPACE@{ui} to page
+down and @{i}DELETE@{ui} to page up.
+
+@-------------------------------------------------------------------------------
+@node INDEX
+@{r}knloader Manual
+@{c}@{h1}Index
+
+ @{" Requirements " LINK REQUIREMENTS}
+ @{" Installation " LINK INSTALLATION}
+ @{" Use " LINK USE}
+ @{" Database Format " LINK DATABASE}
+ @{" Notes " LINK NOTES}
+ @{" Copyright " LINK COPYRIGHT}
+
+@-------------------------------------------------------------------------------
+@node COPYRIGHT
+@next REQUIREMENTS
+@prev MAIN
+@toc MAIN
+@{r}knloader Manual
+@{c}@{h1}Copyright
+
+@{c}@{b}@{i}Copyright (c) 2020 kounch@{ui}@{ub}
+
+Some of the code used to launch programs has been adapted from the official
+NextZXOS distribution (especifically from browser.cfg, tapload.bas and
+tzxload.bas).
+
+Spectrum Next and System/Next are (c) SpecNext Ltd.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE
+
+@-------------------------------------------------------------------------------
+@node REQUIREMENTS
+@next INSTALLATION
+@prev COPYRIGHT
+@toc MAIN
+@{r}knloader Manual
+@{c}@{h1}Requirements
+
+@{i}Download@{ui}
+
+A ZIP file with the latest version is available on this link:
+
+https://github.com/kounch/knlauncher/releases/latest
+
+
+@{i}Software Requirements@{ui}
+
+NextZXOS (version 1.3.2)*. Docs, downloads, etc. here:
+
+https://www.specnext.com/latestdistro/
+
+@-------------------------------------------------------------------------------
+@node INSTALLATION
+@next USE
+@prev REQUIREMENTS
+@toc MAIN
+@{r}knloader Manual
+@{c}@{h1}Installation
+
+Create knloader.bdt file (see below for more instructions).
+
+Copy knloader.bas, knlauncher and knloader.bdt to your SD card.
+
+@-------------------------------------------------------------------------------
+@node USE
+@next DATABASE
+@prev INSTALLATION
+@toc MAIN
+@{r}knloader Manual
+@{c}@{h1}Use
+
+Use the browser or command line to navigate to the folder where knloader.bas,
+knlauncher and knloader.bdt are. Load "knloader.bas".
+
+On first run, cache files will be created from the data inside database file
+knloader.bdt. This has to be done only once, or after any changes are made to
+the database file.
+
+The main interface shows a list of the programs found in the database file.
+
+You can use the cursor keys or a joystick (Kempston or MD) to move and select
+the program that you want to load. Then, press @{b}ENTER@{b}, @{b}0@{ub} or the joystick button
+to launch.
+
+After a brief period of time, the program should load using the desired mode.
+
+If you have made a change to the database file, press @{b}R@{ub} to rebuild the cache.
+
+Press @{b}C@{ub} or the joystick secondary button (in MD mode) to hide/show images.
+
+Press @{b}X@{ub} to exit the program.
+
+Press @{b}H@{ub} to show some help.
+
+@-------------------------------------------------------------------------------
+@node DATABASE
+@next NOTES
+@prev USE
+@toc MAIN
+@{r}knloader Manual
+@{c}@{h1}Database file format
+
+The main database is stored in a text file (ANSI encoding).
+
+The first line must be the base path where to start looking for programs
+(for example: /games). It's length cannot exceed 128 characters.
+
+Starting from line 2, each line must have the following format:
+
+Program Name,Loading Mode,<Directory>,File,<Image File>
+
+@{b}Program Name@{ub}: Name to show in the interface (maximum 22 characters)
+
+@{b}Loading Mode@{ub}: A number indicating how to load the program file. Must be
+one of these:
+
+    0  - 3DOS
+    1  - TAP
+    2  - TZX (fast)
+    3  - DSK (AUTOBOOT)
+    4  - TAP (USR 0)
+    5  - TZX (USR0 - Fast)
+    6  - TAP (Next)
+    7  - TZX (Next - Fast)
+    8  - DSK (Custom Boot)
+    9  - TAP (PI Audio)
+    10 - TZX
+    11 - TAP (USR 0 - PI Audio)
+    12 - TZX (USR 0)
+    13 - TAP (PI Audio - Next)
+    14 - TZX (Next)
+    15 - NEX
+    16 - Snapshot
+
+@{b}Directory@{ub}: Subdirectory where file (optionally) and image file are
+located (maximum 64 characters)
+
+@{b}File@{ub}: Name of the file to execute (maximum 64 characters)
+
+@{b}Image File@{ub}: (Optional) Name (maximum 64 characters) of a full screen
+image file to show behind the program listing. It can be in SCR, SLR, SHC, SL2
+or BMP format.
+
+@-------------------------------------------------------------------------------
+@node NOTES
+@next MAIN
+@prev DATABASE
+@toc MAIN
+@{r}knloader Manual
+@{c}@{h1}Notes
+
+This program creates a preferences file named opts.tmp inside the same folder
+where knloader.bas is installed.
+
+It also creates a variable number of cache files insidde /tmp/knloader. This is
+necessary to speed up the program execution and overcome RAM limitations for
+large database files. However, if the database file is not changed, these will
+become read only on all subsequent executions.