HTML Markup 3.0 Documentation

HTML Markup is a fast and easy way to put existing text documents on the web. It is essentially a text to HTML converter. However, it is really much more powerful than that. HTML Markup can automatically detect URL's in documents and convert them to links. It can translate special characters and it is fully-customizable. HTML Markup is also scriptable.

Table of Contents

Installing HTML Markup 3.0

To install HTML Markup, simply copy the HTML Markup folder onto a hard drive. Make sure that the "Engine" file is in the same folder as the HTML Markup 3.0 application.

Quick Start

Using the basic text to HTML features of HTML Markup is quite easy. Follow these steps:

  1. Launch HTML Markup by double-clicking on the icon
  2. Select the conversions that you would like to apply on the tabs of the "Job Ticket"
  3. Click "Convert File..."
  4. Select the text file you would like to convert
  5. HTML Markup will convert the file and ask you where to save it

These steps cover the core functionality of the program but there's a lot more than that! Other features of HTML Markup let you add headers and footers, process multiple files at once, save your settings for future use, and customize the way the program works.

Features

Most documents convert into HTML just fine using the default settings of HTML Markup. This section explains every option that you can use to customize the way your document is converted. It is organized according to the four tabs in the Job Ticket dialog.

AppleScript

HTML Markup 3.0 has a new AppleScript interface which allows you to write your own scripts to control HTML Markup or use another program like BBEdit or WebStar to interface with HTML Markup.

The Standard Suite
Like any good program, HTML Markup supports the standard suite of commands:

The Standard Suite
HTML Markup adds one important element to the standard suite -- the "settings" variable. You can use this to change which set HTML Markup is currently using. This way, you can save a group of settings when you write the script and just have the script always use those settings. You can use the "settings" variable with the "set" command like this:

set settings to "Jenny's Settings"

The HTML Markup Suite
HTML Markup itself only adds one command -- "Convert", which takes a string of text to convert to HTML. Previous versions of HTML Markup had commands like "ConvertFile" which took a file. However, you can use AppleScript to open a file and get its contents so there's really no need for this command. The functionality of the "SimpleConvert" command is now built into the application itself as the "Already HTML" option on the Conversion tab.

Scripting Examples
See the "scripts" folder for some examples of using HTML Markup with AppleScript. If you have any ideas for scripts or some cool scripts that you've written, please send them to klephacks@kagi.com

Open Source

All of the text to HTML conversion functionality for HTML Markup 3.0 is written in Perl. When you launch HTML Markup, an application called "Engine" is also launched. This application is really a Perl interpreter. When you convert a file, this Perl interpreter is really doing all of the work using some routines defined in "markup.pl".

Guidelines for Modifying markup.pl
The "markup.pl" file is distributed in Perl source format. You can modify the functions in this file to change the way that HTML Markup works. Please note that according to your HTML Markup license, you cannot distribute modified versions of the file with HTML Markup. Instead, I request that you submit changes to me to be incorporated in future releases. If you prefer not to do that, you can still distribute your changes but you must distribute them separately from the HTML Markup application. In other words, you cannot remove my version of "markup.pl" and replace it with your own. Yours must be separate.

Overview
With the rules and regulations out of the way, here's an overview of how that file works. More details can be found at the top of the file itself.

The functions in markup.pl should be considered to be set in stone entry points. In other words, the front end of HTML Markup is expecting these functions with these names and these parameters. You can add functions if you want, but they will only be called if you modify one of the existing functions to call them.

Given the close relationship between the front-end (which you can't change) and the back-end (which you can), it may seem like there's little room for improving the distributed markup.pl file. In fact, there's a lot you can do. First of all, there may be places to tweak the performance. I'd be particularly interested in hearing about those. You can also add some features although you won't be able to change the HTML Markup interface to reflect these changes. You could, for example, add a feature to reverse the spelling of all five-letter words. There's no particular entry point where this makes sense but it could go just about anywhere since most of the functions just take the entire text to be converted as input.

Common Questions about HTML Markup and Open Source
You may be wondering why the front-end isn't open source as well. I really see a distinction between the functionality of HTML Markup (Perl) and the user interface (C++). The interface is actually much more difficult to write and probably less interesting to modify. It also contains a lot of code that I didn't write or that I would prefer to retain the rights to.

You may also be wondering why I decided to make the back-end open source at all. The truth is that the easiest way to implement a Perl back-end was to just have a file full of Perl code that gets read in by the Perl interpreter. I was looking for a way to avoid leaving the implementation in a modifyable state when I realized that just leaving it open was the best solution.

Questions and Answers

Q: Who are you?

A: My name is Scott J. Kleper. I'm a graduate student at Stanford University, originally from Pittsford, New York. I originally wrote HTML Markup when I was 17 years old and it's been so popular that I've been updating it periodically ever since. My other programs include MacFolklore, HTML Markdown, NetBots, and KlepSig. All are available from the KlepHacks web page at http://www.printerport.com/klephacks/


Q: Why did you write HTML Markup?

A: During the summer of '95, I did some contract work for a web consulting firm. My first assignment was to convert several articles from text to HTML. I used a freeware program to do it, but the output was a mess and there were no options to select from. I began to write HTML Markup for future projects and quickly realized that it was a general purpose utility that anybody could use. Versions 1.x were all modal programs, meaning you couldn't switch to the finder and they operated linearly. I designed it this way because it was mainly for my own use. However, as it caught on, people started suggesting tons of new features. I wrote version 2.0 from the ground up, incorporating many of your ideas. Over the years, I've gotten better at programming and dealing with the old code in 2.0 became too difficult. Version 3.0 addresses many of the problems with previous versions and provides a clean new codebase to work with.


Q: Aren't there other similar programs?

A: Yes, there are several other programs that do similar tasks. When I first had to convert text to HTML, I used TextToHTML, a freeware program. It was fast, but had few features and wasn't very customizable. There's a relatively new one called Hyperize, which is similar to TextToHTML. I've talked to both authors of these programs. Both are really nice guys and I encourage you to give their programs a shot too and use whichever is best for you.


Q: How can I keep up-to-date on new releases

A: Subscribe to the KlepHacks mailing list! Go to http://www.printerport.com/klephacks/support.html and you won't miss an update.


Q: I work for a user group, CD-ROM publisher, or magazine. Can we give out your program?

A: If you're going to be distributing it electronically or on disk, you may distribute HTML Markup without notifying me. However, I still request that you send me a quick note letting me know where it's going to be distributed. If you are going to write an article or review of HTML Markup, I really really really want to read it. Please please please send me a copy of the article. If you're going to be distributing HTML Markup 3.0 on a CD-ROM, you must notify me first. I will generally grant permission for distribution, but I want to know which CD it's going to be on. Send permission requests, reviews, etc. to:

Scott J. Kleper
Attn: HTML Markup 3.0
klephacks@kagi.com
134 Caversham Woods
Pittsford, NY 14534-2834
USA


Q: I want to learn more about HTML in general. Where can I look?

A: I learned HTML mainly from online resources. I'd check www.yahoo.com for resources. If you'd prefer a book, anything by O'Reilly and Associates will be pretty good.


Q: What's with all the "Registered Version Only" features?

A: The shareware version of HTML Markup has the vast majority of the features of the full version. However, a few minor things have been disabled. This isn't intended to annoy you. Rather, it's to distinguish between people who need to use HTML Markup once or twice and people who really use it a lot and should pay for it.


Q: What's going to happen to HTML Markup in the future?

A: A lot depends on how this version is received in terms of registrations. I hadn't planned on writing a new version after 2.2.1 but there were bugs that needed to be fixed and when I thought about starting from scratch, I had lots of other ideas. If the open-source thing catches on and people submit new scripts, there will be frequent updates. If not, there will probably still be periodic updates from KlepHacks.


Q: Why can't HTML Markup recognize and convert styled text and graphics?

A: HTML Markup is a text converter, and text can't contain styles and graphics! The ability to use styles and graphics is something people have been asking for for a long time. There are some other converters that recognize formats like RTF, which can contain styles. A future version of HTML Markup may add support for RTF or another styled format, but I can't make any promises.


Q: What's the point of a text-to-HTML converter? Isn't HTML already text?

A: HTML is a format that contains plain text. However, HTML offers much more than plain ASCII text does. HTML offers links, styles, lines, and much more. Text is an extremely popular format and is the lowest common denomenator for all operating systems. Millions of documents already exist in text format. HTML Markup provides an easy and effective way of putting these documents online and taking advantage of many of the features that HTML offers.

Registering

Writing shareware is a lot of work, especially for a college student. Considering all the time that HTML Markup can save you, I request that if you find it useful, you pay your shareware fee.

If you do decide to register HTML Markup, you will receive the registered version, which will give you access to all the "locked features" that you can't use in the shareware version. It will also allow you to disable the credit lines at the end of each document and to store more sets.

Registration costs $15 for a single-user license. This means that one person can use HTML Markup on one Macintosh. If you're in a multi-user environment, or want to have HTML Markup installed on multiple machines, you may purchase multiple licenses at $15 each or a site license for $400. If you are a registered user of an earlier version of HTML Markup, you can upgrade for $5. Send me email and I'll give you instructions on how to buy the upgrade. If you decide to upgrade, you must do so directly through me.

There are several ways to register HTML Markup. You can buy it online, phone in your order, pay by credit card, fax your credit card, etc. For information on any of these methods, go to:

http://www.printerport.com/klephacks/sales.html

Or just run the "KlepHacks Register" application that comes with HTML Markup.

You can also get the registered version by sending me a check directly. Make your $15 check payable to Scott J. Kleper and please include your email address if possible. I can also take traveler's cheques, money orders, and international money orders in US dollars.
Send checks to:

Scott J. Kleper
Attn: HTML Markup 3.0
134 Caversham Woods
Pittsford, NY 14534-2834
USA

One last thing about registering. I really appreciate it when people send comments about and suggestions for the program. I read them all and often use the feedback for future versions.

About the Author

For more information about me, please go to my web site.

Version History

HTML Markup 1.0 (8/1/95)

For the registered version, there is now a popup menu that allows you to select the colors. Previously, you had to know the RGB values. There is a tradeoff though. With this method, you only have a selection of 11 colors. There is also a popup menu in the output dialog for selecting the file creator. You can still enter it manually, but you can also choose from Netscape, BBEdit, Microsoft Word, Jot, or SimpleText. I added <BR> tags to the index.html file. A bug in earlier versions caused all the links to be on one line! One user reported that he used URL's within sentences and when Markup converted them to links, it included the trailing periods. I recommend that you always enclose your URL's with < and > but if you use them in sentences, Markup will now recongnize that and treat it appropriately (i.e. it will ignore the period). I got rid of some extra \r (carriage returns) that I had originally put in for debugging purposes. This makes the output look nicer, especially for lists, embedded lists, and numbered lists. I also added support for two more required AppleEvents, namely OpenApp and QuitApp. It's pretty pointless to add PrintDoc because Markup can't print anyways.

HTML Markup 1.1 (8/13/95)

Version 1.1 fixes several small bugs. One problem encountered by a few users with some interesting memory configurations was a write to NIL problem with the summary dialog. A temporary fix for those still using 1.0 is to simply uncheck the "Show final summary" option on the job ticket. Somehow, conversion of smart quotes was _disabled_ in version 1.0 of HTML Markup (it worked fine in the betas). I reenabled it in version 1.1. I also implemented the full ISO Latin set. Now just about any international character or symbol can be converted. There are some symbols, however, that are not in the ISO set so they may not display properly. Where necessary, I have built in my own conversions. I also increased the buffer size of HTML Markup from five kilobytes to seven kilobytes. This really doesn't affect the user. There were no problems with the 5k buffer, but I feel safer with the extra 2 kilobytes. As a side-note, HTML Markup 2.x uses an exact estimation technique so it will not require any buffer at all.

HTML Markup 1.1.1R (11/22/95)

Version 1.1.1R fixes a small bug that showed up ONLY in the REGISTERED version of HTML Markup 1.1. The bug showed up when the "show final summary" option was selected. HTML Markup would convert the documents without a problem but would then crash without showing the summary. This problem was caused by a renumbering of resources in the summary dialog.

HTML Markup 2.0 (3/1/96)

Version 2.0 is a total rewrite of the original program with tons of new features and a flashy new interface. The key features are that this version is non-modal, meaning that you can switch from HTML Markup to the Finder. Previous versions were modal and linear. You launched the program, did your conversion, and it quit. Now you can leave HTML Markup running. Version 2.0 has a great new feature called "sets" that allows you to store multiple settings for different types of jobs. You can select the set you want to use from a popup menu. There are several new conversion options, including nested list conversion of more levels, different styles of line conversions, converting the file name to the title, adding the date and time of the conversion, and much more. Selecting colors is now much better. Instead of selecting from a popup menu, you can now use the standard color wheel to select your colors. You can also now include a URL for the background pattern. The new version is faster. The code is more compact and will allow for future modifications. It is also much more efficient. No estimation of memory allocation is done. Instead, the algorithm is actually run through twice. The first time it figures out how much memory it needs. Yeah yeah, I know this makes it O(2N) for all you CS majors, but the time required is actually negligible in most cases, and it's a very efficient solution. The style of the output is much nicer than previous versions. There's a great new interface with kind of a 3-D look. There's also online help available through balloon help.

HTML Markup 2.0.1 (3/21/96)

Version 2.0.1 fixes a few minor bugs in the initial release of version 2.0. The most significant bug caused bombs on most Macs that did not have Drag-and-Drop installed. While HTML Markup 2.0 was tested on Macs without this handly little extension (built into System 7.5 and later), not all Macs were able to handle its absense and crashed after displaying the splash screen. HTML Markup now checks to see if Drag-and-Drop is installed and doesn't load the code if it's not there. A bug with the "Append credit line" item was also fixed. In 2.0, you could feasibly disable that feature through some clever hacking. 2.0.1 also prevents the user from switching to background windows by clicking in the title bars. For example, the preferences window is a movable modeless window, so you shouldn't be able to switch back to the Job Ticket from there.

HTML Markup 2.2 (8/18/96)

Version 2.2 fixes one conversion bug that falsely translated ê to â. It also fixes a bug that caused HTML Markup to crash if you attempted to convert a file that was open from another application. Version 2.2 adds AppleScript support (see above), changes the way paragraphs were defined (paragraphs can now either be separated by a blank line or start with an indented line), and has a few minor interface tweaks.

HTML Markup 2.2.1 (5/6/98)

After a long hiatus, version 2.2.1 was released to fix some long-standing bugs and some new ones that came up with Mac OS 8. One new feature was added-"End all lines with paragraph" and the header/footer features of the registered version were rewritten. Some extra sample sets were added to the shareware version, the price was lowered to $15 and the following bugs were fixed: the color picker now works under OS8, converting all caps to headers now handles lines with 0's in them, header files shouldn't be truncated anymore, and custom sets shouldn't randomly disappear anymore.

HTML Markup 3.0 (7/25/99)

Version 3.0 is a total rewrite featuring a much-improved interface and an open-source back-end written in Perl. The feature set is similar to 2.2.1 but now offers further customization through the conversion table.

Legal Stuff

HTML Markup 3.0 is ©copyright 1999, by Scott J. Kleper. You may copy and distribute the SHAREWARE version of HTML Markup 3.0 as long as you include all the documentation and everything that came with it when you downloaded it. You may not distributed modified versions of HTML Markup 3.0 (or any accompanying files). You may distribute modified versions of the "markup.pl" file. However, they must be distributed separately from the HTML Markup package. This program is shareware. If you use it, you are obligated to pay for it. See above for payment/registration information.

No warranty is included with this program. Use it at your own risk. There are no known bugs with this program. However, the author is not responsible for any problems caused by it.

This program may be included in online file areas and archives. It may be distributed through user groups and shared with other users. CD-ROM publishers MUST contact me at klephacks@kagi.com before including HTML Markup 3.0 on a CD-ROM product.

If you would like to review HTML Markup for an online or print magazine, please contact me so that I can see a copy.