AMB: Ancient Machine Book
Writing with digital technologies can include a variety of tools. Here's how to start writing in a lightweight ebook format.
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. 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:
|Plain text. This is the default.|
|Link to another AMA file. Indicate the destination file, then a colon (|
|So-called “boring” text such as copyright or asides.|
|A literal percent (|
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.