Zugg Software :: View topic

Posted: Fri Oct 29, 2004 10:37 pm

Since the move to the linux server, the online zMUD manual was broken (since it relied on some Windows-specific stuff). I've spent the last few days making heavy modifications to the Knowledge Base module of this new MX Portal web system. I have converted the zMUD Manual into this new format. You can view the manual at

zMUD Online Manual

or click the Home link in the forum toolbar above, then select Articles from the navigation box, then select the zMUD category and then select the zMUD Manual document.

The new document system creates "related topic" links in the column on the left "on the fly" and is much more flexible than the old help system. Over time I will be improving the categorization of various topics to make navigation easier.

Because there are over 500 topics in this manual, I haven't looked at each one manually yet. If you find a topic that has a formatting problem in the text, please post here or send me an email message and I'll try to get it fixed. Conversion from the HTML generated by the old ForeHelp system into the BBCode used in the forum and Knowledge Base was pretty tricky, so I'm sure there are some weird things on some pages.

One very nice side benefit of this conversion is that you can now easily create a link to ANY help topic in the manual in your forum post. To create a Knowledge Base link in your forum post, use the syntax:

[[article_key]link text]

where article_key is the title of the article or the ID field of the article. link text is the text that you want to show as a link. You can leave out the link text and it will use the article_key as the text.

For example, to create a link to the #TRIGGER command in the help file, use the syntax: [[#TRIGGER]] and it will show up like this: #TRIGGER

Commands start with # and functions start with %. Here is a link to the %roomname function using the optional link text. The syntax is: [[%roomname]Room Name] and the result is: Room Name

This feature should make it a lot easier for the Gurus and other people answering posts in the forum to give links directly to the zMUD help file.

Coming soon is a full-text search engine for the knowledge base (and will also improve the Forum search function)!

Wizard Joined: 15 Jan 2002 Posts: 1644 Location: USA

*Drool* Worship Zugg
Now THAT is awesome

*wonders* Now if we can get Rorso to incorp that in his bbcode syntax highlighter we would be able to click on any command or function in a script and view the help file for it :P

Apprentice Joined: 26 Oct 2004 Posts: 108

Upon Entering that link: http://forums.zuggsoft.com/mx/modules/mx_kb/kb.php?mode=doc&index=zMUD_Contents

I tried to click on the Command reference link: http://forums.zuggsoft.com/mx/modules/mx_kb/kb.php?mode=doc&index=zmud_Reference

And I get this message:

Article doesn't exsist

Click Here to return to the Knowledge Base

Click Here to return to the Index

Same goes for Function Reference

Wizard Joined: 15 Jan 2002 Posts: 1644 Location: USA

He is referring to the one that is at the bottom of the right column, so far I havn't come across any problems using the related links column.

The Related link to the file ishttp://forums.zuggsoft.com/mx/modules/mx_kb/kb.php?mode=doc&k=233

SubAdmin Joined: 18 Nov 2001 Posts: 5187

Wow that turned out really nice. Might almost be worth it to abandon the old the help system entirely.

Wizard Joined: 14 Oct 2000 Posts: 1368

Posted: Sat Oct 30, 2004 6:18 pm

I think the offline and online help files serve two different purposes. As Rorso mentioned, some people like to look at it offline, and also the offline help file integrates nicely with zMUD using the F1 key.

But let's face it...the offline manual is a pain to update. Vijilante has done an amazing amount of work on it, but since the application we used to create the offline help file no longer exists, that really limits what we can do without starting over.

The online manual is going to be a lot easier to keep up to date. For example, once it's all working, Gurus will have edit access and will be able to fix typos, add examples, etc. Also, you'll notice that the Knowledge Base allows you to comment on articles. Like with the online PHP manual, this will give a place where any user can post tips or additional information about a topic. And, of course, the Related Topics section is a lot easier to handle dynamically on a database driven site like this.

So, the offline manual is pretty much fixed and static and will slowly get more out of date. The online manual will always have the most current information and will have more examples and tips from other users.

Both serve a purpose. Would I give up my paper PHP O'Reilly Manual in favor of the excellent online PHP reference? Nope. Sometimes I like using the book and sometimes I like going to the online site.

Now I'll go take a look at those link problems you reported.

Wizard Joined: 14 Oct 2000 Posts: 1368

Posted: Sat Oct 30, 2004 9:50 pm

No, it's not nearly that simple. To create Windows HLP files and HTML files from the same source you need a real help authoring tool. Back when the zMUD help was written, the .CHM help format didn't exist. I needed a tool that could do WYSIWYG editing of a single source file and then generate HLP, HTML, and RTF from that source. I ended up buying ForeHelp HTML from ForeFront Inc. It was an excellent tool at the time and much less expensive than the RoboHelp competitor. It handled all of the hard stuff such as HLP contents and indexes, as well as supporting HTML styles for the HTM files. Remember, this was back in 1996 or so.

Once I started using that tool, there was really no easy way to get out of it. The ForeHelp program stores the source in it's proprietary format. When ForeFront went out of business, I had not yet upgraded to the latest version of ForeHelp. Vijilante found a cracked version of the latest version on the Web, which we started using so that we could exchange compatible data files (I don't consider this software piracy since the company is out of business. I'd pay for the new version if I could, but there is no way to do that).

So, editing the existing offline help file requires a copy of ForeHelp HTML v5.

The HTML files generated by ForeHelp, as I have found recently, are a real mess. There is no way to directly import them using HtmlHelp Workshop to create a CHM file. And as I mentioned, zMUD itself is set up to use a HLP file, *NOT* a CHM file. So, until that part of zMUD is rewritten, I'm stuck with the HLP format for the offline file.

Now that I've converted all of the HTML files from ForeHelp into BBCode for the forum and knowledge base, it's probably a lot easier to just take those files out of the database and convert them back to simple HTML. That's my current plan for how to make a .CHM file in the future. I'll use the source files from the database on this web site as the *master* files and convert them, rather than trying to use ForeHelp anymore.

Yeah, if you haven't messed with Windows Help files, it's a real mess, and a lot of companies charge a lot of money for quality tools to handle all of this. I'm much happier now that I can just edit the help files directly from the web site interface.

SubAdmin Joined: 18 Nov 2001 Posts: 5187

Since that is the plan I will transfer over all my recent edits in the new manuals. Might take me a little while to figure out how it all goes together, but I am sure I will figure how to add in topics like that Advanced DB thing I was working on.