Various issues with the HELP command

Unlisted commands

The HELP command makes no mentioning of the following commands (I think I've listed them all). I think they should be included in the list, which would make them discoverable by the user just by looking at the output of HELP /ALL.

• ATTRIB
• AUTOTYPE
• BOOT
• CHOICE
• COMMAND
• CONFIG
• COUNTRY
• IMGMOUNT
• KEYB
• LOADFIX
• LOADROM
• LS
• MEM
• MIXER
• MOUNT
• RESCAN
• SERIAL
• SUBST

Inconsistent behaviour

It also works inconsistently; this is the output of HELP CALL:

Which is different to the output of CALL /?:

For other commands, HELP <cmd> and <cmd> /?displays the exact same text:

I think there should be no difference between HELP <cmd> and <cmd> /? for any of the commands.

Important commands are not listed

This is the output of the HELP command:

The choice of commands included in this short list is questionable. Without specifying the /ALL flag, I think the most useful commands should be listed, e.g. MIXER, MOUNT and IMGMOUNT should be included, and perhaps CONFIG and RESCAN too.

Whereas the current list includes commands such as IF, GOTO, SET, SHIFT, REM, CHOICE, PAUSE — I'd say these shouldn't be in the basic list but only in the full list, as most users will never write batch files, but would most definitely want to use the MIXER or MOUNT commands.

This seems to effectively be a duplicate of #1660

Perhaps we should continue discussion there?

This seems to effectively be a duplicate of #1660

Perhaps we should continue discussion there?

Well, there's overlap between the two tickets but there's extra info in both tickets not present in the other. I think we can keep them separate for now?

I'm specifically referring to "Important commands are not listed" and the list of unlisted commands in my ticket; that's not present in the other ticket.

Big YES. The output of this help command is ancient and obviously was never discussed but is just a relic of its time.

Batch file commands are of no use for basic users and shouldn't be shown using help without parameters. This just buries the important commands which are VERY important for using DOSBox at a basic level.

Also DOSBox documentation inconsistencies are my pet peeve. They confuse new users, look amateurish and don't feel modern at all. Documentation shouldn't be A here and B there, it should all be written in one or two places and referenced/linked so there is as little duplicate documentation as possible. Sorry for the rant.

So, I'm thinking of having a crack at refactoring (at least some of) the help system this afternoon/weekend. From what I'm gathering, the behaviour should be something like:

help

Display the most common commands, ideally on one screen, and not necessarily the ones that currently show.

help /all

Should show help for all commands/programs, including those which are currently omitted. Should this be categorised at all into shell commands and other commands?

help cmd
cmd /?

Should both show the same help output.

Any other thoughts?

Great, agree with the above list of things to do! 🚀

Should this be categorised at all into shell commands and other commands?

I think we should always think from the perspective of a regular end user when it comes to interface design. Would making that distinction be useful for the user, would it make their lives easier, or is that just some unnecessary detail? I tend to think that normal users don't care about that distinction at all (well, I know I don't when I'm just using DOSBox), and having two different alphabetically sorted lists would make it difficult to find the command you're looking for.

But if we decide that info is really useful, we could still have our single A-Z sorted list and also mention per command whether it's a built-in or an external command.

Yeah - it's definitely balancing act; how much of a helpful "cheat sheet" can we pack on a page?

I was thinking something like this (albiet a lot simpler):

Where our categories might be:

• filesystem
• networking
• media-mounting
• ...

Then again, even that assumes some knowledge ... these might be foreign to a 100% tablet gamer or someone whose only owned an iPhone. But, we've gotta start somewhere!

I suspect when you get into it you'll find a layout (without or without categories), that seems to be the right balance for a beginner.

There's also the intro command, so I think help should be used as a reference for commands, rather than a complete "beginners guide"

Then again, even that assumes some knowledge ... these might be foreign to a 100% tablet gamer or someone whose only owned an iPhone. But, we've gotta start somewhere!

Yeah, so when compiling the list I think the best approach would be to think like this: what would a typical novice user need for installing, configuring and playing a typical game? So definitely no commands that are only useful in batch files, that's an advanced topic.

There's also the intro command, so I think help should be used as a reference for commands, rather than a complete "beginners guide"

I think the intro should give detailed explanations of the useful commands, maybe one or two more pages could be added to it (but not too many). Then the short help output should list at least the same commands from the intro as a quick-reference guide, and possibly a few more (for people who've read the intro text already and are vaguely aware of what can be done, but don't remember the exact command names).

So, I have been working on this.

help /all now shows all available commands:

help <cmd> and <cmd> /? now show the same help text:

The help for all shell commands can also invoked with -h and --help as well as /?. I haven't gone through all the programs yet though.

Code probably needs a bit more cleanup, and I we need to come up with a list of 18-20 programs and commands to list with the bare help command.

BTW, I've noticed that config's help could use some love.

Noice! :)

BTW, I've noticed that config's help could use some love.

Yeah, I've noticed too and definitely agree with you.

Looks great!

BTW, I've noticed that config's help could use some love.

Let some of that love flow to the wrapped IMGMOUNT summary, too :-). Maybe something like:

• "Mounts CD (iso or bin+cue) and floppy (img) images", or
• "Mounts CD (iso or bin+cue) and floppy (img) images to a DOS drive"

Small comments:

• the description of the MOUNT command should start with an uppercase letter.
• the description of the CONFIG command should end with a period.

Small comments:

• the description of the MOUNT command should start with an uppercase letter.
• the description of the CONFIG command should end with a period.

I haven't changed any messages (yet), so it currently uses whatever is available.

Another detail is that not all programs and commands have a "short" help line. In such cases, I'm using the first line from the "long" help. That's what's happening with CONFIG.

Small comments:

• the description of the MOUNT command should start with an uppercase letter.
• the description of the CONFIG command should end with a period.

I haven't changed any messages (yet), so it currently uses whatever is available.

Another detail is that not all programs and commands have a "short" help line. In such cases, I'm using the first line from the "long" help. That's what's happening with CONFIG.

Cheers, makes sense!

List of default commands for HELP:

CD CLS CONFIG COPY DEL DIR EXIT IMGMOUNT INTRO MD MIXER MOUNT RD REN RESCAN TYPE

Any i missed?

That list looks pretty much perfect to me!

Thanks, the list could be broken down into two parts for better readability. I'm not happy with "File commands" and "DOSBox commands" though. Maybe something more elegant could replace these.

-File commands CD COPY DEL DIR MD RD REN TYPE

-DOSBox commands CLS CONFIG EXIT IMGMOUNT INTRO MIXER MOUNT RESCAN

Remember, any grouping would eat into the number of commands/programs that can be displayed on the single page, and I think for the "common" help, keeping it to a single page is desirable. We have a max of 24 lines to play with.

(I'm not at all implying that I'm too lazy to implement that... Definitely not. Absolutely certain.)

I agree, short help should definitely be a single page. What we have now would fit on a 80x25 screen nicely with the proposed categorisation, assuming single-line short descriptions (which is the case already for these commands, if I'm not wrong):

We could even add up to two extra commands if we really wanted to! 😉

I like "File commands" and "DOSBox commands". Maybe you could say "File operations", but that's not exactly better... I've considered "DOS commands", but if the goal is to help people who have no idea what "DOS" really means, that's not really helpful at all. Plus "DOS commands" and "DOSBox commands" sounds confusing.

(Btw, CLS isn't really a DOSBox command, but whatever... It doesn't warrant a separate category, and it's not a file command... This categorisation is good enough.)

@shermp 🥇 for removing the < and > characters surrounding the commands. That was completely unnecessary and didn't add any value, only some potential confusion, and took up valuable space. 👍🏻

Another small inconsistency thing. In the list of commands we use upper case and blue colour for the command names, but in the detailed help for the individual commands we use lowercase and green colour.

Wouldn't it make sense to use the same colour and casing consistently? Then the user would go, "okay, this is in lowercase and it's green, so that's a command!" I think colour coding is good, but then it needs to be applied consistently across the board.

I like the lowercase bright green personally for the commands, but happy with whatever, just make it consistent.

@shermp 🥇 for removing the < and > characters surrounding the commands. That was completely unnecessary and didn't add any value, only some potential confusion, and took up valuable space. 👍🏻

Yeah, I didn't like the < and > either. Didn't actually save any space though, because I replaced them with spaces to keep the same amount of padding. Can adjust to give another couple of characters if needed though.

Don't mind what colour we use, it's easy enough to change (and I no longer have to lookup ANSI codes).

EDIT: BTW, this can be tested on the sp/help-refactor-2 branch, I'll probably open a draft PR tomorrow. Although I might add the grouping feature first. While we're at it, why not add a "useful for batch file" grouping for help /all?

While we're at it, why not add a "useful for batch file" grouping for help /all?

Yeah, so that's a variation on @kcgen's "cheat sheet" idea, and I think it's worthwhile to do it. I'd say grouping the commands is more useful than a simple A-Z ordered list.

How about these groups for the full help?

• File commands
• DOSBox commands
• Batch scripting
• Misc (for stuff like VER, MEM, LH, etc.)

I'm not really happy with it, it's just a start; most likely we could come up with better categories, so post your ideas 😄

I'm not really happy with it, it's just a start; most likely we could come up with better categories, so post your ideas 😄

Naming things is Hard (tm)

Ok, I've refactored the refactor, Will open a draft PR once all CI workflows complete.

EDIT: Sigh... MSVC builds will take a while. redacted vcpkg :(

Phew: Total Duration: 1h 1m 1s. That took a while...

Work on this item has been completed, just keeping it open for documentation purposes.

I think it would be better to create a new issue for the documentation and link the closed issues there. Less clutter.