NOTE: This software is in beta version. I have tried to test the macros as much as possible but I seriously doubt whether I got everything right the first time around. If you find a bug, or if something about the macro suite really bugs you, you can email your report to Mike.Sosteric@Ualberta.Ca.
Intro
ction
If you are like me, you have tried numerous HTML markup tools and have been dissatisfied. This is not always a result of the quality of the tool. More often it is simply because html editing tools were designed to create hypertext from the ground up.
Unfortunately, I almost never create HTML text from the ground up. Usually I have a document or set of documents that I want to convert to HTML. HTML editors are usually no use because the process of tagging an entire document is labourious. The other option is HTML WordProcessor conversion macros. But IMHO, there are two problems. Either the macros are to dumb to be of any real use, or the authors of the macros forget the cardinal rule of wordprocessors-
Not All Document are Created Equal.
Forgetting this rule results in overzealous attempts to create macro suites that try to do everything under the HTML sun. But since the authors of the macros can
t anticipate every little quirk document authors might throw into their document, usually these super complicated macro suites fail to work for more than a handful of people who accept the macros unstated document assumptions.
So to overcome these problems I set out to write some software that would
intelligently
assist the HTML author. What I ended up with was a set of Describe 5.0 macros that makes it easier for me to mark up a regular documents. Most of the macros are straightforward. However I have also included some automated function macros that clean up documents, tag paragraphs with HTML containers (
blockquote
), and markup and number notes. I will explain all these in latter sections.
While creating these macros, I have tried to keep one directive or principle of design in mind. NO ASSUMPTIONS!. I have tried to anticipate the many ways authors can use to create documents. When I couldn
t anticipate, I didn
t make assumptions. I have found that when authors make too many assumptions about the look and feel of documents, the macros they design make a mess of things and end up creating as much work as they eliminate. Because of this philosophy, these macros are not entirely automated and they require your input to tell them what to do. I think you
ll find that in the long run, this makes the job of HTML markup easier and more fluid.
Finally I need to enter the standard disclaimer with one caveat. The standard disclaimer is of course, whatever these macros do to your computer or you files, it is not my fault. Use them at your own Risk! The chances are of course low that anything serious will happen. These are after all only macros. But you never known. If you are not prepared to assume full responsibility (which you do by running any of these macros) then don
t use them.
The caveat is that I am not a computer programmer by trade. If you are a programmer, you may have been able to come up with more elegant solutions than I. Oh well, I wrote these macros only for me. If you find them useful, great. If you don
t, that
s life.
Macro Usage
Hints and Tips
USE STYLES and STYLE SHEETS!. This is good advice generally but even more valid when you need to convert documents from one format to another. Using style sheets makes it easier to automate the conversion of documents since it is easier to identify the purpose of sections of text. Using style sheets makes macros function better for the much the same reasons. This is especially true for macros that attempt to convert entire documents into HTML on the fly. Inconsistent use of styles will result in inconsistent markup.
I find the easiest and quickest way to use these macros is to assign them to accelerator keys. I have taken the liberty of doing this for the heading, paragraph, and blockquote macros. To activate the heading macros, hit ALT-1 for heading one, ALT-2, for heading two, etc. Paragraph is ALT-P, and blockquote is ALT-B. You
ll find that if you assign keys to the functions you use the most, it becomes very easy to mark up even large documents quite quickly.
Document Structure
The macros in this section deal with the structuration of HTML documents. Most of them operate in three modes, a paragraph mode, a container mode and a newline mode. In paragraph mode, you simply put the cursor over the line of text you wish to markup, and activate the macro. The macro then reads the start and end positions of the paragraph and tags the section of text. In Container mode, highlight a section of text and activate the macro. The section you highlighted will then be surrounded with the appropriate tags. Finally, if you activate the macro on a blank line you
ll just get the containers.
The Base, ISINDEX, and Skeleton macros function differently. With the base macro, you can either a) surround a block of text containing and URL reference, or b) activate the macro without highlighting of block. If you highlight a block, the macro assumes the TEXT you highlighted is an URL reference and builds <A BASE=
> using the text you highlighted. If you didn
t highlight any text, the macro prompts you for the URL to use.
The ISINDEX macro simply places <ISINDEX> in the document. If you highlight text before you activate this macro, the text will disappear forever!
Finally, when you activate the skeleton macro, it surrounds the entire document with a valid HTML2.0 skeleton. It doesn
t matter where in the document you are when you activate the macro. It simply goes to the top and bottom of the macro and inserts the appropriate text. If there is no text in the document, he macro just gives you a valid skeleton.
Headings
Like the functions in document structure, the Heading functions operate in three separate ways depending on the context within which the macros are activated. If you highlight a block of text the macro will surround the highlighted block with the appropriate heading tags.
Alternatively, if the heading is on one line (normally the case), simply place the cursor anywhere on the line and activate the macro. The line will then be surrounded with the heading tags. NOTE: This macro will not tag correctly headings that are longer than one line.
Finally, you can activate the cursor on a blank line and get straight heading tags with the cursor positioned nicely between the tags
Paragraph
The paragraph, blockquote, pre and center macros work a) on a new line, b) while the cursor is within a paragraph, c) or when a block of text is highlighted. As you see, I
ve tried to be consistent across macro functions to make markup easier.
The HR and Break macros simply insert the appropriate tags. HR prompts for some values.
The comments and address macros work a) on a newline, or if b) with a blocked section of text.
Character Markup
All of these work in two ways. Position the cursor on a blank line and get the basic tag or highlight a section of text and have the text surrounded by the appropriate tag.
Lists
Lists are pretty much all the same. So, except for the glossary list and list item macros, they all work in two ways. You can highlighted a section of text. The macro should correctly enclose the text in the appropriate container tags and itemize each line or paragraph of text correctly. Alternatively, if you activate the macro on a blank line, you just get the container tags.
The Glossary macros are dumb macros. You just get the tags.
LINKS
A HREF creates a link in two ways. If you highlight text, the macro prompts you for an url and an optional name (anchor) for the link. If you don
t highlight text, the macro prompts you for the text to display, the url and the optional link name.
The mailto macro creates a mailto url. If used on blank line, the macro prompts for the link name and email address of the linkname. If you highlight a block of text (like someone
s name) the macro prompts you for the email address
The anchor macro creates an hypertext anchor in the document. If you block of a section of text, the macro uses the blocked section as the anchor reference. If you don
t block a section of text, the macro prompts you for the name of the document anchor.
Inline Images
These macros are pretty self explanatory. If you need the inline to be an imagemap, choose the appropriate macro.
Automated Functions
These macros are an attempt to automate some of the routine and highly repetitive functions of converting and standardizing the look and feel of HTML documents. They are based on a number of requirements that I have when converting documents to HTML. For example, I like to make sure there are no extra spaces or paragraph markers in the document. I also like to ensure that the period at the end of a sentence is followed by two spaces and not one. I admit that these are my own preferences. As a result, you may or may not find these macros useful. It all depends on the way you like to format documents.
Standardize Document
This macro performs a number of standardization functions. It eliminates extra spaces at the end of paragraphs. It ensures that there are 2 spaces after each period in the document. If you have a REFERENCES or reference section, it ensures that the section always reads
REFERENCES.
It changes footnotes and endnotes to
NOTES.
Finally, the macro ensures that there is only one
end of paragraph
marker at the end of paragraphs. Some people like to add space between paragraphs by hitting the return key instead of using the style sheet options. This is generally bad practice and interferes with the later markup of the document. And since spacing is irrelevant in HTML documents, there is no reason to keep them.
Convert Special Characters
This macro converts double quotes to the
"
html tags, handles
with
&
and tags sections of text that are italicized, emboldened or underlined with the appropriate HTML presentation tags. This macro should be run before you place an HTML skeleton around the document since the skeleton contains quotes that shouldn
t be converted to ".
This macro is not exhaustive. I haven
t bothered to include routines for any of the other ISO characters. This is something I
ll do as the characters appear in my own documents.
Mark Quotes and Paragraphs
The documents that I mark up generally contain lots of paragraphs and quotes. So I have two macros that automate the tagging of these documents. Since I am not always the one who has prepared the documents, the style used to identify quotes and paragraphs is never consistent. As a result, I have to have a flexible way to notify the macro of the appropriate style. I chose to do this by getting the macro to read the style at the cursor position and then to tag all sections of the document that share that specific style. That way it doesn
t matter what name the author has given to the paragraph style. It could be
document
normal
paragraph
/document/par
or whatever.
To use these macros, simply place the cursor over a paragraph or quotation, and activate the macro. Know that you should have separate styles for sections of text like
notes
bibliography
headings.
Otherwise the macro might mark up sections of text you don
t want marked. For example, say you use two levels of headings and say that instead of using styles to format these, you center them, make the characters bold or italic, etc., by hand. These headings only LOOK different than the paragraphs. The macro will read the underlying style and tag them as if they were paragraphs.
NOTE: The paragraph macro has an optional routine to automatically number paragraphs. If you want paragraphs numbered, type
at the prompt. If you don
t want them numbered, type
Mark and Link Notes
Finally, there is the
mark and link notes
macro. This macro looks for sections of text that are
superscripted.
Is assumes that superscripted text references a footnote or endnote section. It creates hypertext links to the appropriate footnote or endnote number.
Because superscripted text is difficult to see, and as a result, you can delete a footnote that you don
t need but still leave a superscript style marker over a space, the macro first runs through the document and eliminates blank superscript sections. Obviously, if you use superscripts for something other than footnotes (like mathematical equations) don
t run this macro.
For the Future
If you like these macros, let me known and I will work on extensions. In the future I might add a) form support, table conversion, and
http-equiv
and
content
meta-information macros. I might also provide better functionality when describe (currently the best wordprocessor package on the market - IMHO), develops a better regexp search and replace and better macro to user interfaces (i.e., more power over the look and feel of dialogue boxes with optional radio buttons and like that).
COPYRIGHT NOTICE
These macros are copyrighted by Mike Sosteric with all rights reserved. You can distribute these macros free of charge so long as you don
t make any money from the exchange (except for a suitable charge for recovering the cost of copying, disks, etc.).
These macros cannot be included in prefab commercial software packages without the express, written consent of the author. Bundling for academic or noncommercial use is permitted so long as the author is notified.
(.txt)