Declined User-created extended help (probably in a text file): DIRHISTORY /?x

[Rick Reinckens]

If a user follows /? with an x (for "extended"), after displaying the built-in help the display will pause (equivalent to /p) and then display user-created help.

In the OPTION dialog the user can specify where extended help files are located.

User-created help files must have a standard format (most likely ASCII text, maybe Unicode).

User-created helps filenames must match the command name and begin or end with a standard indicator, e.g., DIRHISTORY-xhlp.txt An "indicator" is necessary to prevent problems of the command name being a reserved word.

 

[Charles Dye]

Or make it a command instead, e.g. xh dirhistory That way (1) you can implement it yourself, as a batch file/external/plugin; (2) it would work with older versions; and (3) you can also add help text for things other than internal commands: batches/externals/plugins....

 

[Rick Reinckens]

Possibly both. My idea is that people probably would routinely just add the x after the question mark.

I don't quite follow how a separate command would work. If it's a new command it wouldn't work with older versions.

One of the things I was thinking after I wrote the suggestion was many people would want colors, bolding, etc. Since various free Word-compatible software is available, maybe have it automatically look for a variety of endings (and that approach would make more sense as a separate command).

So xh dirhistory will look in the \Ext-Help\ folder for and display dirhistory.txt, if it doesn't find that look for dirhistory.doc*, if not that dirhistory.htm*, then dirhistory.pdf

For a separate command it would probably be good to be able to list in an ini file the viewer and path for each extension. People might want to use a different viewer than the default program for that extension or be able to set that xh dirhistory will open \Ext-Help\dirhistory.doc* in read-only mode.

 

[Rick Reinckens]

I guess that actually brings up several questions:

1) Why have to add an x, i.e., dirhistory /?x Why not just add that to the current help processing code.

2) Alternatively, set it in OPTION whether /? will automatically display the user-created help too or whether the user has to use /?x to show that.

3) Have /?x show the normal /? help and then activate the separate command suggestion. That would probably be easiest to implement.

 

[Charles Dye]

Or how about /?? instead of /?x
Would be easier to type....

 

[Rick Reinckens]

Or how about /?? instead of /?x
Would be easier to type....

True.

 

[Rick Reinckens]

Just "bringing this back to mind." Especially the xh command and being able to set the programs and sequence to use for finding the viewer file. Also, be able to set THE folder where the SET of user-created helps will be, since you might want it on a network--especially with TCC-RT on a server farm.

 

[w_krieger]

I've been playing around with this sort of stuff since the days of doshelp.hlp and 4help. My computer readme file and the various cdrom root files were variations on 4help.

For example, trying to integrate the variety of loaded plugin-help files into a single source (like in OS/2) or Winhelp4, where one could fiddle the contents page, In doshelp.hlp, for example, you have to put all of the commands in alphabetical order, but with a few string-hacks, you could use a different text-file.

Typing something like /?a etc, is something like selecting 'help about', or help on option a (eg dir /?o would give help in dir /o options), is what some programs use. Also something like reg add /? (for help on reg add function).

What would be nice is for someone to port the freedos help reader to windows, and people could make their own help systems.

 

[Joe Caverly]

If something similar to a manual page is desired, console help could be created using a PowerShell .ps1 file.

For example, the help for _doy could be created like this;

<#

.SYNOPSIS
A variable that returns the current day of the year (1 to 366)

.DESCRIPTION
A variable that returns the current day of the year (1 to 366)

.EXAMPLE
If the current date is August 25, 2019;

echo %_doy
237

.NOTES
See also @doy

.LINK
https://jpsoft.com/help/_doy.htm

#>

...create an alias;

alias tcch=`pshell /s "get-help .\%1.ps1 %2"`

...call it;

e:\utils>tcch _doy

NAME
    E:\Utils\_doy.ps1

SYNOPSIS
    A variable that returns the current day of the year (1 to 366)


SYNTAX
    E:\Utils\_doy.ps1 [<CommonParameters>]


DESCRIPTION
    A variable that returns the current day of the year (1 to 366)


RELATED LINKS
    https://jpsoft.com/help/_doy.htm

REMARKS
    To see the examples, type: "get-help E:\Utils\_doy.ps1 -examples".
    For more information, type: "get-help E:\Utils\_doy.ps1 -detailed".
    For technical information, type: "get-help E:\Utils\_doy.ps1 -full".
    For online help, type: "get-help E:\Utils\_doy.ps1 -online"

Now see an example of how to use _doy;

e:\utils>tcch _doy -examples

NAME
    E:\Utils\_doy.ps1

SYNOPSIS
    A variable that returns the current day of the year (1 to 366)


    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>If the current date is August 25, 2019;

    echo _doy
    237

As this is all text-based, a plain text editor is all that you need to create the page.

Just a suggestion.

Joe

 

[Joe Caverly]

Here's the help for @doy as a console manual page (@doy.ps1);

<#

.SYNOPSIS
A function that returns the current day of the year (1 to 366)

.DESCRIPTION
@DOY[date[,format]] : Returns the day of year (1 - 366) for the specified date. See date formats for information on acceptable date formats.

@DOY accepts an optional second parameter specifying the date format:

0 default 
1 USA (mm/dd/yy) 
2 Europe (dd/mm/yy) 
3 Japan (yy/mm/dd) 
4 ISO (yyyy-mm-dd) 
5 ISO 8601 yyyy-Www-d 
6 ISO 8601 yyyy-ddd 

.EXAMPLE
echo %@doy[02-02-2010]
33

.EXAMPLE
echo %@doy[%_date]
127

.NOTES
See also _doy

.LINK
https://jpsoft.com/help/f_doy.htm

#>

Proof;

e:\utils>tcch @doy

NAME
    E:\Utils\@doy.ps1

SYNOPSIS
    A function that returns the current day of the year (1 to 366)


SYNTAX
    E:\Utils\@doy.ps1 [<CommonParameters>]


DESCRIPTION
    @DOY[date[,format]] : Returns the day of year (1 - 366) for the specified date. See date formats for information on
    acceptable date formats.

    @DOY accepts an optional second parameter specifying the date format:

    0 default
    1 USA (mm/dd/yy)
    2 Europe (dd/mm/yy)
    3 Japan (yy/mm/dd)
    4 ISO (yyyy-mm-dd)
    5 ISO 8601 yyyy-Www-d
    6 ISO 8601 yyyy-ddd


RELATED LINKS
    https://jpsoft.com/help/f_doy.htm

REMARKS
    To see the examples, type: "get-help E:\Utils\@doy.ps1 -examples".
    For more information, type: "get-help E:\Utils\@doy.ps1 -detailed".
    For technical information, type: "get-help E:\Utils\@doy.ps1 -full".
    For online help, type: "get-help E:\Utils\@doy.ps1 -online"

Note also that if you do;

e:\utils>tcch @doy -online

...you will be taken to the online site for the help page.

Joe

 

[Rick Reinckens]

As I've mentioned before, the problem with all "roll-your-own" approaches is they're not standard, they don't come with dialogs, TCC Help, etc. The xh separate command approach seems the easiest to implement

So xh dirhistory will look in the \Ext-Help\ folder for and display dirhistory.txt, if it doesn't find that look for dirhistory.doc*, if not that dirhistory.htm*, then dirhistory.pdf

For a separate command it would probably be good to be able to list in an ini file the viewer and path for each extension.

I think that needs to be clarified to "for each supported extension", i.e., each extension the xh command will try to process.

Also, in the ini file the setup should be able to override the default location for the \Ext-Help\ folder, so one could be set on a network or a separate data drive or partition, e.g., it's okay to have non-tech folks add their own Word document to a network folder but you wouldn't want them messing with a subfolder under C:\ProgramData or C:\Program Files.