Creating a Document Using Almost Plain Text (APT) Markup Language

John New

Structured using DocBook XML, edited using XMLmind XML editor, parsed using Saxon, tidied using HTML Tidy.

Revision History
This document was created by John New, an adjunct IT lecturer at Charles Sturt University, Australia.

1. Copyright
2. Introduction
3. What To Do
3.1. Obtain and Install Java
3.2. Create a Publishing Environment
3.3. Get APTconvert
3.3.1. Download and Unzip APTconvert
3.3.2. Read the Documentation
3.3.3. Look At the Examples
3.4. Edit a Document
3.5. Convert the Document to HTML
3.6. Convert the Document to RTF
4. Conclusion

1. Copyright

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.

2. Introduction

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.

 
 --Aptconvert

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:

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

  2. Obtain the technology, often software, to convert the electronic document or file to another format.

  3. Convert the document or file to one or more other formats.

3. What To Do

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.

3.1. Obtain and Install Java

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:

java

If correct, you will see a syntax listing.

3.2. Create a Publishing Environment

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:

c:\xmlpub                             1
         \aptconvert                  2
                   makefile           3
                   \class             4
                   \distrib           4
                   \docsrc            4
                   \java              4
                   \mydocs            5
         \zip                         6
1

Publishing environment top-level folder.

2

Working folder. This is your working folder. It contains the unzipped APTconvert files plus all files that you create.

3

APTconvert makefile (Unix only, ie not required on the Windows platform).

4

APTconvert subfolder. There are numerous folders below each of the subfolders.

5

Your subfolder for source files, output files, and essential processing software.

6

Storage folder. When you download the APTconvert zip file, save it in this folder first.

3.3. Get APTconvert

Currently, you can get APTconvert from http://www.xmlmind.com/aptconvert.html.

3.3.1. Download and Unzip APTconvert

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.

3.3.2. Read the Documentation

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.

Start by reading the "Introduction" (1 Introduction or userguide1.html) from the APT User Guide.

3.3.3. Look At the Examples

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.

First, look at the examples in "2 The APT format" (2 The APT format or userguide2.html) from the APT User Guide.

Second, look at the source files used to create the APT User Guide in the /docsrc folder.

3.4. Edit a Document

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.

3.5. Convert the Document to HTML

Convert the source documement into the required HTML and RTF documents.

Here's how:

  1. Copy aptall.jar and aptconvert.bat into the /mydocs folder. There is no need to make any changes to aptconvert.bat.

  2. Create a new batch file called apt2html.bat that runs aptconvert.bat and also has some APTconvert processing instructions (-PIs).

  3. Run apt2html.bat to convert the document.

For example, to convert a source document to HTML, include the following processing instructions in apt2html.bat:

aptconvert -pi html ... your instructions go here ... %1

where %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:

aptconvert mysourcefile.txt

3.6. Convert the Document to RTF

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.

4. Conclusion

After you have finished this activity, you should have a thorough appreciation of the key techniques required when using markup languages.