_    ____ _    ___       _   _
|    ||  \|    |  \    O |   |
|    ||  ||    |__/_ _ _ |  _|
|----||  ||    |  \| | | | / |
|_  _||__/|___||__/\_/_|_|_\_/__By_Martin_Bazley__Release_2__________________

This text is best viewed at a wrapwidth of 77 columns.
For interactive contents, do a 'List of Found' search for '==='.

_____________________________________________________________________________

=== 1 == Introduction ==

Where to start?  This program has its roots years and years ago, when I
decided, for no particular reason other than that I was nine years old and a
bit weird, to list the entire contents of my hard disc, by hand.  So I
created a file called 'HardDscLst' and set to work.  I actually got as far
as 'Manuals' (the RISC OS 3.7 User Guide supplied with all RiscPCs) before
becoming disillusioned, and eventually, about a year later, deleting all my
hard work...

...to replace it with a better version.  Having just discovered the joys of
HTML, I resolved to restart the disc listing project and colour-code all the
entries - that system is the one the automated program (i.e. this one) uses.
Unfortunately, this had the result of making the process take even longer,
and this time I didn't even get beyond !Boot.

A cold, nasty-tasting dose of sanity was administered by my big brother
Chris (of Star Fighter 3000 fame) - why not write a program to do it instead?
Thus he introduced me to the wonderful world of OS_GBPB which eventually
blossomed into a BASIC program called, funnily, 'HDLBuild', the core of
which was written by Chris but which had a load of frills attached by me,
such as the option to produce either formatted or unformatted output.  The
last version of this was eventually attached to Release 2 of the Oddities
Collection, and was made available, via Chris's website, to the general
public.  Whether anyone actually used it or not, I never found out!

Unfortunately it was slow and single-tasking.  Therefore, I resolved (again)
to write a Wimp version, and I got as far as designing the sprites, then
dabbled in AppBasic, then forgot about it altogether.  However, having
finally figured out drag'n'drop technique, I'm proud to announce the latest
in a long line of useless programs.  Why not run it and see what it does?

_____________________________________________________________________________

=== 2 == Quick guide ==

Double-click on the !HDLBuild icon (that pretty white thing with what looks
vaguely like a pencil in the middle).  A save box will come up (or it does
on my computer, anyway) from which you can drag an icon to a directory.  A
file called whatever you called it will appear there, and a progress window
will come up, listing the contents of that directory.

_____________________________________________________________________________

=== 3 == Slightly slower guide ==

The first thing HDLBuild does is to ask you, all in one, where you want to
store the list and what directory you want to list (i.e. you could specify
the root directory to list the entire hard disc, or !Boot to just list the
contents of the !Boot directory).

Basically, the directory you save the list to is the one it lists.  If you
don't want the list to interfere with the numbers, I recommend you call it
'zzzzzzz' or something similar at that end of the ASCII table, ensuring it
gets listed last.  Note: Whatever your sort options are (from the
Filer 'display' menu) the contents will always be listed in alphabetical
order - that's the way the SWI works.

You can also choose whether to save as HTML or textual output.  HTML takes
up more space and takes longer to display, but is prettier and colour-codes
the entries.

_____________________________________________________________________________

=== 4 == The progress window ==

My main incentive for writing this version of HDLBuild is mainly centred
around this very window.  It's multi-tasking.  The old one completely took
over your system for ten minutes or so.

The field across the top shows the number of the current file - this is
essentially nesting information, and will get written to the file.  The
field below this, to the left, shows the current filename and is blank if
the directory is empty.  The field to the right shows the filetype, and is
blank if the current item is a directory or the current directory is blank.

The three buttons at the bottom can be clicked on.  The first - 'Abort' -
does exactly what you'd expect it to - it ceases writing the file and packs
up and shuts down.

The second is marked 'Slower'.  This slows the display down to a readable
pace, giving you a better idea of what the program is doing at the moment.
If you click on this, the text changes to 'Faster', which, when clicked on,
restores the speed to normal.

The third is marked 'Pause'.  This will slow matters down to a complete and
absolute stop.  Clicking the 'Continue' button which appears in its place
will make the program resume where it left off.

_____________________________________________________________________________

=== 5 == To do==

   Make the directory to be listed independent of the save box.
   When using either HTML or text icons with transparency in them, toggling
    the save box 'HTML' button doesn't redraw the icon properly.  As far as
    I can tell, this is an OS bug...

_____________________________________________________________________________

=== 6 == Version history ==

=== Release 1 == 6th September 2008 ==

   First version.

=== Release 2 == 26th September 2008 ==

   Should hopefully now produce slightly more valid HTML.
   As a side effect, aborted files are now properly terminated.
   Fixed misfeature where the 'Slower' display could be sped up by wiggling
    the mouse very fast.
   Shouldn't cause problems on negative centisecond timers any more - but
    who leaves their computer on for six weeks at a time anyway?
   Added interactive help.
   Reshuffled the pollwords and delay routines to cope with it.
   Increased maximum length of the numbering and filename icons.
   Securely blanked the contents of the progress window before opening. :-)

_____________________________________________________________________________

=== 7 == The boring bits ==

=== 7.1 == Thanks and credits ==

Naturally enough, thanks to Chris for the base of this program - even though
not much of it survives intact.  Also thanks to Harriet for debugging, and to
Martyn Fox for some of the Wimp shell.

Thanks to me for everything else!

=== 7.2 == Legal stuff ==

HDLBuild is completely free software.  You may distribute, hack, improve,
copy and otherwise mutilate it in any way you please, but do NOT release
anything incorporating any part of this program (except the parts that
weren't written by me!) without giving me any credit and/or without my
permission.

You use this program at your own risk, and I will not accept liabilities for
any damage resulting from use/misuse of this program.  If you're going to
burn HDLBuild to CD and then poke yourself in the eye with it, that's your
problem, not mine.

If you're going to review or mirror this program, I'd appreciate knowing
about it!  (Especially if you're going to give it a good review. :-) )

=== 7.3 == Contact ==

If anyone, by accident, does find this program useful, please tell me.  I
can be reached at:

 mailto:martin@bazleyfamily.co.uk

And:

 Martin Bazley
 Flat 8
 349 North End Road
 Fulham
 London
 SW6 1NN
 ENGLAND

I am now living at home full-time, and am free to answer you when I like.
Please ignore any information to the contrary I may have inscribed in
earlier programs.

=== 7.4 == And finally... ==

My former deviantART pages are at http://swirlythingy.deviantart.com .
They are no longer updated, but you can still see some pretty impressive
computer-generated images and, latterly, photographs.  Not worth viewing
with anything other than Firefox.

Christopher's website is at http://www.starfighter.acornarcade.com/mysite :

Items by him include ScreenGrabber (screenshot-taking module), BSP (front-
 end for the Doom BSP nodes builder) and Grab II (save current ROM, RAM or
 tool sprites to disc).
Items by Harriet include Textseek (locate ASCII text in multiple files),
 Switch (freestanding version of Director's manipulate-open-windows facility)
 and Wimpdrain (allows you to close any files that may have been left open).
Items by me include a load of high-quality Doom levels, XmasTime (a utility
 to count down the time until next Christmas) and Cogs (a rather fun little
 program to draw Spirograph patterns).

Thanks for downloading HDLBuild!

_____________________________________________________________________________
Martin Bazley
26th September 2008

=== End