Sunday, January 7, 2018

A new Help system?

The original FreeDOS Help was based on Unix man. FreeDOS Help simply displayed the Help page you asked for, in the same was that Unix man displays the manual page you ask for.
C:\> HELP FIND

$ man fgrep
Later, we introduced an improved Help system, called HTML Help. This used a different design based on a text-mode web browser using simple HTML code. Called without options, HTML Help displayed a kind of "master index" page with links to different Help topics. This design also allowed Help topics to link to other Help topics, like related topics in a wiki.

However, HTML Help is really is a parallel Help system. If someone adds a new command line option to a program included in FreeDOS, then someone (else) needs to update HTML Help, too. FreeDOS contributor Fritz did most of the work to improve FreeDOS HTML Help content. You can see the amount of effort that Fritz had to put into the HTML Help documentation in our ebook, 23 Years of FreeDOS. Fritz says this about HTML Help:

FreeDOS Help 1.0.6 had more than 100 English HTML sites with a lot of expressions from the readme.txt files that I had never heard before, because I am not a programmer, only a trained user. But eventually, the last translation was done and I could publish FreeDOS Help 1.0.6.

Version 1.0.6 was still a little buggy, so I did an update to 1.0.7 shortly after. This must have been in Spring 2008. […]

I would like to see a new dynamic Help system that adjusts based on the installed packages. I had a few weeks ago with a FreeDOS developer, and I wanted to share the idea we came up with in case someone out there wants to take on this project:

I've wondered if it would be possible to create a new Help system that picked up "Help" documentation from each package in some dynamic way. You are thinking in a similar direction. I think it will end up being a rewrite of the current Help. I'm not sure what it would look like or how it would function, but a few thoughts: Maybe Help could pull the description from the installed package, and use that in a menu, perhaps with some "sections" that represent the package groups. For example:
BASE

 [APPEND] - APPEND enables programs to open data files in specified directories
  as if the files were in the current directory.

 [ASSIGN] - Assign a drive letter to a different drive

 [ATTRIB] - Display and set file attributes
 ⋮

Development

 [BCC - BRUCE'S C COMPILER] - Bruce's C compiler is a simple C compiler that
  produces 8086 assembler for tiny/small models.

 [BYWATER BASIC] - The Bywater BASIC interpreter

 [CPP2CCMT] - A C++ to C comment converter.
 ⋮
…and so on…

Each of those is the package title and description copied/pasted from the Software List, which itself is pulled from package metadata. The only difference is I've cast the package titles to all-uppercase.

If the [bracketed] text represents "clickable" text, users could select that entry and view the Help file for that program. When showing the Help file, I'd also have a "Back to menu" option somewhere that lets users go back to the main Help menu.

The problem is there's no defined standard for what a "Help file" should be named. The package spec just says there's a HELP\ directory that contains Help files, and we encourage developers to name the Help file after the package. This has worked well for most packages, which were named simply after the command or function it implemented; a package called Choice typically has a help file called CHOICE. But some developers might have reason to use a different name than the package name (for example, package names that are multiple words, like Bywater BASIC use BWBASIC as its Help file name.

Other developers might choose to split up very long Help files into individual topics. For example, let's assume a very complicated program called Foo. The developer might include a main Help file called FOO, and two other Help files that detail specific usages of Foo called FOODATA about how to use Foo with databases, and FOONET about how to use Foo on a network. So maybe the Help menu might instead list the Help files that you can click on:
FOO - A very complicated program that does lots of things.
        [FOO]
        [FOODATA]
        [FOONET]
This exposes an underlying problem with my suggestion for a dynamic Help system: how does a dynamic Help know what Help files to associate with each program? I suppose one solution is to modify the package manager to automatically create/remove Help entries when you install/uninstall packages. But that assumes that you only install or remove packages via the package manager. Since FreeDOS packages are just zip files, users could also install packages via the Unzip program. So a slightly better solution might be for packages to contain a Help Index file.

I'm sure there's a better way to implement a dynamic Help. Maybe this article will give someone a starting point to implement a new Help.

1 comment:

  1. Looking at how Microsoft has implemented Get-Help in Powershell might be a good start as it is a FANTASTIC help system once you get the hang of it. It also has an option to update your help files from the web to take advantage of improvements to examples/flaws/etc without actually changing the version of programs on your system.

    ReplyDelete