Using the Help in Version 30

[Jay Sage]

Since I could not find the proper arguments to open some of the local help targets, I decided I would have my 'favorites' script use the web help. I made note of the URLs that opened, and I now see the that name of the .htm file is exactly what is needed to open the desired local help page. So, the way to get them is to go to jpsoft.com/help, navigate to the desired page, and grab the name of the .htm file (without the extension or the prefix URL).

Thanks, everyone, for the help with this.

 

[Jay Sage]

I have now written my script (tchelp.btm) for quickly accessing my favorite help topics. I list them in a file with lines that look like this:

functionnames Functions by Name

The help keyword comes first (for coding convenience). Descriptions are aligned in a column farther right. There are blank lines for readability in the selection window. The whole thing can be seen below as it currently stands. It is very easy and quick to update.

That text file is read into an array variable using the EXECARRAY function call shown below. The environment variable %HelpChoices is set to the name of the file. The one-dimensional array variable "choices" is defined earlier with the proper size based on the number of lines in the file (stored in environment variable %lines).

%@execarray[choices,type %HelpChoices]

The choices are now displayed in a popup window using the SELECTARRAY function with the selection returned in a variable.

set choice=%@selectarray[choices,2,3,%@eval[1+%lines],75]

If a non-blank line was selected, the first word of the line is used as an argument for the HELP command (which I include as *help because I end up aliasing HELP to my script).

If the script is invoked with an argument, that argument is passed to the HELP command; otherwise the selection window is popped up.

Next, I defined an alias "help" that invokes the script (alias help=batrun tchelp). I have so many aliases that invoke scripts that I have an alias called "batrun" that handles the calling (alias batrun=call c:\commands\bat\%@name[%1].btm %2$).

Finally, I defined an auto-execute keyboard alias. I first tried defining F1, but then I lost the ability to press F1 after typing a command on the command line, so I used Alt-F1.

alias @@Alt-F1=^ehelp

(The leading caret-e represents the ESC key to clear the command line. Otherwise, the text "help" just gets added to the command line. If there were a character to force the cursor to the beginning of the line, then the alias could have that character followed by "help^s" instead, which would insert "help" and a space in front of the text already on the command line.

Here's what I see when I execute HELP with no argument.

 

[Joe Caverly]

Well done @Jay Sage

This is a sample of what I have been using for the last couple of years;

@setlocal
@echo off

OPTION //ConsolePopupWindows=Yes

::Gosub FavList > %temp\myfav.txt
Gosub FavList > clip9:

::*set results=%@select[%temp\myfav.txt,1,1,20,80,Select a Help item from the list]
*set results=%@select[clip9:,1,1,20,80,Select a Help item from the list]
iff defined SELECT_LINE then
  set HelpArg=%@word[-0,%results]
  *help %HelpArg
endiff

OPTION //ConsolePopupWindows=No

endlocal
quit

:FavList
text
Internal Variables Listed by Category variablecats
Variable Functions Listed by Category functioncats
endtext
Return

Joe

 

[Jay Sage]

Thanks, Joe. I'll study your code later when I have more time.

I had forgotten about the negative argument option of the @word function to work from the right. That would allow me to place the choices at the beginning of the line and the help keywords at the end, as you did, with equally simple code.

I also really like the way you get the data into the array right in the batch file. I'm not sure that I don't prefer to keep it in a separate file, but it is a terrific technique that really makes nice use of the clipboard facility. I had not realized that a clipboard could be used in the @select function.

A lot of my existing batch files create temporary files (as the old version of yours did), which I work hard to clean up at the end of the code. However, I don't always succeed because of unexpected exits, and I find the files littering my drive. It's not a huge problem -- they are tiny files -- but it annoys me and frustrates my desire for neatness. I'm hoping to convert that old code to use arrays, clipboards, and memory buffers instead.

 

[vefatica]

Here's one (TOPIC.BTM, far below) that presents its menu in an alternate screen buffer (console or WindowsTerminal).

It requires only one keypress. Skip the menu altogether by specifying an index on the command line. Note that this BTM reads data from itself, so the position of the comment is crucial.

comment
Functions by Category;functioncats
Variables by Category;variablecats
Commands by Category;commandcategories
Conditional Expressions;ConditionalExpressions
Regular Expression Syntax;regularexpressionsyntax
Initialization Directives;Directives
Aliases;Aliases
Array Variables;Array_Variables
ANSI Reference;ansiref
endcomment

setlocal
on break goto done1

setarray /f title[9] helparg[9]

do i=0 to 8
    set line=%@line[%0,%@inc[%i]]
    set title[%i]=%@word[";",0,%line]
    set helparg[%i]=%@word[";",1,%line]
enddo

if %# GE 1 (if %1 GE 0 .and. %1 LE 8 ( HELP %helparg[%1] & goto done2 ))

set oldbuf=%@consoleb[-1]
set newbuf=%@consoleb[0]

do i=0 to 8
    echo ^t%i  %title[%i]
enddo

inkey /k"012345678[Esc]" ^r^nPress 0-8 to select a topic, Esc to quit %%key
if "%key" != "^e" HELP %helparg[%key]

:done1
set junk=%@consoleb[%oldbuf]
set junk=%@fileclose[%newbuf]
:done2
unsetarray title helparg

 

[Jay Sage]

Well, I paid the $50 to upgrade from version 27 to 30 even though I had not noticed any new features that I thought I really needed. It has been worth it just for the fun I've been having and the education!!

And I suspect that I will actually find the clipboard facility to be quite useful.

 

[rconn]

I can also launch the TCC 30 help, from the TCC 30 command line, into my browser (Microsoft Edge).

For example;

http://127.0.0.1:8000/903740DE-8B73-4B83-A01B-4D1EA7BB26F8/variablecats.htm

http://127.0.0.1:8000/903740DE-8B73-4B83-A01B-4D1EA7BB26F8/functioncats.htm

It'd be a lot simpler to use the web help.