Copyright © 2006 John New.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the GNU FDL is available from http://www.gnu.org/licenses/fdl.html.
Almost Plain Text (APT) is a very simple yet powerful markup language. It is particularly interesting because it enables you to create neatly formatted HTML, RTF, and other output formats from a document that appears to be in plain text. As the documentation says:
APTconvert is a command-line tool that can be used to convert the APT format to HTML, XHTML, PDF, PostScript, (MS Word loadable) RTF, DocBook SGML and DocBook XML.
The APT format (Almost Plain Text) is a simple markup language (like HTML) than can be used to write simple article-like documents (like HTML). Unlike HTML, APT uses as few markup as possible to express the structure of the document. Instead, APT uses paragraph indentation.
In this activity, you will mark up one source document using APT, and then create two output documents from the source document - in HTML and RTF.
This will introduce you to some important techniques that you will perform over and over again as you become familiar with markup languages in general and XML in particular:
Analyse the structure of a document or item and assess the best way to mark it up using the markup language, usually in an electronic document or file.
Obtain the technology, often software, to convert the electronic document or file to another format.
Convert the document or file to one or more other formats.
In this practical, you will set up your own publishing environment, create a document using APT markup language, and then produce versions in HTML and RTF.
Various resources are available to help you complete this practical.
We will assume that you are setting up the environment on a Windows platform.
The following steps explain how to complete this practical. If there is no need to complete a step (for example, you already have an existing Java runtime environment), simply skip the step.
The publishing software you will be using requires a Java runtime environment. If you do not have an existing Java runtime environment, you must create one.
Currently, you can obtain a Java distribution from http://java.sun.com/javase/index.jsp. You can choose either the J2SE Development Kit (JDK) or the J2SE Runtime Environment (JRE). Run the installer and follow the instructions. When finished, restart your computer if required.
To check that Java is installed correctly, start a Command Prompt, and then type:
If correct, you will see a syntax listing.
Now you need to create a publishing environment. This is a hierarchy of folders to publish documents. In this case, we are publishing APT documents but you can easily adapt the hierarchy to publish other documents. In particular, you may want to create and publish XML documents.
For convenience, we will assume that you have created a hierarchy of folders as shown:
Publishing environment top-level folder.
Working folder. This is your working folder. It contains the unzipped APTconvert files plus all files that you create.
APTconvert makefile (Unix only, ie not required on the Windows platform).
APTconvert subfolder. There are numerous folders below each of the subfolders.
Your subfolder for source files, output files, and essential processing software.
Storage folder. When you download the APTconvert zip file, save it in this folder first.
Currently, you can get APTconvert from
Download APTconvert into the the
/zip folder. Unzip APTconvert. Copy all unzipped files into the
/aptconvert folder so that files and folders correspond to the publishing environment hierarchy shown.
When you obtain new resources, it is very sensible to read its documentation. This takes time initially but it can save time in the long run. When you read documentation, there is often a Getting Started section. There may also be a tutorial that explains how to use the resources. These are good places to start with any new resource.
In the case of APTconvert, browse around the folders and files from the zip file. Start off by reading the documentation in the
/distrib/docs/ folder. This is the APT User Guide. This introduces APT, explains the APT markup language format, explains how to install APTconvert, and explains how to use APTconvert.
Especially, look at the examples as you read through the documentation. Looking at examples is very useful because examples can show you the best way to structure a document.
Second, look at the source files used to create the APT User Guide in the
Now, edit a document. You will be provided with the document as a plain text file.
Examine the structure of the source document you are going to mark up.
Identify the parts of the source document. Even though the source document is in plain text, it will have a structure that you can easily identify.
Apply APT markup tags to the source document to produce the output formats you want. Remember, you are going to produce both HTML and RTF from the same source document.
If you have carefully looked at the examples, it should be very easy.
Convert the source documement into the required HTML and RTF documents.
aptconvert.bat into the
/mydocs folder. There is no need to make any changes to
Create a new batch file called
apt2html.bat that runs
aptconvert.bat and also has some APTconvert processing instructions (-PIs).
apt2html.bat to convert the document.
For example, to convert a source document to HTML, include the following processing instructions in
aptconvert -pi html ... your instructions go here ... %1
%1 represents the name of the source file.
Start a Command Prompt, navigate to the directory where your files are located, and (if your source file is called
mysourcefile.txt), type and execute the following command:
After you have successfully converted the source document to HTML, create a new batch file called
apt2rtf.bat that runs
aptconvert.bat and converts the source document to RTF. Read the APT User Guide to find out how.