A fledgling FAQ for JafSoft text conversion utilities

The latest version of these files is available online at http://www.jafsoft.com/doco/docindex.html


    Next page

1.0 Introduction
1.1 Document conventions
1.2 Finding JafSoft software on the web
1.2.1 The home page
1.2.2 Online documentation
1.2.3 Keeping track of updates
1.2.4 Who is the author?
1.2.4.1 John A Fotheringham
1.2.4.2 JafSoft Limited
1.2.4.3 Contacting the author
1.2.5 Reporting errors and bugs
1.2.6 Requesting changes to the software
1.3 Registration and updates
1.3.1 Registration
1.3.2 Update policy
1.4 Other related products by the same author
1.4.1 AscToTab
1.4.2 AscToRTF
1.4.3 AddLinx
1.4.4 API versions of the software
1.4.5 Linux versions of the software
1.5 Document conversion consultancy
1.5.1 Do you offer consultancy?
1.6 Y2K Compliance
1.7 Status of this FAQ
  2.0 Getting the best results
2.1 General
2.1.1 Three words: consistency, consistency, consistency
2.1.2 Make sure your files are "line-orientated"
2.1.3 Make sure your use of tabs is consistent
2.1.4 White space is your friend
2.1.5 Use a simple numbering system
2.1.6 Save policies into a policy file
2.1.7 Add preprocessor commands to your source file
2.2 Using policy files
2.2.1 Saving "incremental" policies
2.2.2 Editing policy files by hand
2.2.3 Using include files in policy files
2.2.4 Using a default policy
2.3 Using preprocessor commands
2.3.1 What is the preprocessor?
2.3.2 Delimiting tables, diagrams etc
2.3.3 How do I add my own HTML to the file?
2.3.4 Using standard include files
2.3.5 Adding Title, keywords etc
2.3.6 Adjusting policies for individual files or parts of files
2.4 Making the program run faster
2.4.1 Review the "look for" options
2.4.2 Don't convert URLs
2.4.3 Don't generate tables
  3.0 Conversion Questions
3.1 General
3.1.1 How do I get rid of the "nag" lines?
3.1.2 My file has had it's case changed and letters replaced at random by numbers. How do I fix that?
3.1.3 Why do I sometimes get <DL> markup? How do I stop it?
3.1.4 Why are some of my words being broken in two?
3.1.5 Why am I getting line breaks in the middle of my text?
3.1.6 Why isn't the software preserving my line structure?
3.1.7 Why am I getting lots of white space?
3.1.8 What's the largest file anyone's ever converted with AscToHTM?
3.1.9 Does the software support hebrew letters / Japanese / Right to Left Alignment ?
3.1.10 Why does the program hang after a conversion?
3.2 What the software can't do
3.2.1 Why doesn't it convert Word/Wordperfect/RTF/my favourite wp documents?
3.2.2 How can I use DDE with Netscape 6.0?
3.2.3 Can I use AscToHTM to build a web site with a shopping cart?
3.2.4 How do I interrupt a conversion?
3.3 Tables
3.3.1 How does the program detect and analyse tables?
3.3.2 Why am I getting tables? How do I stop it?
3.3.3 Why am I not getting tables?
3.3.4 Why do my tables have the wrong column structure?
3.3.5 Where did all my table lines go?
3.3.6 How can I get the program to recognize my table header?
3.3.7 Why am I getting strange COLSPAN values in my headers?
3.4 Headings
3.4.1 How does the program recognize headings?
3.4.2 Why are my headings coming out as hyperlinks?
3.4.3 Why are the numbers of my headings coming out as hyperlinks?
3.4.4 Why are various bullets being turned into headings, and the headings ignored?
3.4.5 Why are lines beginning with numbers being treated as headings?
3.4.6 Why are underlined headings not recognized?
3.4.7 Why are only some of my underlined headings not recognized?
3.4.8 How do I control the header level of underlined headings?
3.4.9 Why are only the first few headings are working?
3.5 Hyperlinks
3.5.1 Why doesn't it correctly parse my hyperlinks?
3.5.2 Why doesn't it recognize my favourite newsgroup?
3.5.3 Why are only some of my section references becoming hyperlinks?
3.5.4 Why are some numbers becoming hyperlinks?
3.5.5 Why are some long hyperlinks not working?
3.5.6 How do I preserve one URL per line?
3.6 Policy files
3.6.1 How many policies are there? Where can I read more about individual policies?
3.6.2 My policy file used to work, but now it doesn't. Why?
3.6.3 xxxx Policy is not taking effect. What shall I do?
3.7 Bullets and lists
3.7.1 Why is the indentation wrong on follow-on paragraphs?
3.7.2 Why is the numbering wrong on some of my list items?
3.7.3 Some of my text has gone missing. What happened?
3.8 Contents List generation
3.8.1 How do I add a contents list to my file?
3.8.2 Why doesn't my contents list doesn't show all my headings?
3.8.3 Some of my contents hyperlinks don't work!
3.9 Emphasis
3.9.1 Why didn't my emphasis markup work?
3.10 Link Dictionary
3.10.1 What is the Link Dictionary?
3.10.2 My links aren't coming out right. Why?
3.10.3 I can't enter links into the Link Dictionary. What gives?
3.11 Batch conversion
3.11.1 How do I convert a few files at once?
3.11.2 How do I convert lots of files at once?
3.11.3 What's the most files I can convert at one go?
3.12 File splitting
3.12.1 Why isn't file splitting working for me?
3.13 Miscellaneous questions
3.13.1 How do I suppress the Next/Previous navigation bar when splitting a large document?
3.13.2 Why am I getting regions of <PRE> text?
3.13.3 Do you have a html-to-text converter, rtf-to-html converter etc?
  4.0 Adding value to the HTML generated
4.1 Adding Title and Description and Keyword META tags
4.2 Adding other META tags
4.3 Adding Headers and Footers
4.4 Adding Javascript
4.5 Adding colour/color
4.6 Adding images to the HTML
4.7 Adding hyperlinks to keywords and phrases
4.8 Splitting large documents into sections
4.9 Customizing the HTML created by the software
  5.0 Diagnosing problems for yourself
5.1 Generate a .lis file
5.2 Generate a .log file
5.3 Generate a .pol file
5.4 Understanding error messages
5.5 Diagnosing table problems
  6.0 Future directions
6.1 RTF generation
6.2 Multi-lingual user interface
6.3 Improved standards support
6.4 Targeting particular HTML versions
6.5 CSS and Font support

1.0 Introduction

This FAQ is clearly a work in progress. Many of the subjects have no answers as yet. Nevertheless I intend fleshing this out as and when I get time, and I welcome new questions (or prompts to write the answers to questions listed here) for all users.

Direct all correspondence to info<at>jafsoft.com


1.1 Document conventions

Often the answer to a question involves setting a policy value (see the "Policy Manual" for more about policy files). The policy involved will be displayed as

<policy text> : <value>

The <policy text> is the text that will appear in the policy file. This must be exactly as shown, no variability in the spelling will be tolerated by the program. If you misspell the policy text (or if it's been changed in a new version), the program will complain that it doesn't recognize the policy.

In addition to adding lines to your policy file by hand, the Windows version allows most (not all) policies to be set via property sheets. You'll need to locate the equivalent policy on property sheets.

More details on policies can be found in the Policy Manual which is included in downloads, but may also be found online at

http://www.jafsoft.com/doco/policy_manual.html


1.2 Finding JafSoft software on the web

1.2.1 The home page

Currently http://www.jafsoft.com/. Each product has it's own page, e.g.

http://www.jafsoft.com/asctohtm/
http://www.jafsoft.com/asctortf/
http://www.jafsoft.com/asctotab/
http://www.jafsoft.com/addlinx/

These are are listed on the products page

http://www.jafsoft.com/products/

There is also a .co.uk mirror site.


1.2.2 Online documentation

Currently http://www.jafsoft.com/doco/docindex.html. Documentation is usually included with all downloads, either as HTML or as ready-to-convert text.

In Windows this will usually be found in the folder c:\Program Files\JafSoft\AscToHTM

Documentation available includes :

If you plan to read one or more of these manuals you'd be best advised to download one of the documentation .zip files.


1.2.3 Keeping track of updates

There are update pages at

http://www.jafsoft.com/asctohtm/updates.html and http://www.jafsoft.com/asctortf/updates.html

Registered users get update notifications by mail. To date all updates have been free to registered users, but we can't guarantee that will always be the case.


1.2.4 Who is the author?

1.2.4.1 John A Fotheringham

That's me that is. The program is wholly the responsibility of John A Fotheringham, who maintains it in his spare time. He doesn't make enough to make a living from it (in case you were wondering).


1.2.4.2 JafSoft Limited

Although authoring shareware doesn't earn enough that I can give up my day job, I have created a separate company to handle AscToHTM, AscToRTF and all the shareware and other services I have to offer.

The company is called JafSoft Limited, and the web site is http://www.jafsoft.com/


1.2.4.3 Contacting the author

Correspondence should be via email to info<at>support.com. Priority is given to registered users and people who want to pay for development [ :) ], however all correspondence will be answered.


1.2.5 Reporting errors and bugs

Despite the best of intentions, bugs do happen, and we're always grateful for anyone who takes the time to report them to us.

Please feel free to report all errors and bugs to info<at>support.com. When you do so please include

Please keep any source files small. If the source file is large, try to generate a smaller file that exhibits the same problem.


1.2.6 Requesting changes to the software

Feel free to send suggestions for enhancements/changes to info<at>support.com. A surprising number of features have been added this way although, naturally, I'm happy for people to think these were all my own ideas.

Minor changes may slip into the next release if I think they enhance the product.

Major changes to the software can be undertaken on a commercial basis by contracting my services from Yezerski Roper Ltd. This option is not for the faint hearted. Don't let the software's $40 price tag persuade you that that's anything but a bargain, my hourly rate is more than that amount, although I can do quite a lot in one hour :-)


1.3 Registration and updates

1.3.1 Registration

Registration can be completed online by visiting

http://www.jafsoft.com/asctohtm/register_online.html or
http://www.jafsoft.com/asctortf/register_asctortf.html

Registration is usually completed via a third party registration service (I use a couple) and an on-line download. The registration service will take your payment and then send you download instructions for a fully registered copy. The registration companies can accept payments using a number of methods, but the commonest is credit card.

We do not ship software on media at this time. We'd have to double the price and stop our free upgrade policy if we did. That said, one of the registration companies will put the software onto CD and ship it to you for an extra charge. As yet I haven't set this up, but if interested email info<at>support.com with details.


1.3.2 Update policy

To date all updates have been free to registered users. This has been true for both minor and major updates. Over time the price of the software has risen, but no-one has ever had to pay extra.

I'd like to continue this policy, but I'm unable to actually guarantee this, especially since I've discovered old registered versions circulating on the Net.


1.4 Other related products by the same author

1.4.1 AscToTab

AscToTab is a subset of AscToHTM which is dedicated to creating tables from plain text and tab-delimited source files. The software is offered as freeware under Windows and OpenVMS.


1.4.2 AscToRTF

AscToRTF is a text-to-RTF converter which uses the same analysis engine as AscToHTM, but which creates Rich Text Format (RTF) files instead. RTF is a format better suited for import into Word and other word processors.

AscToRTF was released early in 2000 and has received a number of 5-star reviews.


1.4.3 AddLinx

A registered user (see "requesting changes to the software") contacted me and asked if I had a program that could add hyperlinks to an existing HTML file. At the time I didn't, but on examining the software it seemed I had all the bits and pieces necessary to construct such a tool. Within 24 hours I sent him a first attempt at such a utility, and within a few weeks [AddLinx] was born.

It's a very rough utility that I haven't spent much time on. It's available as postcard ware.


1.4.4 API versions of the software

For those wanting to programmatically integrate the conversion software into their own products, an API has been produced and is available under license.

AscToHTM and AscToRTF are written in C++, and an API is available which provides a C++ header file defining the functions available. The software is then provided as a Windows library to be linked against.

In the past clients have successfully integrated this with their Java software, on Windows, Linux and Solaris platforms.

Although I'm not a Visual Basic programmer myself I'm less sure of how the software could be integrated with VB, although I presume this can be done.

Contact info<at>jafsoft.com if interested.


1.4.5 Linux versions of the software

Linux versions of all programs are planned. The core conversion software is developed as a command line utility, and in this form it ports to Linux reasonably easily. I plan to offer AscToHTM and AsctoRTF as Linux shareware in the near future.


1.5 Document conversion consultancy

1.5.1 Do you offer consultancy?

We always like to offer a little help to users just starting out. Once you register you are free to send a typical sample file to the author, who will offer some advice on problems you might encounter and policies you may use.

However, for people wanting to do larger conversions (see "What's the largest file anyone's ever converted with AscToHTM?") or wanting significant amounts of our time, you will need to buy assistance at consultancy rates. Regrettably this is not cheap, although we feel it's good value for money :)

Contact info<at>jafsoft.com with details. See also "requesting changes to the software"


1.6 Y2K Compliance

From time to time I get asked if my products are Y2K compliant.

The short answer is "yes it was" :-)


1.7 Status of this FAQ

Clearly it's not finished yet. You might even say it's "under construction" :)

I've decided to put this on the web in "unfinished" form so that it may be of some benefit to people as soon as possible.

If you've a particularly urgent need for a question to be answered contact info<at>support.com, and don't be surprised if your answer ends up in this document.



    Next page

Valid HTML 4.0! Converted from a single text file by AscToHTM
© 1997-2003 John A Fotheringham
Converted by AscToHTM