Advice On Documenting Scripts.

[Bokkie]

I'm putting together a script library that will perform a number of permutation functions and I've probably got about 60% of the code written and tested. Eventually I'll put this into the scripts and scraps forum. By necessity I need to document the functions the .au3 file contains.

I see two ways going forward: I can place the documentation for the functions in the script file or I could create a Word document. If I place the function reference in the .au3 file then obviously it bloats the size of the file. If I put it in Word format then I guess most people have Word installed or at least have access to a machine where it could be viewed or printed?

I'm not too familiar with creating a web pages but I suppose I could throw something together that Firefox or IE could use. Are there any precedents as to what's the best method to adopt? Many of the scripts and scraps I've looked at have been small enough to self-document their concepts but what I'm putting together is better served by an explanation of what my functions do.

Comments?

Edited April 16, 2006 by Peter Hamilton-Scott

[MHz]

To consider.

A CHM file like AutoIt Helpfile uses:

NVU Html editor

A lightweight webpage creator which finished pages can be easily imported into Hmtl Help Workshop. It is as easy as typing into Word.

Hmtl Help Workshop

Creates a chm file from html and images. Forget the docs that are on the download page as they are complicated. It has a setup wizard that is easy to use.

A PDF file:

PDFCreator

Can print from any window application (including MS Word). Easy to view through FoxIt Reader or Adobe Reader.

A HLP file:

I would not bother. Support is low for creating a help file worthwhile compared to the above types.

Edited April 16, 2006 by MHz

[Bokkie]

MHz,

Is CHM the preferred style as that's what the documentation uses already and that's what we're familiar with?

Edited April 16, 2006 by Peter Hamilton-Scott

[MHz]

We are very familiar with it as it helps you when you script with AutoIt.

I just did this in a minute piece of time.

Sample.zip

[Bokkie]

We are very familiar with it as it helps you when you script with AutoIt.

I just did this in a minute piece of time.

Sample.zip

How did you create it? Did you use Nvu as you gave a link to it earlier. Sorry for coming across as a fool but I've never been down this road before.

[MHz]

1. I open a new file in NVU.

2. I typed that line.

3. I saved the file, with a title and filename.

4. I started Html HelpWorkshop

5. Clicked on new project which starts the wizard.

6. I create a new project file when asked.

7. I check the Hmtl checkbox as I have a Html page already to add, then browse and add.

8. Wizard finishes, and all I need to do is press save and compile.

You should have a Chm help file created. Each Html page you add is a new topic and can be added at anytime to continue building up your help file. Contents and/or Index is used once you have more then one page/topic for selection.

Have a play with it. It is very easy once you have used it once or twice.

[Bokkie]

Thanks MHz. I downloaded the utilities and there seems a lot they can do. Reckon I need to finish the code first and then do the paperwork.