# File Types

> [HTML Version](filetypes2.htm)

_Reviwed and revised June 2024; see History_

A collection of HTML pages with index and table of contents pages, also known as "Web help," is the normal format for A-Shell online documentation. While this is the best choice for most readers in most circumstances, other file formats may be applicable or needed in some situations. Sometimes, for historical reasons or by special request, the A-Shell documents may be available in other file formats. If you would like to get the documentation in a format you don’t see, it may be available on request. Continue reading for information about document formats and files types, and why you might prefer one or another.

**HTML** also known as "Net Help" or "Web Help:" These help files are standard web pages, with hyperlinks, tables of contents, linked indexes and search capabilities. They reside on the MicroSabio web server, are always up to date, and require no downloading step; pages are downloaded on demand—and very quickly. As long as you have a good internet connection, this is the preferred format for help/documentation files.

**CHM** (Compiled HTML, standard Windows help files): CHM files are compilations of HTML pages into a single document which includes all the features of the HTML documents. CHM files are downloaded to and accessed from your computer, and are the preferred help file format when you do not have a good internet connection. CHM files are opened using built-in components of Windows, so no additional programs are required to view them. If you are running Windows 98 or later, you have what you need in order to read CHM files. If you download them to your Windows computer and then double-click on them, they should be properly opened and displayed in the familiar help-file context.  Note also that this file format is no longer recommended or supported by Microsoft, and therefore is becoming less common. More on CHM

CHM files have largely been superseded by Web Help in the A-Shell documentation library. CHM files were the best choice in days of limited internet access—and still are the best choice when the internet is not available. Here is some general information on CHM files.

**Background Information**

●	Compiled HTML help ("CHM") is a proprietary format for help files developed by Microsoft. It was first used in 1997 (Win98) as a successor to the even-older WinHelp format, and is supported through Windows XP, Vista, Win7, 8, 10 and 11. Microsoft no longer creates CHM files for its own documentation and has long since moved on to new formats, but CHM will likely be supported for a long time.

●	CHM files consist of a set of individual web pages plus a hyperlinked table of contents and, optionally, an index. The pages are combined into a single file, which is then compressed using LZX compression. CHM files are therefore quite efficient and and relatively small.

●	CHM files are created using a free tool from Microsoft called "HTML Workshop." There are many tools on the market for creating CHM files, but they all use Microsoft's "HTML Workshop" as the engine for combining and compressing the HTML files. 

●	CHM files contain "active content"—i.e., the files are executable—and therefore are frequently perceived as being security risks. Gmail, for example, blocks CHM files.

●	For more information, see the [Wikipedia entry for CHM files](http://en.wikipedia.org/wiki/HTML_help#_blank), from which some of the above facts were taken.

**Problems and Solutions**

●	For security reasons, CHM files will normally not be displayed properly or at all when you are trying to access them from network drives or remote servers. It is possible to change your security settings to accommodate such files, but the easier solution is just to move the CHM file(s) to a local drive.

●	CHM files will not work if their path or filename includes the pound (aka hash) character '#'. The hash character signifies an anchor in HTML so the CHM viewer fails to resolve the path properly and to retrieve the content. If this is your situation, move the file to a path that does not have a hash character in its name. In general, avoid using '#', '?', '\&', '+', and other special characters in directory names.

●	When you click on an external link inside a CHM file, the web page is opened with Internet Explorer and not with your computer's default browser. Why? Since the CHM viewer itself is a component of IE, or \*is\* IE operating in some special mode, the program does not issue a conventional call to the PC to use the default browser. Instead, since IE is already running and available, IE simply "tells itself" (?\!\!) to open the external page. There is no work-around to this "problem."

●	Windows security provisions may prevent CHM files from opening. If you get a "cannot display" message in the right pane of the display window, this may be the problem. Solution: right-click on the CHM file and select _Properties_ from the popup menu. Click on the _Unblock_ button immediately below the Advanced button on the General page, then click _Apply_. Once the CHM file has been unblocked, the _Unblock_ button disappears, and you need only do this once—i.e., not every time you open the file.

●	If the ideas and suggestions mentioned above do not resolve your problems opening CHM files, you might want to do a web search for "MJ's Help Diagnostics." This is a program that checks to see if the Windows programs and components needed to display CHMs are properly and completely installed on your (Windows) computer. 

**PDF** (Adobe's Portable Document Format): Various A-Shell docs have been available as PDF files in the past, and may be available on request; inquire if you are interested. Files of this type consist of exact replicas of printed pages, just as they would appear in a printed manual. If you plan to print a copy of the document, this is the best type of file to download. PDF files are not hypertext documents or pure help systems, but most documents come with an interactive table of contents. This file format and the program(s) needed to read these files are the property of Adobe Systems. If your computer does not already have a copy of Adobe® Acrobat®, which you will need in order to read the files, you may download a free copy from the Adobe Acrobat download page. If you are printing or plan to print PDFs, see note under Printing below.

**TXT**: Text files are universally readable by all computers and all operating systems, so you can download or display them regardless of your system. They do not contain any organizational or text formatting, however, and are therefore the most difficult file type to navigate.

**DOC and DOCX**:  These are the native file formats of Microsoft Word. From the beginnings of A-Shell documentation until 2022, all documentation was written and maintained in Word, and then published to other formats using various types of conversion and authoring programs. Although the A-Shell documents are now maintained in another format, Word files may be available; inquire if interested.

**Printing**

HTML and CHM files are not particularly well-suited for printing. They are fine if you want to print a few pages or even a full section, but not if you want to print an entire doc/manual for reading and reference. The best format for printing is PDF. If you wish to print the docs, therefore, make sure to get a PDF version of the doc(s) you want to print. If you don’t see them here, contact MicroSabio and ask about a PDF for the doc in question.

Important note on PDF printing: If you intend to print the PDF documents, be sure that your printer is configured to interpret colors as either black or white; if the printer tries to interpret colors as shades of gray, all the color printing in the document will appear as gray—i.e., light and not very readable. A-Shell help files do not use a lot of color, but they use some for text formatting and screenshots. On pure black and white printers, configured as black and white printers, the colored material prints fine.

**History**

Through approximately the year 2001, the A-Shell documentation was written in Microsoft Word and was presented to users and developers in Word or PDF files. In additional to the on-going record of changes to A-Shell, which was available in simple text format, A-Shell was described in four manuals: Setup Guide, Command Reference, XCALL Reference and Development Guide.

In 2001, with the arrival of Ty Griffin as a member of the MicroSabio team, the A-Shell documentation remained in Word but was now processed by a "help authoring tool" called Doc-to-Help. This tool produced CHM files, which soon replaced the Word and PDF files as the "presentation of choice" for all the A-Shell documentation. Internet access was generally not fast or reliable, so the CHM format (a single file which resided on the users' computer) was much better than web-based alternatives.

In approximately Spring 2012 and A-Shell version 6.1, two things happened:

•	The four separate documents mentioned above were consolidated into one: The A-Shell Reference. 

•	The new A-Shell Reference, along with the smaller documents for A-Shell's add-on products (ATE, PDFX, EMAILX, etc.), were published in "Web Help" format instead of CHM format. Since most A-Shell users, developers and sites now had good and reliable internet connections, the Web Help format became the new standard for not just A-Shell but most of the documentation world.

In 2015, Doc-to-Help, the tool that MicroSabio had been using to generate the CHM and HTML files presented to users, was sold for the second or third time. The old program continue to work and meet MicroSabio's needs, but the new owner of Doc-to-Help was not continuing to develop the program. MicroSabio started looking around for alternatives.

In December 2019, after concluding that there was no future in Doc-to-Help, MicroSabio purchased a new help authoring tool called "Help \& Manual." It took a couple years to learn the new system and make the full transition from old tool to new, but it eventually happened. The new online documentation published with H\&M was essentially identical to the old versions published with Doc-to-Help. 

As of this writing, June 2024, Help \& Manual has been in use for several years, and is nicely meeting the documentation needs of A-Shell and MicroSabio. All of our online documentation is published by H\&M, and H\&M the software product is undergoing continuous development and improvement, much like A-Shell itself. We expect to be using H\&M for the foreseeable future, and recommend it to anybody who has documentation publishing needs.