AMB: Ancient Machine Book

Technical writers have a variety of tools and technologies they can use to write documentation. Many writers rely on HTML, Markdown, and DITA to get the job done. But sometimes, technical communicators must use other tools that better suit the environment in which they are working. For example, much of the Linux system documentation is written in nroff and groff.

A less known documentation format is AMB, the Ancient Machine Book format. This is a very lightweight ebook file format meant for low memory systems like DOS. You can find more information at the AMB website.

AMA files and AMB containers

The AMB file is essentially an archive that contains other AMA content files. This is similar to an EPUB file that is a zip file containing XHMTL content with XML metadata.

Filenames within an AMB file are not case sensitive; the file MORE.AMA is the same as more.ama or MORE.ama. Every AMB file starts with an AMA file called index.ama, which is the file that AMB readers will look for first.

AMA source files are plain text files that use commands to indicate basic formatting. These commands are of the format %x. That's a % followed by a single letter instruction:

Every new line in an AMA file starts as plain text (%t). That means you don't need to indicate %t at the start of a new line.

AMA files may not contain the Tab character, but may use either Unix-style (LF) or DOS-style (CR+LF) to indicate the end of a line.

In AMA files, text is not collected and lines are not filled automatically like in other typesetting systems like HTML, nroff, and DITA. Instead, lines are presented as they are given in the file. When writing AMA files, you may need to rely on other tools such as fmt to reformat text to a preferred line length. Lines should not be longer than 78 characters.

Creating an AMB ebook

To generate an AMB ebook, first place all of your AMA source files into a single project directory. You must have one file named index.ama, and other files that contain any content linked from the index file.

Let's start with this index file:

%hHow to write documentation in AMB format

An AMB ebook is essentially an archive that contains one or more content
files. The content files use special "AMA" markup instructions to
indicate paragraphs, headings, links to other AMA files, and other
text formatting.

%!Lines should be less than 78 characters long.%t This is because the
AMB reader application reserves one character on the left for the border,
and one character on the right for the scroll bar.

Read %lmore.ama:More Info%t for more information.

This links to a second file called more.ama, which might contain additional information:

%hMORE INFO

Visit <https://amb.osdn.io/> to download the AMB and AMBPACK programs,
and to read the AMB and AMA specifications.      

%bThe end

To give the AMB ebook a title, create a one-line text file called title. Due to how the title is displayed in the AMB ebook, the title should be less than 68 characters long. A longer title will get cut off.

About AMA and AMB files

Save these files in a project directory, such as about, and run the AMBPACK program to convert the AMA source files into an AMB ebook. Use the c action to create the AMB file:

> dir /b about
INDEX.AMA
MORE.AMA
TITLE

> ambpack c about about.amb
Computing the list of files...
Packing files...
  index.ama --> about.amb
  more.ama --> about.amb
  title --> about.amb
OK

You can view the generated AMB ebook using the AMB reader program.