HELP does not help

[igully]

Whenever you really want help and not an introductory guide (for which the current one is useful and needed), indeed HELP does not help.

I really don't know how internally does this HELP system work, but if it has the ability, it should link to already installed documentation.

For example I get this result:

C:\help attrib ERROR: requested chapter not found

Ideally, it should link to the ATTRIB.TXT which is already placed as C:\SvarDOS\DOC\ATTRIB\ATTRIB.TXT, and, of course display it with with some scrollable feature provided either internally or just by filtering it using TYPE with MORE.

It would be an ideal default procedure to make all commands attempt to match their actual help files.

[mateuszviste]

It is a good point that help is not very helpful. It is somewhat on purpose, although I am definitely not very happy about its current state. The thing is that I'd prefer to avoid documenting the commands themselves, as I think that the help of each command should be inside the command itself (eg. ATTRIB /?) and duplicating it will only be a maintenance burden and waste of space.

BTW the FreeDOS help is 1MB big nowadays - that is also something I'd very like to avoid ending up with in SvarDOS.

This is why I tried to make the help as generic/short as possible, so it contains very "high level" information only. The current state of the help is not a success though, but I do not know how or what could be changed or added to make it more "newbie-friendly".

The fallback-to-doc-file method you suggest seems rather unreliable, as we cannot expect files to be consistently present on disk. Moreover these files are not in the AMA/AMB format which would require AMB to handle text files, along with all the extra processing it requires (wrapping long lines, unexpected control characters, etc). It is also not compatible with the multi-language approach I am trying to maintain.

MS-DOS 5 has a nice approach: its help is just a list of available commands, and when asked for the details of a command the help system simply runs the command with a "/?" argument. Perhaps we could mimic this.

Currently the SvarDOS help command is a batch file that calls AMB to load the language-specific help file: http://svn.svardos.org/filedetails.php?repname=SvarDOS&path=%2Fhelp%2Fhelp.bat

Perhaps this batch file could detect that what is called is a DOS command (attrib, copy, dir, etc) and in such case execute this command with "/?" ?

[boeckmann]

I think it would be awesome if every package could provide its own .AMB file. A help "wrapper" program could then open the specific .AMB. For example help fdisk would open the .AMB file provided by FDISK. Help without parameters would open some general .AMB file. That would keep the general .AMB file small while giving programs a standardized way to provide help files.

[mateuszviste]

I think it would be awesome if every package could provide its own .AMB file. A help "wrapper" program could then open the specific .AMB. For example help fdisk would open the .AMB file provided by FDISK. Help without parameters would open some general .AMB file. That would keep the general .AMB file small while giving programs a standardized way to provide help files.

It might be a worthy extension, yes. So the "HELP" batch file could follow such logic:

1. if no argument (HELP) - open the general SvarDOS "user guide"
2. if argument (HELP ATTRIB or so), do first that matches:
   • load file %DOSDIR%\HELP\%LANG%\ATTRIB.AMB if it exists
   • load file %DOSDIR%\HELP\EN\ATTRIB.AMB if it exists
   • execute ATTRIB /? if such command exists in %PATH%

[igully]

MS-DOS 5 has a nice approach: its help is just a list of available commands, and when asked for the details of a command the help system simply runs the command with a "/?" argument. Perhaps we could mimic this.

I know a thing or two about the burden of creating and maintaining a help system within a commercial OS (not even counting the toll of keeping up with localization!).

The MS-DOS 5 approach in this subject, seems simplistic but quite efficient considering the objectives of SvarDOS.

I took the liberty of doing something about it. Do as you please with it. It contains all current both internal and external commands that SvarDOS has. Care has been taken that lines never exceed 80 characters in length when it comes to a command description. I hope it somehow helps (pun intended!):

---

For more information on a specific command. type the command's name followed by the /? argument, like for example: DIR /?

AMB Ancient Machine Book book reader for .AMB files (External Command). ATTRIB Displays or changes file attributes (External Command). BREAK Sets or clears extended CTRL+C checking (Internal Command). CALL Calls a batch file from within another batch file (Internal Command). CD/CHDIR Displays name or changes the current directory (Internal Command). CHCP Displays or sets the active code page number (Internal Command). CHKDSK Checks a disk and displays a status report (External Command). CHOICE Presents a choice to the user and waits for a key (External Command). CLS Clears the screen (Internal Command). COPY Copies one or more files to another location DATE Displays or sets the system date (Internal Command). DEBUG Tool that aids developers in inspecting code (External Command). DEL/ERASE Deletes one or more files (Internal Command). DELTREE Deletes directories with all their contents (External Command). DIR ListS files and subdirectories in a directory (Internal Command). DISKCOPY Copies the contents of one floppy disk to another (External Command). DISPLAY Driver for codepage management (External Command). ECHO Displays messages, or toggles command-echoing (Internal Command). EXIT Quits the command.com program (command interpreter) FC Compares files and displays its differences (External Command). FDAPM Controls and reports on energy/power (External Command). FDISK Prepares a hard drive for use with SvarDOS (External Command). FIND Searches for a text string inside files (External Command). FOR Runs a specified command for each listed element (Internal Command). FORMAT Formats a disk to use with SvarDOS (External Command). GOTO Directs batch processing to a labelled line (Internal Command). HELP Displays the help page you are reading right now (External Command). HIMEMX XMS memory manager (External Command). IDLEDPMS Energy-saving screensaver (External Command). IF Performs conditional processing in batch programs (Internal Command). KEYB Sets the keyboard layout (External Command). LABEL Modifies the volume label of a disk (External Command). LN Manipulates global executable links (Internal Command). LOCALCFG Locale preferences configuration tool (External Command). MD/MKDIR Creates a directory (Internal Command). MEM Displays memory information (External Command). MODE Configures system devices (External Command). MORE Displays console output one screen at a time (External Command). MOVE Moves files from one location to another (External Command). PATH Displays or sets search path for executable files (Internal Command). PAUSE Suspends processing of a batch program (Internal Command). PKG Package manager to handle package deployment (External Command). PKGNET Pulls packages from the online SvarDOS repository (External Command). PROMPT Changes the DOS command prompt RD/RMDIR Removes (deletes) a directory (Internal Command). REM Records comments (remarks) in a batch file (Internal Command). REN/RENAME Renames one or more files or directories (Internal Command). SET Displays, sets or removes environment variables (Internal Command). SHCDX86 8086 CD-ROM extender replacement (External Command). SHIFT Changes the position of arguments in a batch file (Internal Command). SHSUCDX Unloadable CD-ROM extender for SvarDOS (External Command). SORT Sorts the contents of its input (External Command). SVED Default SvarDOS text editor (External Command). SYS Transfers system files to another drive (External Command). TIME Displays or sets the system time (Internal Command). TREE Displays the directory structure of its argument (External Command). TRUENAME Returns a fully qualified path or filename (Internal Command). TYPE Displays the contents of a text file (Internal Command). VER Displays the DOS kernel and shell versions (Internal Command). VERIFY Verifies that files are written correctly (Internal Command). VOL Displays the disk volume label and serial number (Internal Command).`

[igully]

Help file in text format available here: https://www.transfernow.net/dl/20240117aCemQ6uP

[mateuszviste]

It is nice, but did you see that the Help already has something similar? http://svardos.org/phpamb.php?fname=help/help-en&f=commands.ama

Your list appear to be more complete, though. Could you integrate your work with what is already in the help? That would be very helpful. :)

The file to rework would be exactly this one: http://svn.svardos.org/filedetails.php?repname=SvarDOS&path=%2Fhelp%2Fhelp-en%2Fcommands.ama

[igully]

It is nice, but did you see that the Help already has something similar? http://svardos.org/phpamb.php?fname=help/help-en&f=commands.ama

Your list appear to be more complete, though. Could you integrate your work with what is already in the help? That would be very helpful. :)

The file to rework would be exactly this one: http://svn.svardos.org/filedetails.php?repname=SvarDOS&path=%2Fhelp%2Fhelp-en%2Fcommands.ama

I haven't come across that file when asking help inside SvarDOS as mentioned in my OP.

I will try to rework it as you suggest.

[mateuszviste]

I think you missed it because the SvarDOS system comes with an older version of the help at the moment. This list of command is in the "work in progress" version that is visible only on the website: http://svardos.org/phpamb.php?fname=help/help-en

I will try to rework it as you suggest.

Awesome :+1:

[igully]

Give it a test, it should be merged now: https://www.transfernow.net/dl/20240117lSDwRjI0/soA5qEzf

[bttrx]

Just an idea and probably worth a separate issue:

• This list of commands needs to be translated to other languages. I focus on the external commands here.
• Translation for pkg_desc_??.json (http://svn.svardos.org/listing.php?repname=SvarDOS&path=%2Fwebsite%2Frepo%2F&#a852addeddea8868d0b92dc0fa97d4ffa) is also still pending.
• Translated descriptions at http://www.svardos.org/?p=repo would also be nice.

So, maybe we can create a central place for translated descriptions for the 'core' packages? Then a script could pull in (or push out) translations to commands.ama and other places.

What do you think? Too complicated and 'copy & paste' would also do the job?

[bttrx]

Descriptions for internal commands could be pulled in from, e.g., svarcom/trunk/lang/de-utf8.txt:

# CLS
10.0:Löscht den Bildschirminhalt.

# CD / CHDIR
12.0:Zeigt den Namen des aktuellen Verzeichnisses an oder wechselt es.

That way, with the help of some scripting, content for commands.ama could be generated completely automatically.

[mateuszviste]

Give it a test, it should be merged now: https://www.transfernow.net/dl/20240117lSDwRjI0/soA5qEzf

Committed, thanks! I only changed line endings to "LF" as it should be and fixed a few very minor typos. http://svardos.org/phpamb.php?fname=help/help-en&f=commands.ama

Too complicated and 'copy & paste' would also do the job?

Indeed... Given the little amount of commands and the very low amount of changes in time, I expect that designing and maintaining the system you suggest would be much more time consuming than pasting a few strings by hand here and there :-D

There is still the item below left pending... Any takers? It's basically if.. then... BAT scripting. :)

So the "HELP" batch file could follow such logic:

1. if no argument (HELP) - open the general SvarDOS "user guide"
2. if argument (HELP ATTRIB or so), do first that matches:
* load file %DOSDIR%\HELP\%LANG%\ATTRIB.AMB if it exists
* load file %DOSDIR%\HELP\EN\ATTRIB.AMB if it exists
* execute ATTRIB /? if such command exists in %PATH%

[igully]

Give it a test, it should be merged now: https://www.transfernow.net/dl/20240117lSDwRjI0/soA5qEzf

Committed, thanks! I only changed line endings to "LF" as it should be and fixed a few very minor typos. http://svardos.org/phpamb.php?fname=help/help-en&f=commands.ama

There is one other typo that remains to be fixed: ..."DIR ListS files and subdirectories in a directory."...

Thanks!

[bttrx]

There is one other typo that remains to be fixed: ..."DIR ListS files and subdirectories in a directory."...

Fixed now.

@mateuszviste Thanks for doc/svn quickstart.txt, because I forgot all that svn or git stuff over the last month.

[bttrx]

A few notes:

VERIFY Verifies that files are written correctly.

Nope. It doesn't verify. It just reports or sets the DOS VERIFY flag.

AMB Ancient Machine Book book reader for .AMB files (used by HELP).

Do we really need it that long?

COMMAND SvarCOM Command-line interpreter.

Is this capital 'C' in 'Command-line' by intention?

FDISK Prepares a hard drive for use with SvarDOS. FORMAT Formats a disk to use with SvarDOS. SHSUCDX Unloadable CD-ROM extender for SvarDOS.

One might think these are special versions only for use with SvarDOS, which is not the case AFAIK.

I suggest to change these to:

FDISK Prepares a hard drive for use with DOS. FORMAT Formats a disk to use with DOS. SHSUCDX Unloadable CD-ROM extension.

[bttrx]

@mateuszviste

Given the little amount of commands and the very low amount of changes in time, I expect that designing and maintaining the system you suggest would be much more time consuming than pasting a few strings by hand here and there :-D

But I really love to throw big machines on little problems. ;-)

There is still the item below left pending... Any takers? It's basically if.. then... BAT scripting. :)

HERE! ME!

'if such command exists in %PATH%' doesn't mean any code for the BAT file?

[mateuszviste]

'if such command exists in %PATH%' doesn't mean any code for the BAT file?

Maybe this should be tested like "IF EXISTS %DOSDIR%\COMMAND.[EXE|COM] ..." althought I'm not sure it's the best approach as we would miss internal commands. On the other hand blindly executing COMMAND /? as a fallback is also not a very good idea as it is a risk of executing things that are not part of SvarDOS but do happen to be in the PATH, and potentially do not even understand "/?".

Another option would be hard-code the list of commands (internal or external) so the batch file knows when it is allowed to execute "COMMAND /?" as a fallback.

[bttrx]

Any comments on this?

A few notes:

VERIFY Verifies that files are written correctly.

Nope. It doesn't verify. It just reports or sets the DOS VERIFY flag.

AMB Ancient Machine Book book reader for .AMB files (used by HELP).

Do we really need it that long?

COMMAND SvarCOM Command-line interpreter.

Is this capital 'C' in 'Command-line' by intention?

FDISK Prepares a hard drive for use with SvarDOS. FORMAT Formats a disk to use with SvarDOS. SHSUCDX Unloadable CD-ROM extender for SvarDOS.

One might think these are special versions only for use with SvarDOS, which is not the case AFAIK.

I suggest to change these to:

FDISK Prepares a hard drive for use with DOS. FORMAT Formats a disk to use with DOS. SHSUCDX Unloadable CD-ROM extension.

[bttrx]

It might be a worthy extension, yes. So the "HELP" batch file could follow such logic:

1. if no argument (HELP) - open the general SvarDOS "user guide"
2. if argument (HELP ATTRIB or so), do first that matches:
   • load file %DOSDIR%\HELP\%LANG%\ATTRIB.AMB if it exists
   • load file %DOSDIR%\HELP\EN\ATTRIB.AMB if it exists
   • execute ATTRIB /? if such command exists in %PATH%

This logic breaks compatibility as early as step 2, as currently HELP ATTRIB tries to open a chapter named 'attrib' from the SvarDOS User Guide. On failure AMB writes ERROR: requested chapter not found to the screen.

[mateuszviste]

A few notes:

VERIFY Verifies that files are written correctly.

Nope. It doesn't verify. It just reports or sets the DOS VERIFY flag.

IIRC this is indeed just a flag that may or may not be checked by some storage drivers (usually ignored). MSDOS describes this also in an ambiguous way: "Tells MS-DOS whether to verify that your files are written correctly to a disk." (and their help is even more misleading). No idea what would be the best wording not to cause any confusion.

AMB Ancient Machine Book book reader for .AMB files (used by HELP).

Do we really need it that long?

I think it is important that it is clear this is required by HELP. The other bits might be shortened a little perhaps. Feel free to optimize whatever you feel is best. :)

COMMAND SvarCOM Command-line interpreter.

Is this capital 'C' in 'Command-line' by intention?

Seems to be a typo to me.

FDISK Prepares a hard drive for use with SvarDOS. FORMAT Formats a disk to use with SvarDOS. SHSUCDX Unloadable CD-ROM extender for SvarDOS.

One might think these are special versions only for use with SvarDOS, which is not the case AFAIK. I suggest to change these to:

FDISK Prepares a hard drive for use with DOS. FORMAT Formats a disk to use with DOS. SHSUCDX Unloadable CD-ROM extension.

Sound good for me.

1. if no argument (HELP) - open the general SvarDOS "user guide"
2. if argument (HELP ATTRIB or so), do first that matches:

• load file %DOSDIR%\HELP\%LANG%\ATTRIB.AMB if it exists
• load file %DOSDIR%\HELP\EN\ATTRIB.AMB if it exists
• execute ATTRIB /? if such command exists in %PATH%

This logic breaks compatibility as early as step 2, as currently HELP ATTRIB tries to open a chapter named 'attrib' from the SvarDOS User Guide. On failure AMB writes ERROR: requested chapter not found to the screen.

Yes, it would indeed be a change of the help behavior. But would it be a bad change? I think the current behavior of trying to locate a chapter in the user guide is pretty much useless. That being said I am not a big user of help systems, so my intuition may be very well wrong here.

[bttrx]

Anyway, here is a first implementation:

@ECHO OFF
REM :: NO PARAMS GIVEN?
IF "%1"=="" GOTO USERGUIDE

REM :: HELP ON HELP WANTED?
IF %1==/? GOTO HELPONHELP

REM :: UPCASE PARAM #1
SET OLDPATH=%PATH%
PATH %1
SET COMMAND=%PATH%
PATH %OLDPATH%
SET OLDPATH=

REM :: ANY SVARCOM INTERNAL COMMAND?
REM :: ALL UNDERSTAND THE /? SYNTAX
IF %COMMAND%==BREAK    GOTO RUNCOMMANDHELP
IF %COMMAND%==CALL     GOTO RUNCOMMANDHELP
IF %COMMAND%==CD       GOTO RUNCOMMANDHELP
IF %COMMAND%==CHDIR    GOTO RUNCOMMANDHELP
IF %COMMAND%==CHCP     GOTO RUNCOMMANDHELP
IF %COMMAND%==CLS      GOTO RUNCOMMANDHELP
IF %COMMAND%==COPY     GOTO RUNCOMMANDHELP
IF %COMMAND%==DATE     GOTO RUNCOMMANDHELP
IF %COMMAND%==DEL      GOTO RUNCOMMANDHELP
IF %COMMAND%==ERASE    GOTO RUNCOMMANDHELP
IF %COMMAND%==DIR      GOTO RUNCOMMANDHELP
IF %COMMAND%==ECHO     GOTO RUNCOMMANDHELP
IF %COMMAND%==EXIT     GOTO RUNCOMMANDHELP
IF %COMMAND%==FOR      GOTO RUNCOMMANDHELP
IF %COMMAND%==GOTO     GOTO RUNCOMMANDHELP
IF %COMMAND%==IF       GOTO RUNCOMMANDHELP
IF %COMMAND%==LN       GOTO RUNCOMMANDHELP
IF %COMMAND%==MD       GOTO RUNCOMMANDHELP
IF %COMMAND%==MKDIR    GOTO RUNCOMMANDHELP
IF %COMMAND%==PATH     GOTO RUNCOMMANDHELP
IF %COMMAND%==PAUSE    GOTO RUNCOMMANDHELP
IF %COMMAND%==PROMPT   GOTO RUNCOMMANDHELP
IF %COMMAND%==RD       GOTO RUNCOMMANDHELP
IF %COMMAND%==RMDIR    GOTO RUNCOMMANDHELP
IF %COMMAND%==REM      GOTO RUNCOMMANDHELP
IF %COMMAND%==REN      GOTO RUNCOMMANDHELP
IF %COMMAND%==RENAME   GOTO RUNCOMMANDHELP
IF %COMMAND%==SET      GOTO RUNCOMMANDHELP
IF %COMMAND%==SHIFT    GOTO RUNCOMMANDHELP
IF %COMMAND%==TIME     GOTO RUNCOMMANDHELP
IF %COMMAND%==TRUENAME GOTO RUNCOMMANDHELP
IF %COMMAND%==TYPE     GOTO RUNCOMMANDHELP
IF %COMMAND%==VER      GOTO RUNCOMMANDHELP
IF %COMMAND%==VERIFY   GOTO RUNCOMMANDHELP
IF %COMMAND%==VOL      GOTO RUNCOMMANDHELP

REM :: LOOKUP HELP FILE FOR ANY EXTERNAL COMMANDS
IF EXIST %DOSDIR%\HELP\EN\%COMMAND%.AMB SET AMBFILE=%DOSDIR%\HELP\EN\%COMMAND%
IF EXIST %DOSDIR%\HELP\%LANG%\%COMMAND%.AMB SET AMBFILE=%DOSDIR%\HELP\%LANG%\%COMMAND%
REM :: PARAM #2 BECOMES PARAM #1 TO SPECIFY CHAPTER NAME
IF NOT "%AMBFILE%"=="" SHIFT
IF NOT "%AMBFILE%"=="" GOTO RUNAMB

REM :: EXTERNAL (CORE) COMMAND PRESENT?
IF EXIST %DOSDIR%\%COMMAND%.COM GOTO RUNCOMMANDHELP
IF EXIST %DOSDIR%\%COMMAND%.EXE GOTO RUNCOMMANDHELP
IF EXIST %DOSDIR%\BIN\%COMMAND%.COM GOTO RUNCOMMANDHELP
IF EXIST %DOSDIR%\BIN\%COMMAND%.EXE GOTO RUNCOMMANDHELP

:USERGUIDE
REM :: LOOKUP HELP FILE FOR SVARDOS USER GUIDE
REM :: PARAM #1 SPECIFIES CHAPTER NAME
IF EXIST %DOSDIR%\HELP\HELP-EN.AMB SET AMBFILE=%DOSDIR%\HELP\HELP-EN
IF EXIST %DOSDIR%\HELP\HELP-%LANG%.AMB SET AMBFILE=%DOSDIR%\HELP\HELP-%LANG%
IF NOT "%AMBFILE%"=="" GOTO RUNAMB

ECHO SORRY! NO HELP AVAILABLE
GOTO DONE

:HELPONHELP
ECHO HELP [COMMAND] [CHAPTER]
GOTO DONE

:RUNCOMMANDHELP
%COMMAND% /?
GOTO DONE

:RUNAMB
AMB %AMBFILE%.AMB %1

:DONE
SET COMMAND=
SET AMBFILE=

Notes:

1. I decided against 'whitelisting' all SvarDOS' core external commands, because commit default location of core binaries changed from %DOSDIR%/BIN to %DOSDIR%/ has doubled the checks required for the core binaries.
2. This also allows the user to copy or install additional binaries to the SvarDOS binaries directory and to run help on them.
3. But it may lead to problems, if these additional binaries don't understand the /? option.
4. Help-on-help still needs some love, but I was to lazy for today. Maybe someone else wants to write it after understanding the logic of this script. ;-)
5. I used SVED to write this script and it worked without any problems. :-)

The discussion is hereby opened.

[mateuszviste]

Looks like a very good start! I would suggest that you commit it, as it is undoubtedly better than what we have now anyway.

Any reason to use both "REM" and "::" on comments? Both are equivalent I think.

[bttrx]

Looks like a very good start! I would suggest that you commit it, as it is undoubtedly better than what we have now anyway.

Ok. Will do so over the day.

Any reason to use both "REM" and "::" on comments? Both are equivalent I think.

Yes, REM and :: are (nearly) equivalent, but I'm using :: for visual highlighting only. If it causes confusion to others, I could change it to ;; or ## or ...

[boeckmann]

Nice, now we need .AMB manuals :-)

[bttrx]

I guess, you are in charge now, because it was you, who requested this extension. :-D

[mateuszviste]

Ok. Will do so over the day.

I slightly edited the batch file so the goto labels are shorter (tried to use names that are still readable). the batch went from 3K to 2.5K. I hope it's fine. I wonder if there is an elegant way to shorten the long list of "IF %COMMAND%==.... GOTO ...." Maybe a for loop?

I like your trick for upcasing the %1 string. Did you came up with it yourself? I've never seen this before.

[bttrx]

I slightly edited the batch file so the goto labels are shorter (tried to use names that are still readable). the batch went from 3K to 2.5K. I hope it's fine.

I'm fine with that.

I wonder if there is an elegant way to shorten the long list of "IF %COMMAND%==.... GOTO ...." Maybe a for loop?

I had the same idea, but didn't try. You know better, how FOR was implemented and what its limitations are.

I like your trick for upcasing the %1 string. Did you came up with it yourself? I've never seen this before.

This trick is around 30 years old and was used many times at those days. :-)

[mateuszviste]

New help is part of the current build, hence I'm closing this issue.