Tuesday, April 24, 2018

A gentle introduction to FreeDOS

One question I get a lot from new users is "I've installed FreeDOS, but how do I use it?" I assume these people haven't used DOS for a long time, or maybe they haven't used DOS before. For the latter group, they might assume FreeDOS uses a command line like Linux. And certainly the DOS command line has a lot in common with Unix and Linux systems, but some of the assumptions are different.

So I wrote an article for OpenSource.com to provide a gentle introduction to FreeDOS. A version of that article will appear here on the FreeDOS blog in a few weeks.

This is meant as the first part in a short series of "how to use FreeDOS" articles that I plan to write. In this article, I talk about how to find your way around the DOS file system, using the CD and DIR commands. If you're new to FreeDOS, I recommend you read this article.

Monday, April 2, 2018

PC emulator screenshots look weird

If you remember the early PC era, or if you are a hobbyist who uses original PC hardware, maybe you wonder why PC emulator screenshots don't quite look like screens running on real hardware.

It's really noticeable in text-mode screenshots. For example, here's a screenshot of FreeDOS 1.2, taken in QEMU:

And my favorite DOS spreadsheet, As-Easy-As:

In text mode, QEMU emulates a standard PC character set, at 9 pixels wide by 16 pixels high. So it's easy math to understand why this 80×25 display is 720×400 pixels in size.

If you're running FreeDOS on modern hardware, such as a laptop, using an LCD screen (most common today) then this screenshot should look normal to you. The problem is that original PC hardware didn't use an exactly square pixel. So when you compare this 720×400 screenshot to original hardware, the screenshot looks weird.

The pixel hasn't always been a square dot. In modern flat panel displays, such as LCD, the pixel is a roughly square arrangement of red, green, and blue rectangles. Light all of them at once, and the human eye perceives them as a white square.

Original PC hardware didn't use LCD technology, but instead the cathode ray tube. The CRT used a hexagonal arrangement of red, green, and blue dots. Because these were not rectilinear, each "pixel" overlapped with the one next to it.

In the image below, I've modified Peter Halasz's image (cc by-sa) from Wikipedia, showing the arrangement of RGB on both CRT (top) and LCD (bottom). I've also outlined two adjacent pixels, one with a solid white line, and the next with a dotted white outline. You can see the LCD pixels adjoin, where the CRT pixels overlap slightly.

The result is that text on CRT displays looks a little different than text on LCD displays. Not a lot different, but a little different.

Computer displays on the early IBM PC models used a 4:3 aspect ratio, and the character generator outputted 80×25 text that neatly filled the screen. But in modern PC emulators, a pixel in text mode is represented as a single square dot. That means 80×25 text at 9×16 pixel dimensions fills a 720×400 screen, at an aspect ratio of 72:40, or about 5.4:3 aspect ratio. So the text appears too wide, compared to original PC hardware.

If I take the original QEMU screenshots, and resize them to have the same height but narrower image width, I can put the 80×25 display into a 4:3 aspect ratio. These screenshots have been forced to 533×400 pixels, which is 80×25 in 4:3 aspect ratio:

This looks more like how I remember using DOS in the 1980s and 1990s.

So if you've used FreeDOS on classic PC hardware, and wondered why the screen looks a little different than the screenshots we use on the FreeDOS website, that's why. Original hardware used a 4:3 display, but modern PC emulators use a one-for-one pixel display in text mode.

I'd be interested to know of any PC emulators that simulate a 4:3 display, and if they do that through video tricks (such as 3D effects) or by implementing a DOS font with a different height and width. If your favorite PC emulator can do this, let me know.

Tuesday, March 27, 2018

Running WordPerfect on FreeDOS

In the 1980s, my preferred word processor was WordPerfect. It was a great word processing system. WordPerfect was fast, powerful, and streamlined. I liked that WordPerfect "got out of the way" so it only displayed my text, plus a small status bar at the bottom of the screen.

I used WordPerfect throughout the 1980s, but moved on to a different DOS word processor soon after 1990.

I haven't run WordPerfect 5.1 for DOS in a long time. Sure enough, it installs and runs great on FreeDOS! I tested WordPerfect on FreeDOS 1.2, running in a QEMU virtual machine.

But WordPerfect could be very challenging to use. WordPerfect used the function keys to access the different features, like turning bold text on or off, or centering a block of text, or saving your work. Each function key F1 to F12 could be modified using Alt, Ctrl, or Shift, with a possible set of 12 × 4 = 48 different key combinations. But in practice, not all of the function combinations were used.

In my test, I wrote a simple document that demonstrated centered text, and simple formatting.

A powerful feature of WordPerfect was Reveal Codes, which allowed you to see how the word processor translated your document. Have you ever messed up a document in LibreOffice or Microsoft Word, adding some random formatting, and you wish you could go in and remove the one weird formatting code? With Reveal Codes, you could do that.

As an experiment, I loaded my test file into LibreOffice, and it imported correctly. Granted, this wasn't a very complex document, but it was interesting to see that LibreOffice could read WordPerfect files.

If you're interested in learning about the history of WordPerfect, you may also want to read Almost Perfect by Pete Peterson. You can buy it on Amazon, or download the free ebook version from the author's website.

Tuesday, March 13, 2018

How to run FreeDOS on Raspberry Pi, part 2

I expanded my other item about How to run FreeDOS on Raspberry Pi, and turned it into an article for OpenSource. Here's a recap from that:

As the founder and project coordinator of the FreeDOS Project, I'm often the go-to person when users ask questions. And one question I seem to get a lot lately is "Can you run FreeDOS on the Raspberry Pi?"

The short answer is "no" because like any DOS, FreeDOS needs an Intel CPU and PC BIOS. The Raspberry Pi doesn't have either of these. The Raspberry Pi is based on an ARM CPU, which is a completely different architecture.

But you can run FreeDOS on the Raspberry Pi if you use a PC emulator, like QEMU. FreeDOS runs fine in QEMU on Raspberry Pi, including games, but be aware that installing FreeDOS will take a long time. Actually, anything that requires a lot of disk I/O (like installing software) will be slow because the microSD storage on a Raspberry Pi isn't exactly fast.

Once you have installed FreeDOS in QEMU on the Raspberry Pi, you shouldn't notice any performance issues. For example, games usually load maps, sprites, sounds, and other data when you start each level. While starting a new level in a game might take a while, I didn't notice any performance lag while playing DOS games in FreeDOS on the Raspberry Pi.

Sunday, March 4, 2018

Running As-Easy-As on FreeDOS

In the early 1990s, I was an undergraduate physics student at the University of Wisconsin-River Falls. A major component of our physics program was the physics lab. Every semester of the two-year General Physics track included a lab. And later in the program, physics students participated in Physics Lab 301 and 302, also known as "Junior Lab" because most of us took that in our Junior year. Depending on your program focus, you might take other physics labs.

As you can imagine, a large part of my physics degree was involved in a lab. I constantly analyzed lab data. So it shouldn't be very surprising to learn that I depended on a quality spreadsheet program.

In the late 1980s and early 1990s, the most common spreadsheet program for MS-DOS was the Lotus 1-2-3 spreadsheet. I remember my dad installed a copy of Lotus 1-2-3 on our home, but that was really the "take home" license from his office. Lotus 1-2-3 was excellent software, but it was far too expensive for me. I soon discovered the As-Easy-As spreadsheet, a shareware program that provided basically the same functionality and features of Lotus 1-2-3, but at a fraction of the cost.

"Shareware" was still something of a new idea in the early 1990s. The basic idea was that you could install the software and try it out. If you liked it, you registered the program by sending the author a check. Most shareware registration fees were pretty low, usually $20 to $30, depending on the program. And the shareware model encouraged you to share the program with friends, such as by passing around the install program on a floppy disk. Hence the name "shareware."

I don't know how many times I used As-Easy-As to help analyze my lab data, but I know it was a lot. I especially appreciated the linear regression function in As-Easy-As, which fit the best line to a linear data set, including standard deviations of the slope and intercept. These "error analysis" values were a required element of our physics labs. While I could run linear data analysis via a FORTRAN program on our campus VAX system, it was much more convenient to run the analysis using As-Easy-As on my home computer, without leaving my dorm or apartment, and without having to dial into the often-busy modem pool.

As-Easy-As was my favorite DOS program of the era, no question. And I still have a great fondness for As-Easy-As, many years later. Whenever I install FreeDOS somewhere, I usually install As-Easy-As, as well.

If you're new to FreeDOS and wonder, "What can I do with FreeDOS?" then I encourage you to try As-Easy-As. While the original version of As-Easy-As was shareware, TRIUS Software has since posted the original install files and activation code for As-Easy-As 5.7, including the full user manual, for free. Thanks, TRIUS! (This isn't "Free software" or even "open source software," but a "closed source" program that is now available at no cost.)

Installation is simple; just unzip the package and run the installer. When you've done that, find your way to the As-Easy-As directory (by default, that's C:\ASEASY) and run the ASEASY.EXE program.

As-Easy-As includes several sample spreadsheets that demo the functionality of the program. You can calculate a mortgage, manage a checkbook, generate probabilities based on different functions (Poisson, Gaussian), convert units, and a host of other functions.

If you are familiar with modern spreadsheet programs like LibreOffice Calc or Microsoft Excel, you will notice a few differences in As-Easy-As. That's because As-Easy-As tried to be as much like Lotus 1-2-3 as possible. Microsoft, and later LibreOffice, tried to simplify the spreadsheet and introduced some new standards. You'll notice this in how you enter data into the spreadsheet. There are three basic ways to enter data:

1. Number data
Spreadsheets were built for numbers. That's their specialty. So As-Easy-As (as most other spreadsheets) make it really easy to enter numbers. Just type a number.
2. String data
In Excel and other modern spreadsheets, you can just type in a string, like the label for a column. As long as the string doesn't look like a number, then Excel saves that data as a string. As-Easy-As sort of works the same way. If you enter an x in a spreadsheet cell, As-Easy-As saves that as an x string. But it's safer to enter strings by starting them with a single quote. So instead of typing x, you type 'x.
3. Calculations
This is really where things are different under As-Easy-As versus modern spreadsheets. In Excel or other spreadsheets, you start a calculation with the = sign. So to enter a calculation like "cell A1 plus one" into Excel, you type =A1+1. In As-Easy-As, you start calculations with a + sign. So to enter the same calculation in As-Easy-As, you type +A1+1.

Or as you'll see below, you can also start a calculation with @.

The power of spreadsheets is in their functions. Functions make calculations really easy. Every spreadsheet has the same basic functions: calculate the sum of a list of numbers, averages, and so on. Some of these functions are named differently As-Easy-As than modern spreadsheets. For example, the function name to calculate an average of a list of numbers is AVERAGE on Excel, and AVG on As-Easy-As.

Functions in As-Easy-As are set off with an @ character. So the SUM function is actually referenced as @SUM and the AVG function is @AVG.

In As-Easy-As, you can get a list of all the spreadsheet functions, and how to use them, in the online help. Just press the F1 key as see the list of @ functions.

Let me show you a simple example:

As an undergraduate physics student, I often used As-Easy-As to perform linear regression. As a quick example, I created a simple table of x,y data that described a line (y=x). Because a line that is exactly y=x isn't very interesting, I added some randomness to it using the @RAND function. The random number function generates a random value between zero and one, and I chose to "center" the randomness around the y=x line. So for each x, the corresponding y value was x+@RAND-0.5.

In the spreadsheet, you can reference another cell using a cell reference. So the value A2 references whatever value is stored in column A, row 2. Once you enter the calculation +A2+@RAND-0.5 into the B2 cell, you can copy the cell to other cells in the same column, and As-Easy-As will propagate the cell references. So the B3 cell bases its calculations from the A3 cell, and so on.

I mentioned that As-Easy-As includes a useful linear regression analysis. You tell As-Easy-As where to find the data, and where to prints its results. As you can see below, As-Easy-As fit a straight line of slope 1.022 ± 0.035 and intercept -0.065 ± 0.318 to my randomized linear data.

And the chart from this data:
(I forgot to set my own scale for the x and y ranges, so As-Easy-As made its own best guess. That's why you get the odd interval values: 1.0, 3.3, … instead of typical axis values like 1, 2, 3, …)

Here's another simple example:

What if you wanted to project a trend of current data? For example, I track how many times people download the FreeDOS 1.2 distribution from our website. It's pretty constant, so I entered the download counts for the month of February 2018 into As-Easy-As, and generated a simple trend starting from the middle of the month.

Since downloads are pretty constant, I made the simple assumption to use the @AVG function on the previous data. That is, the next day's downloads should be pretty close to the average of the days before it. In As-Easy-As, I needed to enter the @AVG function to reference a range of cells.

Referencing a range in Excel or other modern spreadsheets uses the : separator. For example, to reference the five values in column A, rows 2 to 6, you enter A2:A6. But in As-Easy-As, you use the .. separator. You reference the same range using A2..A6.

That's all that's required to generate a simple trend of our download data in February. Since I already had the complete data, I also generated a simple calculation of the difference of the trend prediction versus the actual value.

And the chart from this data:
(This time, I remembered to set the interval ranges.)

Thursday, February 15, 2018

Contribute to FreeDOS!

FreeDOS has always been about developers coming together to write code. In that spirit, I'd like to suggest a few things I think would be great for the next release of FreeDOS.

I've started to assemble a list of programming topics that you can work on to help improve FreeDOS. I've sorted the list according to programming experience required, so you can find ways to contribute to FreeDOS if you are new to programming, an expert DOS programmer, or somewhere in between.

Please visit the list on the FreeDOS website at www.freedos.org/contribute

Monday, January 29, 2018

How to run FreeDOS on Raspberry Pi

I got a Raspberry Pi as a Christmas gift, so naturally one of the first things I did with it was install FreeDOS. Here's how I did that.

As a DOS-based operating system, FreeDOS carries with it certain assumptions about its operating environment: FreeDOS currently requires an Intel x86 CPU, and a BIOS. So that means you can't run FreeDOS on bare metal on different architectures like the Raspberry Pi.

But it is still possible to run FreeDOS on the Raspberry Pi, if you use emulation.

This is really no different than running FreeDOS in a virtual machine on your regular desktop computer. All that's changed is the host platform. Instead of running FreeDOS in a virtual machine on an Intel-based computer running Linux or WIndows or Mac, you are running FreeDOS in a virtual machine on an ARM-base computer running Linux.

QEMU (short for Quick EMUlator) is an open source software virtual machine system that can run DOS as a "guest" operating system Linux. Most popular Linux systems include QEMU by default. On the Raspberry Pi, QEMU is available for Raspbian, the Linux distribution I'm using on my Pi.

Step 1: Set up a virtual disk

You'll need a place to install FreeDOS inside QEMU, and for that you'll need a virtual C: drive. Under QEMU, virtual drives are disk image files. To initialize a file that you can use as a virtual C: drive, use the qemu-img command. For example, to create a disk image file that's about 200MB, type this:
qemu-img create dos.img 200M
Compared to modern computing, 200MB may seem small, that's more than enough to install and run DOS, and several applications.

Step 2: QEMU options

In QEMU, you need to "build" your virtual system by instructing QEMU to add each component of the virtual machine. Although this may seem hard, it's actually pretty easy. Here are the parameters I use to boot FreeDOS inside QEMU:

QEMU can emulate several different systems, but to boot DOS, we'll need to have an Intel-compatible CPU. For that, start QEMU with the i386 command.
-m 16
I like to define a virtual machine with 16MB of memory. That may seem small, but DOS doesn't require much memory.
-k en-us
Technically, the -k option isn't necessary, because QEMU should set the virtual keyboard to match your actual keyboard (in my case, that's English in the standard U.S. layout). But I like to specify it anyway.
-rtc base=localtime
Every classic PC provides a real time clock (RTC) so the system can keep track of time. I set the virtual RTC to match the local time.
-soundhw sb16,adlib
If you need sound, especially for games, I prefer to define QEMU with SoundBlaster16 sound hardware and AdLib Music support. SoundBlaster16 and AdLib were the most common sound hardware for DOS systems, so they work pretty much everywhere.
-device cirrus-vga
To use graphics, I like to emulate a simple VGA video card. The Cirrus VGA card was a common graphics card at the time, and QEMU can emulate it.
-boot order=
You can tell QEMU to boot the virtual machine from a variety of sources. To boot from the floppy drive, specify order=a. To boot from the first hard drive, use order=c. Or to boot from a CD-ROM drive, use order=d. You can combine letters to specify a specific boot preference, such as order=dc to first use the CD-ROM drive, then the hard drive if the CD-ROM drive does not contain bootable media.

Step 3: Boot and install FreeDOS

Now that QEMU is set up to run a virtual system, we can install FreeDOS. Download the FreeDOS 1.2 distribution from the FreeDOS website. The FreeDOS 1.2 CD-ROM "standard" installer (FD12CD.iso) works great in QEMU, so I recommend using that.

Follow the usual prompts to install FreeDOS, and you're good to go.

However, it takes forever to install FreeDOS on the Raspberry Pi. I think this is because of the heavy disk I/O when you install the operating system, and the micro SD card isn't exactly fast. I didn't record how long it took to install FreeDOS, because when I saw it was taking a long time, I did something else and waited for it to finish. It certainly took more than twenty minutes to install. It might have been closer to thirty minutes.

The speed problem here isn't with FreeDOS and it isn't with QEMU; it's because the Raspberry Pi uses a micro SD card as its boot device and main filesystem.

But once I installed FreeDOS, things ran just fine. I was even able to play games. But be aware that if you install FreeDOS on the Raspberry Pi, no matter if you use QEMU or some other emulation environment, it takes a long time.

Thursday, January 18, 2018

No, there is no "FreeDOS Licensed Retailer"

One user reported that a person on EBay is selling FreeDOS on USB fob drives and advertising themselves as a "FreeDOS Licensed Retailer." No, there is no "licensed retailer" program for FreeDOS.

But according to the GNU General Public License, anyone is allowed to sell FreeDOS (or any software distributed under the GNU GPL) so long as they provide the source code, too. And in the FreeDOS 1.2 release, we include the source code as part of the installer packages.

The seller seems questionable to me. A few examples that confuse me:

Is source code included?
I don't know exactly what this person is selling. If it's the FreeDOS 1.2 installer on a USB fob drive, we already have an image for that on our website. Or it could be a pre-installed version of FreeDOS on a USB fob drive. If it's the former, then the source code is already there, in the packages that you can install as part of FreeDOS 1.2. If the latter, it depends if the seller installed source code when they installed FreeDOS 1.2 to the USB fob drive. They advertise a 16GB fob drive, so there is plenty of room for source code if they chose to include that.

Is it a USB fob drive or CD?
The seller claims: "Please Note: We have been authorized under the developer’s GPL license agreement to provide a service to buyers by offering this software in a CD format. This is great news for individuals, companies and organizations who prefer the convenience and portability of a CD, that may not have an internet connection to download the software, prefer the install file to be on a CD for easy distribution to other computers and many other reasons." But it's odd that the seller mentions "CD" and they are selling a USB fob drive instead.

Are they contributing back to FreeDOS?
The seller also claims: "By purchasing this software you will also be helping the open source community, as a portion of sales will be donated to developers to support further development." Certainly no one has contacted me to arrange any donation of sales to benefit FreeDOS. So in this case, the seller appears to be advertising something that is not true. Note that there is no obligation to contribute anything back to FreeDOS under the terms of the GNU GPL, so it seems odd to claim that when they don't have to.

I guess my recommendation is to be careful if you buy FreeDOS online. You can always download the full FreeDOS distribution at no cost from our website.

I have been trying to reach this seller via email. He replied to me once in November, but since then has not responded to emails.

Saturday, January 13, 2018

A new alternative shell?

I've been thinking for a while that it would be awesome to have a modern alternative shell. The COMMAND.COM shell is the bog-standard DOS command shell. We have an alternative shell called 4DOS that was opened by JP Software—I helped them with that, but at the time I didn't have a lot of experience in open source software, and I gave them bad advice about licencing. So the current 4DOS system doesn't have a truly "open source software" license.

Maybe this is an opportunity to start fresh. Since people sometimes ask me how they can contribute to FreeDOS, I thought I'd share this idea here.

I'd love to see someone start from the ground up and write a replacement alternative shell. I don't think you have to start from complete scratch. I'd encourage a new developer to borrow features and code from the FreeDOS COMMAND.COM ("FreeCOM") and even from Unix shells like GNU Bash.

Of course, the shell should be a DOS shell, not a Unix shell. That means it must support the basic Internal Commands: EXIT, DIR, PATH, PROMPT, and CD/CHDIR. And the DOS Batch commands: CALL, FOR, GOTO, IF, REM, SET, and SHIFT.

If you compare that list to the standard list of DOS Internal Commands, you'll notice some commands are missing. But maybe you'll implement commands like MD/MKDIR, RD/RMDIR, CLS, and other traditionally-internal commands as external commands. Up to you.

My first systems administrator job was on an Apollo/DomainOS system, and the AEGIS display environment had terminal windows with a neat feature: input was always on the bottom. So the Apollo/DomainOS guy in me would suggest a terminal that looked sort of like this: (this is a mock-up)

CuteMouse loaded
Installed at PS/2 port

C:\> DIR

 Volume in drive C: is FREEDOS12
 Volume serial number is 2134-5678
 Directory of C:\

FDOS              [DIR]     01-06-2017 3:00pm
3DOS    .EXE     89,123     01-02-2018 5:25pm
3DOSAUTO.BAT        998     01-02-2018 5:25pm
AUTOEXEC.BAT      1,234     01-06-2017 3:12pm
BOOTSECT.BIN        512     01-06-2017 3:12pm
COMMAND .COM     66,945     01-20-2016 7:37pm
FDCONFIG.SYS        848     01-06-2017 3:12pm
KERNEL  .SYS     45,344     06-21-2016 8:39pm
HELLO   .BAT      1,123     01-01-2018 1:25pm
     8 file(s)
     1 dir(s)
    208,441 MB free

C:\> _
So that black-on-white bar at the bottom is the command line input. That makes it really easy to see where you are. Yes, you are always scrolling up from the bottom of the screen, but let's face it; 99% of the time, we're scrolling from the bottom of the screen anyway.

The black-on-white bar should be dynamic. Maybe as you type a command that goes over 80 characters, the bar expands so you have black-on-white as you edit the whole command.

And the colors should be customizable. Maybe you want white-on-blue for the display area on top, and bright-white-on-cyan on the command line. You should be able to set that.

CuteMouse loaded
Installed at PS/2 port

C:\> DIR

 Volume in drive C: is FREEDOS12
 Volume serial number is 2134-5678
 Directory of C:\

FDOS              [DIR]     01-06-2017 3:00pm
3DOS    .EXE     89,123     01-02-2018 5:25pm
3DOSAUTO.BAT        998     01-02-2018 5:25pm
AUTOEXEC.BAT      1,234     01-06-2017 3:12pm
BOOTSECT.BIN        512     01-06-2017 3:12pm
COMMAND .COM     66,945     01-20-2016 7:37pm
FDCONFIG.SYS        848     01-06-2017 3:12pm
KERNEL  .SYS     45,344     06-21-2016 8:39pm
HELLO   .BAT      1,123     01-01-2018 1:25pm
     8 file(s)
     1 dir(s)
    208,441 MB free

C:\> _
And of course, standard application behavior applies: F1 for help. Actually, I'd recommend to implement that as a set of macros, so users can set things to their preferences, such as F1 to insert the HELP command on the command line, or F5 to insert CLS on the command line. A really cool option would let you define if that macro executes the command automatically or just inserts the string. For example:
In that simple example, /X means execute after inserting the text. So tapping F1 would have the shell insert HELP wherever you on the command line, then "hit Enter" for you. But tapping F2 would just insert HELP without doing anything else. (For example, you can then give HELP an argument.)

Up/down arrows should let you edit command history, maybe via a selector pop-up window, so you can see the list of commands as you scroll through the command buffer.

I'll even suggest a name for this alternative shell: "3DOS." If you pronounce "3DOS" it sounds like "FreeDOS," which is kind of cool. And the name suggests that it's a replacement for 4DOS.

I'd love to see an alternative shell that integrates, or at least shares themes with, the PG pager. As you view a file with PG, it should feel like you're still in 3DOS. So maybe that means adjusting the theme for 3DOS, or for PG.

But it's critical that this alternative shell be made available under a free/open source software license. I strongly encourage the GNU GPL, which makes it really easy to borrow code from Bash. And for other reasons, I ask that anyone working on such an alternative shell should not view the 4DOS source code. Let's make this a "clean" effort. Looking at GNU GPL'd source code, and even copying GNU GPL'd source code, is fine—if the new shell is under the GNU GPL, you can re-use any GPL'd code. But don't examine or re-use 4DOS source code, since that's not under the GNU GPL.

Anyway, just an idea.

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.

$ 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:

 [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


 [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.
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.

Monday, January 1, 2018

Write about FreeDOS!

It's a new year, and we wanted to encourage people to contribute to FreeDOS in new ways. If you're already working on FreeDOS through code, design, testing, or some other technical way - thank you!

If you aren't sure how to contribute to FreeDOS, or want to contribute in a new way, we'd like to encourage you to try something new: Write about FreeDOS!

Please share your tips about programming for FreeDOS. Post them on your own blog, or email them to us and we'll do guest posts for you.
What should you write about?
Write about something that interests you! Others will want to see how you're using FreeDOS, to run existing programs or to write your own programs. A few suggestions:
Tips and tricks:

1. Partitioning
2. Optimizing RAM usage
3. Getting the network up and running
4. Make some noise (sound cards)

Recipes and use cases:

1. Gaming
2. Office work
3. Internet usage
4. Multimedia consumption (jukebox)
5. Home/Office file server
6. Development
7. Database server for other FreeDOS clients of old accounting software of some sort
suggestions by FreeDOS member Nicolae Crefelean—or come up with your own!
Or if you're a programmer, you might write a "how-to" article about how to manage very large arrays in memory, or how to load very large files. Or maybe you could talk about how to optimize a DOS program's I/O operations, such as how to read chunks of a file into a memory buffer using read() rather than using streams. Or you might want to write an article about how to use the conio functions to control the screen and read from the keyboard. Or maybe you could write something a little more "entry level" like tips to use the FreeDOS Kitten library to support multiple languages in your program.

Your "how-to" articles don't necessarily need to be about coding in a language like C or Assembly. If your preferred programming language is Pascal or BASIC, then write something about how to write programs in those languages for FreeDOS. If it's a programming language that's included in FreeDOS, we'd like to include it in the FreeDOS summer coding challenge.

Don't limit yourself to compiled languages, either. You can do lots of clever things at the FreeDOS command line and in BAT ("batch") files. So you could write an article about how to use a batch menu tool, like Jerome's V8 PowerTools included in FreeDOS 1.2, to create a neat interactive "program" as one smart batch file.

We want to hear from everyone! It's not just about developers, or people who contribute to the FreeDOS Project directly. Tell us how you use FreeDOS.
How do you write an article?
If you don't often write for a blog, then writing a FreeDOS "how-to" article might seem a little daunting. But really, it's easy!

I recommend you write your article as though you were explaining it to a friend. If it helps, write a draft in your email program, so you can convince yourself you're emailing someone about programming in FreeDOS. And if you like, you can actually send that email message to me (jhall@freedos…) and I'll use it as a guest post on the FreeDOS blog.

If you have your own blog or website, post your story on your blog, and email me to let me know where to find your article. If you don't have your own blog, I would be happy to post it for you as a "guest post" here. I'll even do light editing for you and take care of formatting.

Don't worry about making it perfect. I can do light editing for you before I put it up as a guest post. I'll edit for spelling, grammar, and style. I won't make changes to content or to the flow of your article—but if I do, I'll always run the changes by you first.
If we can gather enough articles by Spring, we'll try to collect them in a "how-to" ebook in time for the 24th "birthday" of FreeDOS on June 29.