>2! 1 : Introduction  A 8
AscToHTM 

Documentation for the OAscToHTM conversion utility



9

This documentation can be downloaded as part of the  documentation set in .zip format (370k)




T Previous page $@ Back to Contents List#R Next page 


 "

1 Introduction

F

AscToHTM is an ASCII to HTML conversion tool. It has, of course,> been used to generate the HTML version of this document from the text file a2hdoco.txt (see an example conversion for more details).

F

The HTML version of this document is presented "as is". That is,U no post-production of the HTML has occurred. This should give you/ a flavour of what AscToHTM is capable of.



Any RTF version of this document will have been made by AscToRTF,C the sister product that shares the same text analysis engine.

B

AscToHTM is made available for download via the Internet from^ the download page.


 +

1.1 AscToHTM's design objectives

 $

1.1.1 Intelligent analysis.

J

AscToHTM is designed to analyse a document to determine its structureG and layout. This analysis allows AscToHTM to decide how best to markA up the HTML so as to accurately represent the author's original! meaning as far as possible.

I

This analysis helps AscToHTM to reduce errors by allowing it to spotD anomalies in the document source. This is important in minimisingD the amount of any post-production work required to fix errors.


 "

1.1.2 Human-readable HTML

G

AscToHTM tries to create HTML that can be easily read and modified@ in an editor. This is useful if corrections are necessary, or& further development is required.



For example AscToHTM



    
  1. < produces short (usually <80 character) output lines

  2. 
  3. B attempts to indent the HTML to match the output indentation.

  4. 
  5. > adds comments to the HTML to indicate include files etc.

  6. 
  7. K uses <BLOCKQUOTE> tags for indentation, rather than placing the8 whole file in <TABLE>...</TABLE> tags.

  8. 
  9. K produces "clean" HTML without large numbers of unnecessary tags.

N

Note, later moves to make more standards-compliant and browser-compatibleH HTML code tend to work against making user-readable code. For exampleJ most browsers have rendering problems when newline characters are placedJ in certain key locations, whereas adding newline characters can make the HTML easier to read.




1.1.3 Simple user input

I

Inevitably users have supply additional information to tell AscToHTME where its analysis has gone wrong and to add additional informationB such as a document title etc. AscToHTM offers a large number ofB options (also known as "policies") that the user can modify.

9

Broadly speaking, these policies fall into two camps


 
E

AscToHTM can save your policies to a file, so that next time youC run it you can load this information back from the "policy" file.D This also allows you to create different sets of policies (e.g. to$ use different colour schemes).

\

Policies are described fully in the Policy manual.

G

You can further refine the conversion by placing special lines andH tags into your source file. These are known as pre-processor commands (see Using the preprocessor) and in-line tags (see In-line tags).

b

The preprocessor tags are described fully in the Tag manual

I

To help users formulate and modify their document's policy, AscToHTMi can be made to create an output policy file (see 4.2.2.9).@ Users can then simply edit this file and feed it back into the conversion process.

q

A summary of the recognised policy lines is given in the Policy manual.


 $

1.1.4 Standards compliance.

C

Earlier versions of AscToHTM (before version 3.2) made no realD attempt to be standards compliance. Now standards compliance is aI stated goal or the program. Sadly I can't guarantee standardsF compliance because the HTML generation is so complex that errors canN and do occur, but it is a goal, and usually documents will validate with few problems.

J

Compliance has proved to be vital to get cross-browser compatability,J and to stand a chance of successfully applying CSS to created pages.

G

Original versions of AscToHTM were (loosely) targeted at producing HTML 3.2 code.

C

Currently the software is targeted at "HTML 4.0 Transitional",J which allows CSS, but also permits <FONT> tags (although these areD deprecated). This is a compromise standard that is best placed to+ be well viewed by V3 and V4 browsers.

D

Future versions of the program may attempt to generate stricter? HTML 4.0 code, while still offering production of the earlier HTML standards.

t

The policy "HTML version to be targeted" offers9 some ability to choose the style of HTML generated.


 (

1.2 Expected uses of AscToHTM

 
E

Plain text is still a very popular data format. It is easy toF generate, and easy to read. However text files when placed on theD web don't look as nice as normal web pages. AscToHTM will allowD you to quickly add the HTML markup required to turn a plain textC page into a nice looking HTML page. Because it is an automatedH conversion it will save you time, and ensure you avoid typos in HTMLJ tags that could stop the page displaying wrongly in some web browsers.


 
F

Large amounts of unconverted text exist. As people plan to putN this information on the Web, conversion to HTML will become necessary.

L

This can be a tedious and time-consuming task. AscToHTM will do much of the work for you.

B

AscToHTM is priced to be worth an hour of two of your time.K This means that the "pay back" time is negligible (we only mention thisF in case you have bean-counters to convince :). If you don't thinkA AscToHTM will save you hours, then by all means don't buy it.


 
M

The HTML created by AscToHTM may not be as pretty or as clever as thatB generated by a full blown HTML editor (read as "bloated").



But...

H

It'll be easier to write, edit and spell-check, and it may have a( hyperlinked contents list generated.


 
H

AscToHTM can be used to automatically convert text documents thatE you receive. For this we usually suggest you run in command line mode.


 
I

Many people have legacy systems that generate printed reports thatC may be saved to file. AscToHTM can help extend the lifetime ofC such systems by turning their output to HTML. It may be you'llB need some help in getting the best results from the program in= such cases, since many reports consist of complex tables.


 
L

Printer spool files are not strictly speaking plain text, but often -J especially in older software systems - these files are plain text withD a few printer controls added. Some users have had great successE converting such files using asctohtm, and to support this we haveC added a limited ability to recognise and strip out Unix controlG characters, VT escape sequences and PCL printer codes. If you havej a requirement in this area, contact the author at jaf@jafsoft.comG to discuss whether the software can be made to meet your needs.



 %

1.3 Other uses of AscToHTM

 
W

Please note, AscToHTM DOES NOT convert Word's .doc or .rtf file formats.

O

AscToHTM was never intended to handle Word documents. We fullyA expect HTML export and import filters to appear (they have inB Word '97), and we would advise anyone whose master document is@ in Word to search out these filters and give them a try.

D

That said... a lot of people seem unhappy with what's alreadyF available, and AscToHTM does a reasonable job if you save the fileJ as text with line breaks, though obviously tables and figures will getD lost (in the case of tables, because Word throws them away).

G

The main problem is that Word produces lousy looking text. ThisE is one area where AscToHTM does a little better than "garbage in, garbage out"


 
;

(This is a bit cheeky, but does actually work.).

G

Use AscToHTM to convert text to HTML, then import this into yourH word processing package. Since the text analysis engine in AscToHTMF out-performs that in Word in many respects (URL, table and headingG detection to name but three), you can often get better results than$ importing from text direct..

U

That's because AscToHTM's analysis engine is smarter. That's not just our view (see http://www.jafsoft.com/asctohtm/reviews.html)


P
NOTE:
The same text analysis engine is used in the text-to-RTFv program AscToRTF, which is more suited to this purpose.


 
E

Use AscToHTM to convert text to HTML, then print the file fromD within Netscape or whatever. The result is a much nicer looking document with fonts'n'stuff.


 
G

AscToHTM has a "link dictionary" feature that can be used to addb hyperlinks to any word or phrase (see the Policy manual).

H

This can greatly enhance an otherwise dull set of text pages.



 2


T Previous page $@ Back to Contents List#R Next page 


B& 
Valid HTML 4.0!Converted from 6 a single text file by A AscToHTM
J© 1997-2001 John A Fotheringham