Improved Help File (UNofficial)

[CyberSlug]

I'm in process of defining a text format for documentation pages of functions in the help file.

Here's an example "proof of concept" where the script generated the htm file from the txt file. Shortly, I'll make the script parse a list of files (instead of a static filename) similar to JdeB's scripts.

In addition to enforcing consistent html code, documentation editing and maintenance should be easier (at least for me).

With the help of some other scripts, I expect to have a "rebuilt" help file sent to Jon by the weekend.

Edited January 20, 2004 by CyberSlug

[CyberSlug]

Update on my progress: I'm about half-way through the functions. I've discovered numerous "copy-and-paste" bugs and spelling errors that crept in when I first started the unofficial docs. I hope this second pass thru the docs will eliminate all the bugs

By the way, I'm consolidating the "Return Value" and "Error Flag" sections. Here's an excerpt from ControlGetPos:

[b]Return Value[/b]
    Success:  Returns an array containing the control's position and size relative to its window.
    Failure:  Returns numeric 1 and sets @error to 1.

Expect a post in a day or so.

Edited January 22, 2004 by CyberSlug

[Jos]

Just update the update_help_file.au3 script and made it available on http://groups.yahoo.com/group/AutoItList/files/AU3/MISC/.

It will now also generate the libfunctions.htm for the helpfile which contains the INCLUDE functions.

[CyberSlug]

I've got an update to post!

But it's still beta; I need to go thru and make sure examples are properly tabbed, that syntax specs correctly have brackets around optional parameters, and that links spelling are all correct.

I still have to add changed to macros and keywords; and to MsgBox...

But please take a look at the Beta.chm and the txt2htm.zip

If you find significant bugs in functions, just give me the name and I'll look at it.

With your help pointing out bugs, I'm thinking I'll be ready to submit the changes to Jon on Monday.

[Jon]

Looking good, just had a quick look.

1. Can you make the If Then type keywords bold (the bits in the yellow box - see my last helpfile).

2. If you click on a function directly from the functions.htm page it shows up without the css styles, if you click from the contents it's fine

3. Can you put the examples in the "code" style like the examples at the end of a function page.

Off to look some more.

[Jon]

Heh, that txt2htm script is pretty sweet too - it will certainly give AutoIt a workout.

[Jon]

At the top of the generate htm function there is a double paragraph around the description:

<p><p>Sets the Volume Label of a drive.</p></p>

[Jos]

Looks like this is going to work well... nice job ..

2. If you click on a function directly from the functions.htm page it shows up without the css styles, if you click from the contents it's fine

The reason for this is because the links have a "\" in the url ::/html/functions\AdlibEnable.htm in stead of ::/html/functions/AdlibEnable.htm.

Just run it though the script update_help_file.au3 and it will fix it.

You are mising the new section called "Library Function Reference" which was introduced in the last helpfile.

[CyberSlug]

I haven't touched the keyword sections yet; but that's my next step as I improve txt2htm.

Also, I'm getting the filenames and locations consistant with what Jon uses in his help file source.

Jon, what is the plan with the Library Function Reference, i.e., what will its links point to?

[CyberSlug]

Another update!

I still have a lot of small things to check in functions (such as MsgBox documentation), but here are the highlights:

- Improved txt2htm: Handles Keyword txt documentation and even does a little error checking!

- Keywords and macros should be up-to-date (AutoIt 3.0.91)

- file organization follows what Jon was using

it's the 25Jan stuff

Note: The help file compiles with warnings; I need to replace some greater-than signs in the PixelSearch Examples with the &gt; html-equivalent thingy. But it's bedtime.

Edited January 25, 2004 by CyberSlug

[CyberSlug]

Update to 3.0.91! the Jan27 stuff

I think it looks good. Please take a look; fresh eyes may uncover bugs!

All function and keyword pages were generated with the script txt2htm.... See the file contents for info on how to use. I should probably explain it a bit more, but documentation isn't my strong suit

To do: Update MsgBox docs; and update FileGetTime once Jon fixes it I also forgot to add FileSetAttrib to the table of contents and index, but you can find it with "search".

BTW: The Related links sections do not contain the words "See Also", but this can easily be added to the txt2htm script.

Edited January 27, 2004 by CyberSlug

[Jon]

I think it's excellent. Great use of the spashtext function

Can you just do a couple of tweaks:

1. Move usingAutoit.htm into /intro/

2. Have the scripts generate the files into the final html locations - I generated the functions and then moved up the directory to see where they had gone then when I went back into the .txt directory they were all mixed up with the text files - a FileSelectFolder dialog or something to ask for the output path (or prompt for function/keyword operation and assume the path is ../../html/xxxx would be quicker)

Awesome work, I get chills when I see scripts like that working in something I wrote

[CyberSlug]

Thanks, Jon. I'll also have some spelling fixes (thanks JdeB).

Yeah, I will change the default path. I was unsure of how to handle that. In the mean time, you could change the update.lst file to have the fully qualified path name.

[CyberSlug]

Okay, new version Jan28 stuff finally uploaded; webserver was acting up. Paths are read from a txt2htm.ini file which you should modify to contain the absolute file directories....

Jon, I'm not sure about the intro folder--I think there is an extra/duplicate file....

I updated MsgBox docs and a few other bug fixes. I'll need to look at file/folder copy stuff though.... I was certain directory recursion worked in older betas.....

Edited January 28, 2004 by CyberSlug

[sl_alagappan]

Hi,

Note in the v.91 help file, under Library Function Reference, the text says "Click on a function name for a detailed description." whereas the links are not there to click.

fyi pl.

[Jon]

Hi,

Note in the v.91 help file,  under Library Function Reference, the text says "Click on a function name for a detailed description." whereas the links are not there to click.

fyi pl.

Not written yet.

[Jon]

Okay, new version Jan28 stuff finally uploaded; webserver was acting up.  Paths are read from a txt2htm.ini file which you should modify to contain the absolute file directories....

Everything looks good to me.

[Jos]

Jon, what is the plan with the Library Function Reference, i.e., what will its links point to?

just sent an email to <email> and your Yahoo account that contains a script which will generate this page for you and a link to a page with the descriptions from the include files.. see what you think...

Jon edit: Eeek, no don't write out email adresses normally, the spambots...the spambots!!!

Edited January 28, 2004 by Jon

[Nutster]

Help on the help file is much appreciated as Larry and I _really_ hate documenting... 

I am not such a fan of writing documentation either, but I find it is a necessary evil of writing programs. I am very glad to have CyberSlug, ScriptKitty, et al taking care of this for us.

[CyberSlug]

I am very glad to have CyberSlug, ScriptKitty, et al taking care of this for us.

Don't forget JdeB He's the reason the help file has an index.