I have started work on the MUSHclient Documentation Project (MDP), which is intended to do the following:
Be a total rewrite of the existing help file.
Document each command (as in the commands you can use DoCommand for). Commands are effectively:
Menu items (eg. Connection -> Quick Connect)
Keyboard accelerators (eg. Ctrl+Shift+F12)
Both of the above
Document each dialog box (eg. Alias configuration editor)
Document general ideas (scripting, triggers, aliases, MXP)
Cross-reference things with each other - eg. if a command invokes a dialog box the dialog box is cross-referenced with the command, and the command to the dialog box.
Cross-reference script routines, where applicable, to things they affect (eg. AddTrigger to the triggers configuration).
To assist in this, I have programmatically generated a complete list of commands and dialog boxes, so that nothing is accidentally omitted, and am now going through and putting in descriptions for everything.
The original help file was done using the Microsoft help file format (involving RTF files and a lot of mucking around), which was quite tedious to edit.
The new version is being done on a database, so adding topics is simply a matter of adding new records, and then regenerating.
At the very least, I expect to generate a help file from this, probably in the Windows help file format, although I am interested in whatever CHM is.
Also it will be quite feasible to put an online version on the web site if anyone would be interested in that (using dynamically generated pages, from the raw database information).
I would be interested to hear comments from MUSHclient users about what they would like to see (apart from accurate documentation!), such as ...
Online help (on web site)
Offline help (Window help file)
Offline help (static web pages, to be browsed offline)
Some other version (eg. TexInfo, PDF file, etc.)
Your comments will help me focus energy on the area which is most desired.
Also I am interested in expressions of interest to "beta test" the new manual. Probably the easy thing would be to make the online version available, so you can browse that. Once errors and omissions have been fixed up, a static help file can be generated and made available.
I would like to see a .chm helpfile, which is ridiculously easy to do, as long as all the help topics are in html, which should be easy to export from the DB you are building. I can send you the link for the html help workshop from microsoft's site.
Sign me up for any beta testing you want to do :p
Generating HTML is simple enough. I am doing that to do my testing on my internal web site. Here is an example:
Dialog name
IDD_COLOUR_PICKER
Title
Colour picker
Description
This dialog box provides a handy colour picker, to help choose colours for triggers, MXP programming, and generally throughout the program.
Colour list
This shows all of the internal colours, sorted into various sequences (controlled by the Sort combo-box). The default is Hue, which groups related colours (eg. the reds come together).
Underneath that is the currently-selected colour's name, which you can click on and copy. If this box is blank, then the current colour does not have a matching name.
Select a colour in the list by clicking on the colour name (not the colour swatch).
MXP/HTML:
This is the selected colour code in MXP/HTML format (eg. for use in an MXP-enabled MUD, or on a web page).
Visual Basic:
This is the selected colour code in Visual Basic hex format (eg. for use in a VBscript program).
JScript/PerlScript:
This is the selected colour code in C format (eg. for use in a C program, Perlscript or Jscript).
Red:
The red component of the selected colour, in the range 0 to 255.
Green:
The green component of the selected colour, in the range 0 to 255.
Blue:
The blue component of the selected colour, in the range 0 to 255.
Hue:
The hue component of the selected colour.
Saturation:
The saturation component of the selected colour.
Luminance:
The saturation component of the selected colour.
Sort:
The sequence for sorting the colours in the colour list.
Copy MXP
Copy the MXP/HTML code for the selected colour to the clipboard.
Other colour...
Open the standard Windows colour picker for further colour selection.
Paste
If there is a valid MXP/HTML/VB/C colour on the clipboard, this button will be active. Clicking it will paste the colour code into the window, and the various boxes will adjust accordingly.
Close
Close the colour picker without copying anything to the clipboard.
Yes. CHM files are basically a sort of compressed version of HTML or something like that. While the concept is good, Microsloth has of course screwed it up though. Since it basically employs the same components as their browser they took the simple way out and used the IE core routines in the HTMLHelp program. This would 'seem' to make sense, but since the core routines employ the same app.navigate function for moving from page to page as IE does, if you accidentally code something wrong or ask it to load a page that still has the HTML extension it will try to connect to the internet, even if doing so is unecessary. To make matters worse, if you link actual online content into the help, meaning you intended for it to try to go online, then it will ignore whatever browser settings you use and try to open the new page in IE.
All in all, at least on 98, CHM was a good concept that was badly developed and more than a few applications have 'fixed' the problem by simply including there own built in browser function and showing help within that. Unfortunately more than a few take this innovation and screw it up even worse by only showing the initial page internally, then jumping to IE whenever someone clicks a link.
So for myself... Unless you can be 100% certain that my computer will remain offline when I am looking at help offline, I would prefer the old HLP style. This may be possible, since 'most' CHM files do seem to behave, though ironically the one for the MS Developement library that comes with VB6 didn't. It all comes down to 'if' it is tested completely and behaves itself. ;)
I have to agree with you though, that if you go for the HLP version, then the tools designed to 'help' you develope such files severely suck and make the process 10 times more confusing and 20 times slower than it should be. :(
Isn't there a setting in Internet Options where you can tell it to never ask to connect to the internet? Which solves that, at least.
I'd like to see it offline in some fashion, because I've been known to do things like running MU*s in Cygwin on my laptop while not online, to code and stuff, and I might have some reason to look something up while I did that. So... offline. And please, Nick, *not* in that color scheme, or my eyes will bleed!
I don't really know if I'll have the time to help test. Maybe. Will depend on stuff like whether I actually find a job anytime soon. :)
Yeah, I don't get that either... Just block it in your firewall, or don't allow it to connect, or something... Are you using dialup? I don't understand the whole "programs connecting to the net by themselves" thing...
Oh, and, Nick the documentation looks great... Although I think that the color scheme of this forum and the online documentation would look better... Those colors are kind of tiring to the eye...
The actual documentation is perfect, but I would like to know if there is a way for you to easily update the helpfile when you add new features (wouldn't want it to end up obsolete, like the current helpfile).
Well to Neva and Poromenos. Yes this is an issue with dial-ups. Basically, you either have the option to auto-connect whenever you are offline and something makes a request, which is not a good thing imho.
Or the second option is for it to display the connection dialog, but not dial. Some programs like WinMX are screwed in this respect, since it will try to pop open about 10-12 dialogs before giving up, then promptly crash if you try to close them all. This is thankfully a rare problem, but it is a pain in the rear. However seeing the dialog pop up when it shouldn't is another issue entirely. You shouldn't in a program that is designed to provide 'offline' help or content. Blocking it is a potential issue, since what do you block, IE, which is the 'core' of the programs or the programs themselves. Hard to say what some of these apps 'look' like to the firewall. Not to mention the problem of if blocking the 'access' will block the request completely and keep the dialog quiet.
The third option is what you meantioned, which is turning off the dialog. Not sure if this also disables the dial-up networking connection program, but that program sucks, since it doesn't provide connection data that can tell you 'why' something fails if you can't dial in. It basically only tells you 'dialing' or 'failed to connect', vanishing into the normal internet icon on the task bar if successful.
Of these options, 3 either won't do me any good, or is more of a problem than the few programs that don't work right. Option 2 is the best imho, since programs that incorrectly try to log in when you initial boot up the system and you are 'supposed' to be offline can't hijack things. Option 1 is simply a pain in the ass.
It is simple. Programs that do these things shouldn't. I see no reason for me to have to fix someone elses mistake by installing more stuff on my system or changing configuration options so that these programs don't do bad things when they shouldn't, but as a result, won't work right when they are 'supposed' to be doing those same things. You don't fix something by breaking it, nor will it get fixed if you shrug your shoulders and use it anyway. Unfortunately, sometimes there isn't a lot of choice. ;)
With the online portion of the documentation, you should allow additional user comments, much like the PHP and MySQL online manuals do. I've often found these user comments to be very helpful. For example, in a function, a user could add some tip or trick for use with that function, etc.
Good idea, Dave. I'll get it going first, and then add that option. I quite like the idea of "user examples" of how things can be done, in ways that perhaps I had never envisaged. :P
As for the colours, that was an experimental version, however it was trying to look like the yellow colour from the original Windows help files.
I think a .hlp file will be best, that doesn't try to connect to the Internet, and is quick, plus I already know how to make them from a script.
Obviously any static file will eventually become out-of-date, however what I envisage is that as new versions are released the online documentation will be updated, and a new help file generated (the offline version) from that. Thus it should stay up-to-date unless you happen to use an old help file with a new version, for some reason.
There is still a potential problem that documentation is corrected even without version releases (as happened recently) so the online version is likely to be slightly more accurate at any given time. However there should still be the option for an offline version to be made available on the web site for anyone who wants the absolute latest, so they can just download that.
Shadowfyr, as you put it, you're right, but if you completely disable automatic connecting (i am using this scheme), it still reports when you try to connect manually, you just have to enable "show info while connecting", and ignores any program that wants to connect to the web when you don't want to... Try it :p
Odd, i've used 9x for a LONG time, and what it doesn't have is an option to turn reporting OFF :p
It displays a box that shows connection progress, like, "Dialing..." "Verifying user name and password" and "Logging on to network"...
But we're way off topic here :p
Yes. But the manual dialer doesn't use that dialog. Or if it does, then I don't know how to get to it. That dialog only appears if have the setting to allow the OS to attempt a connection. If you set it to 'never' connect then the system ignores all requests that would normally cause that dialog to appear, thus you end up having to use the link found under 'Dialup Networking' in the start menu. That one only shows 'dialing...', or 'failed to connect' if something goes wrong.
The problem is that if you merely disable the auto-connect and don't turn of dial-up completely, then 'any' program that does an internet request triggers the normal dialog. Worse, in some cases if you hit cancel, then the OS refuses to show the dialog again for 'any' requests made by other applications either, at least until you use the Dialup Networking link and later log off again.
I really wish I could find some way to add a link to the normal dialog to the quick launch list, but if you can I have yet to find it. :p
Once again, that is what I did, but that won't give me the 'normal' dialog. It gives me an abreviated one that won't attempt to redial automatically if it fails an attempt.
well, the "normal" one, is IE's one, which has a log window... The other one has a label that displays progress... you can set redialing parameters if you open up dial up networking and click on, umm, a menu item :p I think it's settings, it's the only menu item that is specific to dial up networking (probably the "Advanced" menu). then, you click on settings, and set all the parameters you want. That should take care of the redial. Also, when it fails, it tells you i.e. "that computer is not compatible with the protocol" or whatever error message there is.
Hmm. Well, I am certainly glad MS decided to not provide a way to get to those settings, except through that entity. Even happier with the fact that it is an entity, not an actually file directory. Damn thing BSDes on me when I tried to open it. Unfortunately I have literally gigs of data I don't really feel like spending hour backing up, not the mention all the tweaks I would need to redo and the hours needed to reinstall all the damn security patches and upgrades that I would need if I considered this important enough to finally do a reinstall of the OS...
Like I said, having to break normal OS behaviour in order to fix something else that is already broken is not much of a solution. Especially when you have to rely on Infernal Exploder's good graces to attempt to fix it. lol