WebDocBuilder

WebDocBuilder is a set of tools that make it easy to create both World Wide Web documents and SimpleText documents from the same source ClarisWorks 4.0 document. It is perfect for creating program documentation, where you want to include the documentation with the distribution and provide a copy of the documentation on the web.

Salient features include:

Using WebDocBuilder

Packing List

The distribution comes with the following files:

In addition you will need the following programs to use WebDocBuilder:

Installing the Bits

To install WebDocBuilder follow these easy steps:

  1. Move the TeachText/SimpleText XTND translator into the Claris Translators folder inside your Claris folder inside your System Folder.

  2. Move the WebDocBuilder Empty stationery into your ClarisWorks Stationery folder, in the folder that contains ClarisWorks 4.0.

  3. Place the rest of the distribution in a convenient location on your hard disk.

Creating a Document

Once you have installed the various pieces you can set about creating a document. Launch ClarisWorks and, in the New Document window, click the Use Assistant or Stationery check box (command-A is an equivalent to this) then choose All Stationery from the Category popup and double-click the WebDocBuilder Empty document. This creates on empty document suitable for processing by WebDocBuilder.

You can now type in your document, formatting it using the paragraph and character styles that are integrated into the WebDocBuilder Empty document. You can access these through the popup menu on the ruler or using the Stylesheet palette (choose Show Styles from the View menu to see this). You can also use the Shortcuts palette (choose Show Shortcuts from the Shortcuts menu on the File menu) to create horizontal lines and WWW links in your document.

When you save the document you should save it with no spaces in the name and make sure the name ends with ".cwk".

Processing Your Document

Once you have created your document you can process it into both a SimpleText and World Wide Web document by simply dropping it on to the WebDocBuilder application. The script launches ClarisWorks to create the World Wide Web documentation and the SimpleText document. If the source file was called "ReadMe.cwk" then the output is called "ReadMe" (the SimpleText document) and "ReadMe.html" (the World Wide Web document). If the document contains any pictures then they are extracted into separate files (called "ReadMe1.gif", "ReadMe2.gif" and so on) to be included with the HTML document.

Caveats

The following is a list of caveats and workarounds for WebDocBuilder.

Reference

This section describes each of the shortcuts and styles in the WebDocBuilder Empty stationery and how you should use them to build documents that look good on the web and in SimpleText. The section concludes with a description of some of the modifications you might like to make to the WebDocBuilder script.

Shortcuts

The stationery contains the following shortcuts:

Web Horizontal Line

This shortcut installs a horizontal line into your document, like the one shown below.


Web Link

This shortcut is useful for creating a WWW link in your document. To use it, first select the text you want to act as the anchor to your link then click on the shortcut. The shortcut changes the style of the anchor text to HTML Link then inserts a footnote that you should edit to contain the URL of the destination of the link.

Note that if you want the link to be effective in SimpleText then you need to include the URL in the text as well. For example this link to my home page cannot be seen in SimpleText, whereas this one can <http://www.AnarchistTurtle.com/Quinn/WWW/>.

Note: Because ClarisWorks is colossally stupid, you need to have the Stylesheet palette open when you invoke this shortcut.

Web Link (hidden Stylesheet)

This shortcut is identical to the Web Link shortcut except that it shows the Stylesheet palette beforehand and hides it afterwards.

Note: Because ClarisWorks is colossally stupid, you need to have the Stylesheet palette closed when you invoke this shortcut.

Paragraph Styles

The stationery contains the following paragraph styles:

Body

This is the standard style for paragraphs. Indeed this paragraph is in body style.

Close Body

This style is useful for text that is necessarily separated by hard returns but you wish to be spaced like a normal paragraph. In more technical terms, the standard Body style creates an HTML <P> tag at the end of the paragraph, while the Close Body style creates an HTML <BR> tag. For example look at the following snailmail address.

Quinn
4/15 Macleod Road
Applecross WA 6153
AUSTRALIA

Quinn

4/15 Macleod Road

Applecross WA 6153

AUSTRALIA

The first address is formatted with the close body style and looks substantially better in HTML.

Default, Footer, Footnote and Header

Are required styles in ClarisWorks. You can safely ignore them.

HTML Header X

Use these styles to mark section headers. You should use HTML Header 1 for the biggest header in your document and successively ascending numbers for sub-sections. Here is an example of each of these styles.

HTML Header 1

HTML Header 2

HTML Header 3

HTML Header 5
HTML Header 6

Note that HTML Header 4 is unavailable because of a limitation in the ClarisWorks WWW translator.

L1, L2 and L3

Use these styles for indented lists. There are two types of lists available in HTML, ordered lists and unordered lists. You can create lists by formatting each paragraph in one of these list styles and beginning the paragraph with either a bullet ( ) or a number followed by a full stop (1.). Here are some list examples.

Preformatted

Use this style to insert preformatted text into your documents. Preformatted text is text that was originally generated in a monospaced font. It is useful for inserting things like directory listings into your document. Here is an example:

H112936    LENINGRAD COWBOYS           LENINGRAD COWBOYS GO AMER
$25.95     CLODW   3/94   GERMANY

B131015    LENINGRAD COWBOYS           LIVE IN PROWINZZ
$30.95     ARIOL          HOLLAND

H187386    LENINGRAD COWBOYS           WE CUM FROM BROOKLYN
$25.95     ARIOL   3/94   GERMANY

Character Styles

The stationery contains the following paragraph styles:

HTML Strong

Use this to emphasise text in a big way. In a web browser this normally translates to bold. In SimpleText it appears as bold.

Example: These characters are formatted with HTML Strong.

HTML Emphasis

Use this to emphasise text in a more subtle way. In a web browser this normally translates to italics or underline. In SimpleText it appears as underline.

Example: These characters are formatted with HTML Emphasis.

HTML Citation

Use this when referencing a document. In a web browser this normally translates to italics. In SimpleText it appears as italics.

Example: These characters are formatted with HTML Citation.

HTML Literal Text

Use this style to insert raw HTML into your documents. Be careful with this because it allows you to generate illegally formatted HTML. Also in SimpleText this text appears in red Helvetica.

Example: These characters are formatted with HTML Literal Text.

HTML Normal Text

Use this style to revert to normal text in cases where the text would appear otherwise.

HTML Link

Use this style to denote the anchor text for an HTML link. This text will be specially highlighted by a web browser, usually with a blue underline. SimpleText will display the text with a blue underline. For an example, consult the previous section on the Web Link shortcut.

Modifying the WebDocBuilder Script

This section documents some of changes you might like to make to the WedDocBuilder script. If you make any changes to the script you should make them to the WebDocBuilder Text file and then use Save as to create a new application.

Changing the Default File Type and Creators

At the moment WebDocBuilder defaults to setting the creator of the output text to SimpleText (that is 'ttxt') and the creator of the HTML to MacWeb (that is 'MWEB'). You can change these by looking through the script for the keywords text_creator and web_creator.

Changing the GIF to PICT Processor

At the moment WebDocBuilder uses clip2gif, a simple Freeware program, to convert the PICT files into GIF files. You can change this by changing the lines associated with the gif_convertor and gif_convertor_launch keywords in the script.

Wrap Up

Version History

Version 1.0b1 is the first released version. Detailed release notes can be found in the AppleScript.

Credits

WebDocBuilder was created by Quinn "The Eskimo!" as a tool to help him in creating documentation for his programs.

Share and Enjoy.

Quinn "The Eskimo!"
<http://www.AnarchistTurtle.com/Quinn/WWW/>