QL Software
SBBox & Style Guide
===================
SBBox V0.04
===========
Requirements:
-------------
This program requires Qlib_run V3.36+ or equivalent. It also uses an up to
date version of JMS'es Scrap Thing that comes with Qmenu.
QD is desirable, but SBBox may work with other editors, including PC-side
ones, or with the aid of intermediate utilities such as Knoware's StuffScrap.
Usage:
------
To create a typical procedure box, in your editor type the title, a brief
description, and a more detailed description, each on a line of their own:
Title
Brief description
Detailed description
Example, using QD:
..................
PeekF
Peek a float
Returns the 6b fp value at address adr
Note: Does not filter out "illegal" values
DEFine FuNction PeekF(adr)
RETurn PEEK_L(adr + 2) * 2 ^ (PEEK_W(adr) - $81F)
END DEFine PeekF
:
:
Mark the five description lines [<F7> at PeekF and <F8> after "values"] and copy
them to Scrap [<F4> <O>]. You could now delete the marked block [<F4> <D>]. Press
the SBBox Hotkey (see below) and then append the Scrap contents just above the
code to end up with:
rem + ------------------------------------------------------------------------ +
rem |< PeekF >|
rem + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +
rem | Peek a float |
rem | |
rem | Returns the 6b fp value at address adr |
rem | |
rem | Note: Does not filter out "illegal" values |
rem + ------------------------------------------------------------------------ +
rem | V0.01, pjw, 2023 Sep 19 |
rem + ------------------------------------------------------------------------ +
:
DEFine FuNction PeekF(adr)
RETurn PEEK_L(adr + 2) * 2 ^ (PEEK_W(adr) - $81F)
END DEFine PeekF
:
:
The detailed description could cover a number of lines. Dont worry about
line length as the utility will wrap lines within the box.
A blank line on its own comes out as a blank Box line.
To continue text on a fresh line, precede the text with a # (Note: No
space, unles you want an extra space.)
#This line starts on a new line.
To draw a box line, put one of the special characters on a line of its
own, eg:
-
comes out as
+ ------------------------------------------------------------------------ +
The special characters are -=+* They can all be used for drawing a line of
their own kind.
These characters (plus #) may also be used to change the box style:
Type the box surround character you want as the first character of the
title:
=New Group
Brief description
etc
*New Section
etc
#New Section with data
etc
When satisfied, mark the block of text and put it into the Scrap (as the
only item! ie [<F4> <O> not <F4> <A>]) Press your chosen Hotkey, and then
paste the result where you want it. Finally, delete the raw text block.
The author's initials must be given on the command line. For example, if
youre setting SBBox up on a Hotkey, you could do worse than:
ERT HOT_RES1("~", '<path>SSBox_obj'; 'me', 'SBBox')
Style Guide
===========
A style guide is suggested for continuation of any of my projects, in case
one wishes to update and improve them over time. I havent followed my own
style guide to the letter in all cases; its just a suggestion after all.
The utility, SBBox, is included to aid the homogeneity of the format.
Each procedure (= procedure/function) has a header of the following format
(76 chars wide + rem ):
+ ------------------------------------------------------------------------ +
|< Procedure Name >|
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +
| Brief description of procedure (centred) |
| |
| Detailed description (if necessary) |
| |
| Reads GLOBal <- list of global variables required by procedure |
| Sets GLOBal <- list of global variables altered by procedure |
| Returns: <- What function returns |
+ ------------------------------------------------------------------------ +
| V0.01, pjw, 2018 Mar 30 |
+ ------------------------------------------------------------------------ +
: ^ ^ ^ ^ <- two line spacing between equal procedures
: | | | | (only one between dependent subroutines
| | | | (which may not even need separate headers))
| | | |
| | | Highlight of changes made since previous
| | Date
| Author initials
Version number
There can be more than one version line.
If there is a history file, more detailed description can be entered there.
The changes field can use more than one line
Not all versions need be listed here, only first, last, and any versions
where the author differs from the previous version.
Not all elements in the sample above are "mandatory". The point is to give
NECESSARY information to later authors who may wish or need to work on
the code.
Group Headers:
: <- Additional lines to indicate new group
+ ======================================================================== +
|< Group Header >|
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +
| Brief summary of grouped procedures (centred) |
| |
| More detailed description of group |
| List of GLOBal variables associated with, or affected by group |
| Common features, eg all return the same category result, etc.. |
+ ------------------------------------------------------------------------ +
| V0.01, pjw, 2018 Feb 05++ <- Version information, if appropriate |
+ ======================================================================== +
:
:
Section Headers:
: <- Additional lines to indicate new section
+ ************************************************************************ +
|< Section Title >|
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +
| Section description |
| Any notes to next author |
+ ------------------------------------------------------------------------ +
| V01.01.03, pjw, 2018 Mar 30, Optional version number (except first sect) |
+ ************************************************************************ +
:
:
: <- Additional lines to indicate new section
: <- Additional lines to indicate new section
+ ######################################################################## +
#< Section with data Title >#
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +
# Section description #
# Any notes to next author #
+ ------------------------------------------------------------------------ +
# V0.01.01, pjw, 2018 Mar 30, Optional version number (except first sect) #
+ ######################################################################## +
:
Data and variables initialised outside any procedure.
(For this to work, the final program instruction must be to start the
program. I have used the convention of calling this module Main. This is so
all variables will be initialised before the program executes.)
:
:
The rest is up to individual authors; spacing, tabs, remarks
A note on Version Numbers
-------------------------
During active development things change so rapidly and widely it is
hard to keep account of version numbers. Not every change in a lowly
subroutine will perculate up to a new section or overall version
increment. What happens in practise is that version numbers change when I
am satisfied with ALL changes made at the lower levels of an issue being
worked on.
Once the source code is relatively stable and "out there", however, this
approach needs to be applied more rigorously to avoid confusing those who
come after. Anywhere that changes have been made need to be noted in the
version number. When all changes have been made to the developer's
satisfaction, an increment to the section's version number should be made,
and when the code leaves the hands of the developer, the overall version
number too must be incremented.
In this context a change may also mean reverting to a previous version of
a routine: The restored routine's version number will be less than the one
it replaces, but the section and overall version numbers must be
incremented!
Software status
===============
Style Guide:
V01.01, pjw, 2018 Apr 05
SBBox:
V0.04, pjw, 2018 Apr 18
Conditions and DISCLAIMER as per Knoware.no
Generated by QuickHTM, 2023 Sep 19
QL Software