Jump to content
Sign in to follow this  
CyberSlug

Improved Help File (UNofficial)

Recommended Posts

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 by CyberSlug

Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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 :whistle:

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 by CyberSlug

Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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.


SciTE4AutoIt3 Full installer Download page   - Beta files       Read before posting     How to post scriptsource   Forum etiquette  Forum Rules 
 
Live for the present,
Dream of the future,
Learn from the past.
  :)

Share this post


Link to post
Share on other sites

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.


Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.


SciTE4AutoIt3 Full installer Download page   - Beta files       Read before posting     How to post scriptsource   Forum etiquette  Forum Rules 
 
Live for the present,
Dream of the future,
Learn from the past.
  :)

Share this post


Link to post
Share on other sites

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?


Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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 > html-equivalent thingy. But it's bedtime.

Edited by CyberSlug

Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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 B)

To do: Update MsgBox docs; and update FileGetTime once Jon fixes it :whistle: 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 by CyberSlug

Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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

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 :whistle:

Share this post


Link to post
Share on other sites

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.


Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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 by CyberSlug

Use Mozilla | Take a look at My Disorganized AutoIt stuff | Very very old: AutoBuilder 11 Jan 2005 prototype I need to update my sig!

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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!!! :whistle:

Edited by Jon

SciTE4AutoIt3 Full installer Download page   - Beta files       Read before posting     How to post scriptsource   Forum etiquette  Forum Rules 
 
Live for the present,
Dream of the future,
Learn from the past.
  :)

Share this post


Link to post
Share on other sites

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

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.

David Nuttall
Nuttall Computer Consulting

An Aquarius born during the Age of Aquarius

AutoIt allows me to re-invent the wheel so much faster.

I'm off to write a wizard, a wonderful wizard of odd...

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this  

  • Recently Browsing   0 members

    No registered users viewing this page.

×
×
  • Create New...