Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[bruceuncle]

This is a bit of a mouthful but stick with it as it will enable some major benefits for AMOS Pro Help when we get to enhancements.  Hungry Horace asked a while back if it would be possible to include help files for extension libraries...

I came across this fixing a minor bug in the editor.  The bug is that the Ask Editor instruction only has 11 calls defined for it (despite what Editor_Commands.doc says!).  There are actually 13 available.  So I opened it up to enable:

• AEdAsk_Token (12)
• AEdAsk_Config (13)

The last one is undocumented anyway, so I made its name up.  Testing them out, AEdAsk_Config works fine (it just returns the address where the config file starts).  But AEdAsk_Token refused to work.  Which is probably why they cut off at 11 instructions, a quick fix.  So, as usual, I investigated further and found that all it lacks is to put the string parameter (the line of text to be tokenised) into AMOS's general-purpose text buffer - Buffer(a5).

So I developed this little AMOS program (well it was before I added the comments) to test that out and blow me down, it works!  The point being, that if the Help Files are mapped using tokens, it gets rid of the intensive text searching that's currently in use.  Extension tokens can be easily identified.  So we can get both the slot number and token.  I've documented how in the sample code below.  And as we know the Extension Slot Number, a simple naming convention of <ExtensionName> + ".map" and ".txt" would work fine.  Eg.  "AMOSPro_Music.Lib" would have help files called "AMOSPro_Music.map" and "AMOSPro_Music.txt".  For the help file hyperlinks links to menus and info topics, there's the whole range of tokens below $FF37 available, I think 16,000+ should be enough. 

As I've got the help and tokens for all "standard" libraries databased, there's no problem making the switch.

To use the code below, you'll need to replace the existing AMOSPro_Editor with the one in the attached zip.  This is identical to the standard release version with just the Ask Editor instruction limit upped to 13.  (I can't release the one with the other fixes in yet until I've got an installer written as changes are needed to its config file and it gets too complicated.  It's not completed yet anyway...)

Then load any program you like and put your cursor on an instruction.  Load the program below as an accessory and run it.  Press any key to exit.  I haven't used the equates for Ask Editor in the code as you won't have them in your equates file.  (Another thing to add to the release files.  When will it ever end?!    )

Code: [Select]

'===========================================================================
'   Author: bruceuncle
'     Date: 10/06/2015
'
'   MUST be used as an accessory
'
'   Tokenise current line in the editor using the current cursor position as
'   the starting point for the text.
'   Results in a tokenised line of code as if just that text had been entered.
'   The 1st word in the result can be discarded as it will be out of context
'   with the actual line of code if the starting position is not at the 
'   beginning of a line.
'
'   So this can replace the text-intensive scanning that the existing help
'   system uses:
'
'     Step 1 - Get the tokenised code.
'     Step 2 - Exclude "punctuation" tokens (anything from $FF37 thru $008C).
'     Step 3 - Get the first "real" token and check for Tk_Ext ($004E) to see
'              if it's an extension library token.
'     Step 4 - If it's not an extension, job done, use extension 0 and go
'              to Step 6. 
'     Step 5 - If it is an extension, get the extension's number and its
'              internal token number.
'     Step 6 - Use the extension number to select the appropriate help files.
'     Step 7 - Look up the help text using a new-format "*.map" file and the
'              token number.  This can now be a binary search against an
'              ordered list of token numbers for each library instead of the
'              current linear text search.
'
'   The new-format "*.map" file is an array of fixed-size records:
'   
'      (0) Word - Token Number.
'      (2) Word - Help Text Length.
'      (4) Long - Help Text starting offset in "*.txt" file.
'
'   The benefits are that extension libraries can participate in help
'   simply by supplying appropriate "*.map" and "*.txt" files.
'
'   Menu and info links can use any token below $FF37.
'
Set Accessory

'   Offset to Buffer(a5)
Global GC_BUFFER
GC_BUFFER=$4F2

Screen Open 1,640,256,16,Hires
Wait Vbl
Screen 1

'   Ask for the current line
Ask Editor 1
G_LINE$=Param$

'   Ask for the current cursor position in the line
Ask Editor 3
G_CURS_X=Param

'   Derive the text from current cursor position onwards
G_TEXT$=Mid$(G_LINE$,G_CURS_X)

'   Get the address of Buffer(a5)
G_BUFFER_ADDR=Leek(Areg(5)+GC_BUFFER)

'   Poke the text into the buffer
Poke$ G_BUFFER_ADDR,G_TEXT$
Poke G_BUFFER_ADDR+Len(G_TEXT$),0
'   Ask for the address of the tokenised result
Ask Editor 12
G_ADDR=Param

'  Display the results
Print
Print "Original line complete  : ";G_LINE$
Print "Cursor position in line : ";G_CURS_X
Print "Text at cursor          : ";G_TEXT$
'
' Offset  Type           Description   
' ======  ====           ===========
'  (0)    Unsigned Byte  Length of tokenised line in WORDS. 
'  (1)    Unsigned Byte  Starting position of line (encodes leading spaces).
'  (2)    Signed Word    1st Token, if it's $004E, it's an extension library
'                        token. 
'  (4)    Word           Next token, token data or, if 1st token was $004E
'                        next byte is Extension Slot Number.   
'  (6)    Word           Next token, token data or, if 1st token was $004E
'                        this word is that Extension's Token.   
' 
'  And so on until end of text
'

Print "First 8 words of tokenised line:"
Print Mid$(Hex$(Peek(G_ADDR),2),2);" ";
Print Mid$(Hex$(Peek(G_ADDR+1),2),2);" ";
For I=2 To 15 Step 2
   Print Mid$(Hex$(Deek(G_ADDR+I),4),2);" ";
Next I
Print
Wait Key
Screen Close 1


[Hungry Horace]

so if i get this right.... this is an accessory that basically gives a 'new' help function, that operates from token-ised commands, and utilising the extensions?  Sounds great!

What's to stop this being fully incorporated into the beta Amos 2.1 editor as a replacement for the current help function?
How do i go about producing an AMCAF help file?

I assume it checks the name of the extension from the currently loaded extensions list?  (thus negating any problem of extensions sharing the same slot)

[Lonewolf10]

How do i go about producing an AMCAF help file?

All you need (based on what bruceuncle said above) is a map file (format documented below, taken from his program listing above) and a .txt file containing the actual help text.

Code: [Select]

'   The new-format "*.map" file is an array of fixed-size records:
'   
'      (0) Word - Token Number.
'      (2) Word - Help Text Length.
'      (4) Long - Help Text starting offset in "*.txt" file.

I don't see any issues, unless a specific piece of help text exceeds 65,535 characters... but I think that is going to be highly unlikely

Amazing work, bruceuncles

[Hungry Horace]

Sounds brill - I am pretty adept at VBA coding, so I could probably convert the HTML version of the AMCAF manual into this format fairly easily.

I will just need to look at a couple of example .txt entries to "program" the layout right.

[bruceuncle]

Sounds brill - I am pretty adept at VBA coding, so I could probably convert the HTML version of the AMCAF manual into this format fairly easily.

I will just need to look at a couple of example .txt entries to "program" the layout right.

I don't see any issues, unless a specific piece of help text exceeds 65,535 characters... but I think that is going to be highly unlikely

Sorry to take a while to reply.  Life's been getting in the way a bit - see here.

Great to see some "buy in" on this project guys.  It can feel pretty lonely out here sometimes .

Realistically, this cannot be a part of V2.10 as any extra work there will just delay it further, and it's taking too long already.  But yes, it would be fairly straightforward to graft it in later.  Especially if you guys can get a working model ready.

These are some points to take note of, as it's not quite as straightforward as it might first appear:

• I think it might get a bit confusing for newbies if the current Help Main Menu started listing hyperlinks to help for the "standard libraries".  I would prefer that it remains pretty much as is.  So Extension Slots 1 thru 7 would remain "invisible" to the Help system users.  All other slots would be added dynamically as hyperlinks at the bottom of that menu depending on what extensions are loaded.  See the notes below on the attachment to this post for more info on how to determine that.  This is something that needs a lot of design thought before it's finalised.  What to do with a missing "standard library", etc.
• The reason I got excited about this method is due to the way that the AMOS Tokenise() function works.  AMOS builds alphabetic indexes for each loaded library.  These mean that it doesn't have to do a text search through the token tables for each loaded library.  It just grabs the first letter of the text it has to tokenise and uses it to get all the tokens for each library that match that letter.  This is a lot faster and supercharged compared to the current help *.map file search.  The tokens in each index only exist for the first token matching the text - the one in the token table with the actual token text.  See attached draft PDF for why this is...  Point being, Tokenise() will only ever come up with one Token Number for each instruction.  Confused?  Read the PDF.
• You'll need to check out the help for the AMOS Compiler Shell as it is integrated to a different AMOS Pro Help program (even though they have the same name!).  Shouldn't present much of a problem, just one more program to review and change.
• You'll need some kind of data storage to keep track of it all.  I'm using Access 2010 and VBA.  You could probably get away with using just about any version of Excel from 2000 onwards to store the work.  I just prefer databases as it's a lot easier to keep track of the relationships.  For example, I have tables of the help text and the libraries and their tokens, all related.  So it will be a very simple matter to assign tokens to the help text instead of the current text keys.  Don't underestimate how confusing it can all become without some organised storage.   
• AMOS Hypertext will take any numeric hyperlink key as a line number.  So the Token Numbers will need some prefix.  I'll have to check, but I don't see why we can't just prefix with "$".  Which would make sense when they get returned to the help program as keys (ready made hex numbers).
• AMOS Pro Token Numbers are signed 16-bit.  Which would muck up binary searching the *.map files if used as is.  Rather than extend them to signed 32-bit, just treat the negative Token Numbers as unsigned and stick 'em at the end.
• The ranges of negative Token Numbers that we can use for menu and info hyperlinks need to be defined up front.  There's 197 of them so far for AMOSPro.Lib plus the "standard" libraries.  I suggest we start at $8000 for AMOSPro.Lib (slot #0) and increment by $0400 for each slot #:
  
  • Slot# 00  $8000 thru $83FF  AMOSPro.Lib
  • Slot# 01  $8400 thru $87FF  AMOSPro_Music.Lib
  • Slot# 02  $8800 thru $8BFF  AMOSPro_Compact.Lib
  • Slot# 03  $8C00 thru $8FFF  AMOSPro_Request.Lib
  • Slot# 04  $9000 thru $93FF  AMOSPro_3D.lib
  • Slot# 05  $9400 thru $97FF  AMOSPro_Compiler.Lib
  • Slot# 06  $9800 thru $9BFF  AMOSPro_IOPorts.Lib
  • Slot# 07  $9C00 thru $9FFF  Extension Library #7
  • Slot# 08  $A000 thru $A3FF  Extension Library #8
  • and so on
  • Slot# 25  $E400 thru $E7FF  Extension Library #25
  • Slot# 26  $E800 thru $EBFF  Extension Library #26
  That gives 1,024 for each library, which is more than enough.
• We could do with an editor for AMOS Help actually written as an AMOS accessory.  But you probably don't want to think about that just yet...  It would be a lot easier to get a direct result rather than having to go though VBA.  One of the hardest bits I had to program was word-wrapping VBA RTF format (actually a cut-down HTML) to AMOS Help format.  Complete with the chroma-coding.  For my purposes, it was a lot easier to write stuff in an RTF format textbox and convert later as the RTF will be used for a manual.  Which is how the whole thing started.
• The editor I use is pretty heavily dependant on Access 2010 features.  But the VBA code should be backward compatible to Office 2000.  The main problem would be that it expects its data to come from an Access database.  So I'll have to dig around for what may be of use to you.  Things like the word wrapper and exporter would be pretty essential.
• MadAngus and I determined a pretty rigid format for the help text a long while back.  I'll have to dig that out too.  The rigid format was necessary for it to convert to a reference manual - the original plan.  I've taken that to the next step where it should do for both manual and help formats with some changes to drop menus from the manual.

I could waffle on for pages on the subject but I'll wait until I get some requests. 

However, you will need the ability to:

• Convert text to a token
• Get the APSystem directory path
• Get the Extension Library file names

So, while I had the editor on the operating table, I added to the Ask Editor commands;

Ask Editor 12,,ProgramText

Now works as per the docs.  You supply the ProgramText as a parameter rather that pokeing it into a buffer.

Ask Editor 14,SysMessageNumber

A new function that gets a "message" from the interpreter config file.  These are actually stored at SysMessages(a5) so no file access is involved.

There's a couple of demo Accessory programs supplied in the attachment which show how to use them.

There's also a PDF of a work-in-progress on the AMOS Pro File format destined for the CSI AMOS thread.  It explains more than I could do in this post.  It's to be completed when I've got my head around more of the Verify process.  But there should be enough there to guide you in what you're looking at doing.  And just ask anyway. 

[Hungry Horace]

I code access databases for about 65% of my working days... Do you wanna post yours here and we can all use the same one?
Perhaps FOL could even host an SQL database on the site and the database could use that as its source and we could all be saving to the same one via the Access front end?


There's a lot to take in with that post and I will need to re read it later!

[bruceuncle]

I code access databases for about 65% of my working days...

Hey!  Another Access programmer.  I thought we were as rare as AMOS programmers.    I've known lots of people who "use" Access but few who actually program it.

I use the typical code database front end and data database back end.  The code database uses a class framework (as far as that's possible with VBA).  The tools are a setup utility (ensures correct version alignment and connection between front and back ends) a configurable code generator (point it at any table and get a very pedantic class).  There's also a user manager (not needed here) and data dictionary for schema output (very useful).

The data and code should be usable outside of Access 2010.  Not so sure for the editor forms as I made liberal use of conditional formatting for some controls.  Anyway, we'll find out.

The most suitable source for initially populating it for AMCAF looks like the AMCAF.guide file in the original distribution.  It's already a well defined markup format, so I'm loading from that.  That gives us the menus and "see also" links straight away.  The tricky bit is forming the menu hierarchy.  It was the same problem for the original AMOS help files.  I've got a separate app I used for that so I'll nick the classes and queries from that and modify to suit.  But I remember it as a mostly manual query and update process.  The menu hierarchy isn't that important for AMOS help but essential for outputting a ref manual - think of it as a contents page.  And trying to edit it without something resembling a tree view is a bit of a nightmare.

Don't know how much I can get done before I go A.W.O.L. in July, but I'll try and get something to you before then if possible.

By the way, currently looking at the AMOS File selector bugs.  So the infamous Hungry Horace parent directory bug may soon get attention.  The reason for looking at it whilst in the midst of the editor is getting the editor to scroll from a mouse wheel, which requires two new editor command functions in the editor config.  There's spare slots, so not too taxing.  Otherwise, getting the file selector to scroll from a mouse wheel was an easy DBL fix.

And my personal gripe with the file selector is that I want to be able to define my "work" directory in the Interpreter config accessory rather than have it always pop into APSytem/ when it's first used.  There's a spare slot #15 in the Set Interpreter / System File Names editor...

[Mia]

The reason for looking at it whilst in the midst of the editor is getting the editor to scroll from a mouse wheel, which requires two new editor command functions in the editor config.  There's spare slots, so not too taxing.  Otherwise, getting the file selector to scroll from a mouse wheel was an easy DBL fix.

hey, I just got the scroll wheel working in the editor by recording a macro - yeh

Editor >> Macros >> Enter A New Macro

then scroll up

then press shift and the up key

then the mouse left

same for scroll down.

magic.

I was modifying +Edit.s and I had a hunchthis was possible.

I the code I traced:
 cmp.b #$4C,d1     Fleche vers le HAUT
   beq   Esc_H
   cmp.b #$7A,d1     Fleche vers le HAUT
   beq   Esc_H
   cmp.b #$4D,d1     Fleche vers le BAS
   beq   Esc_B
   cmp.b #$7B,d1     Fleche vers le BAS
   beq   Esc_B

This makes the Direct Mode up and down with the scroll mouse. but finding tracing Ed_FCall, Ed_Ky2Fonc, Ed_KFonc in the +Edit.s got me a bit lost - then I thought about the macros - so no need to add this to the editor. woohoo

You say you have done this for the File Requester - I know this is in +W.s but I can't find any edits - would be great to get the file selector working as well...

[bruceuncle]

Ah, where do I start? 

First, my recovery from the back op last year has stalled a fair bit since I weaned myself off the heavy-duty painkillers (opiates! yum! but also why they had to go ).  I still can't spend much time sitting so I haven't been all that productive over the last few months.  Things are improving, but progress is glacial...  So my posts and output are a bit limited.

However, enough of my whining and back to the interesting bits.

hey, I just got the scroll wheel working in the editor by recording a macro - yeh

I must admit I never thought of that as a quick fix.

The editor uses two tables in its config file to control all keystrokes and their functionality.  These start at .Ed_AutoLoad (the functions table) and .Ed_KFonc (the keystrokes table).  These are loaded into the offsets at Ed_AutoLoad(a5) and Ed_KFonc(a5) when the editor starts.  In +Edit.s, they match to the jump table at JFonc and the parallel flags table at FlagFonc. The tables, and all the strings in the editor config file, are editable using an AMOS Accessory program - have a look at Editor_Config.AMOS for how.  I won't go into great detail here, but you will need to understand how the key instruction works:

Call Editor FunctionNumber, StringArrayNumber, NewStringValue

FunctionNumber points to entries in the JFonc and FlagFonc tables in +Edit.s.  The JFonc table entry contains the branch, the FlagFonc table entry contains flags to show what actions are allowed:

Bit 0: Refresh the Editor Buffer after function
Bit 1: Refresh the Current Line after function
Bit 2: Function is forbidden for a Closed Procedure
Bit 5: Function can be used within a Macro
Bit 6: Send a Command Line (in use but can't see it does anything)
Bit 7: Function can be called using "Call Editor"

FunctionNumber = 182 uses the branch to EdZ_NewConfig to do all the work changing the editor config file contents.  It should only be used from an AMOS Accessory program.  It does the work in memory (the loaded image of the config file) then forces a save and editor restart when accessory program is closed.

StringArrayNumber determines which set of config strings to change.  There are five sets:

1	System File Names	+Edit.s .Sys1 thru .Sys2:
2	Menu Messages	+Edit.s .Mn1 thru .Mn2 (from "Editor_Menus.Asc")
3	Dialog Messages	+Edit.s Ed1 thru Ed2
4	Test-Time Messages	+Edit.s .Test1 thru Test2
5	Run-Time Messages	+Edit.s .Error1 thru .Error2

NewStringValue this is where it gets a bit tricky!  The format is:

dc.l	MessageNumber
dc.b	Replacement string

If you need to change any of the strings in the config file, the only sane way is to call this function as the editor's code takes care of all the necessary shuffling up or down to make room for a new string.  Note that calls to this function can only be made from an AMOS Accessory program.  This is because, after any calls to the function, a flag is set which forces the editor to save the config file and do a restart (using the new config file it just saved).

Okay, so that's fine for the strings, how are those keystroke tables edited?  Answer, you have to make the changes in situ in the tables pointed to by Ed_AutoLoad(a5) and Ed_KFonc(a5).  Then force the editor to save the config changes and do a restart when you close the AMOS Accessory from which you're making the changes.  This is done by using any value for StringArrayNumber that is greater than 5.  When it encounters this situation, the string modification code is bypassed and just the flags set to force a config file save and the editor's restart.

So, in Editor_Config.AMOS you'll see some Pokes and Dokes followed by the enigmatic instruction:

Call Editor 182,100,"Null!"

This has a StringArrayNumber of 100 (definitely greater than 5!) so it just forces the save and restart.  Any number greater than 5 will do, and the "Null!" is completely irrelevant as any other string would do (and will be completely ignored).  The original authors obviously decided to use something consistent to do the job  .

That's the editor and what you'd need to change to incorporate the scancodes for a mouse wheel (122 = wheel forwards, 123 = wheel backwards).

You say you have done this for the File Requester - I know this is in +W.s but I can't find any edits - would be great to get the file selector working as well...

Almost all of the screen handling and all of the requester handling is done using DBL (Dialogue Box Language) code hidden away in Resource Banks.  This code is a bugger to read and edit, so I wrote a DBL editor a long while ago to make it easier to edit and document.  The thread is here.  It's slightly buggy but does the job.  Read the thread for more info.  The zip file includes a *.guide which is essential reading before using!!!

For the File Requester and Text Reader, the programs are in the AMOSPro_Default_Resource.Abk bank.  You need to know that if you use your own Resource Bank, AMOS will substitute from that default resource bank for whichever groups you've left out.  Eg.  If your bank has no images, AMOS will automatically use the images from the default bank.  Same for the DBL programs and the message strings.  This is very useful as you don't need to design your own graphics (assuming the default ones will do) to maintain the AMOS Pro "look and feel" for your own requesters.

I've attached a zip of the DBL code and message strings from AMOSPro_Default_Resource.Abk.  My text editor (CodeWright on the PC side) allows me to set up syntax highlighting for just about any language, so I've included PDFs of the "pretty coloured" code which might be easier to follow 

[Mia]

glad to hear you are recovering, I didn't realize you couldn't actually sit - that must be frustrating in it's own right. i'm sure your strength will recover now, those pain killers will hold you back so good on you for moving on... And thank you for supporting my learning even while you are in that difficult situation.

yeh the quick macro fix came to me while staring at the code - but it isn't enough as it doesn't work in the accessories, it doesn't do the scrollbar as such, but it is good to use for now.

and wow, that post is just amazing - thanks for all the info, I will read again carefully - this is right where I'm at with the code and I think you just saved me at least a months work.

yes the DBL is a little beast of it's own - I was looking at the AMOSPro_Calc recently as it seems to use it really cleanly - thinking of applying DBL in what I'm doing I'll check out your tool as well.

and I'll keep learning as I'm not quite in a state of walking! (Pas en etat de marche!)