Topic: New HAT for AGS

[Monsieur OUXX]

Yes, a new HAT for AGS would be perfect.
And by HAT, I don't mean a head accessory, but a Help Authoring Tool.

At the moment, AGS is relying on the .CHM format, and it's fine, but it is becoming risky to rely on this any longer, because the very very old tool "hhc.exe" used to produce it is a bit unstable on Windows 7. Calin suggested to move forward in this thread.

Which of these HATs do you recommend? Pick one here: http://en.wikipedia.org/wiki/List_of_help_authoring_tools

The requirements are :
1) Preferably the output should be produced from one big text file containing just a few markers (at the moment the original help file is a .tex file)
2) It must offer those 3 functions : a "contents" section (where we can put selected articles on display, grouped by theme), an index (a list of all the important keywords) and a search function.

=============================

EDIT
Actually, Precision Helper looks perfect. It has the freeware license (see the details here) and can work directly from the .hhp file...

=============================

EDIT 2

Here are my first results with Precision Helper:


That's good enough except for the fact that the index is not sorted alphabetically. That's annoying but I'm pretty sure it can be fixed. I'll have a look at it later.
Oh, and the buttons are in French, but that's probably just a setting.

Test it on your own machine :

• html-based help version 0.9
• html-based help version 1.0 (fixes: menus in English, images no longer broken, Index in alphabetical order)
• html-based help version 1.1 (fixes: buttons "prev", "next" and "home" have their icons back)

[BigMc]

Please use something open source and cross-platform. It is advisable to generate the documentation of the scripting language from proper source code comments with a documentation generator like Doxygen or Natural Docs. Right now the documentation is generated from a TeX dialect that is only understood by the tool tex2rtf. tex2rtf was (as far as I know) only used by wxWidgets until recently. They migrated to Doxygen by adding the capability to output Doxygen syntax to tex2rtf. [1] I haven't found this code yet, but it was done by Hajo Kirchhoff [2], who could be asked for it if Doxygen would be considered.

[1] http://www.litwindow.com/Knowhow/wxDoxygen/wxdoxygen.html
[2] http://www.litwindow.com

[Monsieur OUXX]

It is advisable to generate the documentation of the scripting language from proper source code comments with a documentation generator like Doxygen or Natural Docs.

The thing with AGS is that the manual is not a "source code documentation" per se.
There are also plenty of hand-written articles (let's call them "white pages") about many topics. Is Doxygen designed for that?

And even when it comes to the classes documentation, I'm not sure the help is generated from the source code. It might be just typed in the .tex file. And in this case it might not be such a bad practice, as otherwise it would mean that the documentation should be typed deep into the C++ compiler...just for a few AGS sript functions... not very handy to edit.
 

[BigMc]

It is advisable to generate the documentation of the scripting language from proper source code comments with a documentation generator like Doxygen or Natural Docs.

The thing with AGS is that the manual is not a "source code documentation" per se.
There are also plenty of hand-written articles (let's call them "white pages") about many topics. Is Doxygen designed for that?

I know. It is possible, but it seems to me that separating the API reference and using something more suitable for the white pages is the common approach.

And even when it comes to the classes documentation, I'm not sure the help is generated from the source code. It might be just typed in the .tex file. And in this case it might not be such a bad practice, as otherwise it would mean that the documentation should be typed deep into the C++ compiler...just for a few AGS sript functions... not very handy to edit.

It is in the .tex file now, but it should be moved to and then generated from the source code. It's the easiest way to keep the docs up to date and it encourages proper comments, because the developer knows that his comments end up in the documentation. Typed deep into the compiler? The compiler is completely unimpressed by comments. There are more than 100 script functions and right now the reference looks like this. For comparison, something using Doxygen and Natural Docs.

EDIT: The Doxygen example looks like overkill, but OGRE has a massive API. I could image something like the Natural Docs example would work nicely for AGS. I don't know if Doxygen can be configured to produce something similar.

[monkey_05_06]

The thing about the AGS help file is that it's not just a documentation of the existing script functions, it's the help file for using the entire program as a whole. Scripting is such a big part of using AGS, I would say it would be detrimental to strip the "API reference" for the scripting language out from the documentation for the rest of the program.

Apart from the formatting of the individual pages though, I don't see the major differences between Natural Docs and this. (I linked to the wikified version because it better reflects the actual flow of the CHM file, which is where 99.9% of the time people are looking when looking in the manual.)

[Ghost]

AGS already has a function to send anonymus user info. Would it be possible to have a help file that can be updated and automatically downloaded? I agree with monkey that pretty much everything in the manual is useful and should be left in. But I'd like it even more if there was a way to add useful articles (I learned all about the way you write functions as part of a struct by looking how SSH's modules did just that, for example) quickly to the helpfile. Can that be done, and would it make sense?

Reading the manual is also increasingly strange because many commands still mention their 2.x forerunners. Could be a nice time to clean things up a little?

[BigMc]

But I'd like it even more if there was a way to add useful articles (I learned all about the way you write functions as part of a struct by looking how SSH's modules did just that, for example) quickly to the helpfile. Can that be done, and would it make sense?

That is called a Wiki. Transfering the documentation to a Wiki and maintaining and using it from there is also an option.

[Terrorcell]

Reading the manual is also increasingly strange because many commands still mention their 2.x forerunners. Could be a nice time to clean things up a little?

I guess that's mainly to help people with the transition from the 2.x commands to their 3.x equivalents.

That is called a Wiki. Transfering the documentation to a Wiki and maintaining and using it from there is also an option.

Maybe it's just me, but I quite like the ability to press F1 and quickly find a command or whatever. It seems much faster, and less effort, than opening a web page (unless the documentation was displayed from the help files, which would be alright I guess, but it may need online access?).

[Monsieur OUXX]

I'm not very fond of turning the manual into a Wiki. I mean, I have nothing against a separated Wiki (and why not put a link to that wiki in the manual), but at the moment what I like very much about the AGS manual is that it's offline. to make it a wiki, it would need to be online.

Reading the manual is also increasingly strange because many commands still mention their 2.x forerunners. Could be a nice time to clean things up a little?

I guess that's mainly to help people with the transition from the 2.x commands to their 3.x equivalents.

I think it's too early to clean everything up. It helped me a lot moving from the old sound system to the new sound system just 2 weeks ago. It also helps when you dig out an old module to the forum, designed for 2.7x, and decide to do a quick upgrade (old strings to new Strings, etc.). I don't find the overhead of "formerly know as" lines too annoying to watch.

About Natural Docs :
- the Index is just below the list of topics. I love the way it is at the moment (one tab for the white pages, one tab for the index). The Index in AGS is pretty big.
- Is it easy to programmatically open a help page (using a simple URL) on a given keyword? as you know, that's how the Editor's code does it at the moment, using Windows' built-in functions for .chm files. Old but efficient: You highlight a word, then you press F1, and then boom, the help opens directly on the right page.

[Ghost]

That is called a Wiki.

Sounds like witchcraft!  But what I meant is a physical file on MY computer that gets updated. It would maybe require yet another panel to rate and edit entries, though, so it's probably a silly idea.

[Monsieur OUXX]

what I meant is a physical file on MY computer that gets updated. It would maybe require yet another panel to rate and edit entries, though, so it's probably a silly idea.

I have nothing against your idea, but I think the ratio efforts/result would be pretty unbalanced. What you are suggesting is pretty much an offline Wiki that would get synchronized with the community (and potentially rated by it) whenever you finally go online. In other words, we'd need a "delayed conflicts resolution that's supposed to succeed in merging your changes even 3 or 4 years after you wrote the page and the current wiki doesn't look anything like it looked when you started changing the page, the page might even have disappeared". Phew.


EDIT: As of now, I'm going to have a closer look at the .tex file to see if it could be converted to something more mainstream.

[Snarky]

I would really like for one consistent help file (generated from the same source) available in complete form both offline via Help/F1 in chm format (which still works better than any of the newfangled help systems, as it is quick, simple and completely offline), and online in html format. The current online version seems like it's missing a lot (though it might just be that it's hard to navigate and find all the bits), and doesn't have the same search capabilities as the chm version.

Maybe the online version could have a way for people to comment on each entry, to provide additional help and offer suggestions for future edits. Or there could be a stable version and a wikified version. Changes to the wiki could then be verified and rolled back into the next release. But that might be overkill, since I'm guessing only few people would be making useful changes to the manual, and they could be authorized to edit the source directly instead.

In any case, version control is essential. We would want to be able to maintain multiple versions of the manual for the different AGS releases.

[Monsieur OUXX]

The current online version seems like it's missing a lot, and doesn't have the same search capabilities as the chm version.

Hey Snarky, could you clarify what online version you're talking about? Did you try the prototype I uploaded above? Give a specific example of how the .chm works better?
Also, for clarity's sake, please make sure you say "web-based" or "online" when appropriate. It can be web-based AND offline.

There could be a stable version and a wikified version. Changes to the wiki could then be verified and rolled back into the next release.

Yes, sounds like a good idea. Provided we have an offline web-based manual, at the bottom of each page there could be a link "see the same article on the online wiki for latest updates on this manual page.".

In any case, version control is essential. We would want to be able to maintain multiple versions of the manual for the different AGS releases.

Well, at least I think it would be good enough to add a little hidden tag at the beginning of each help section/page, saying what version it applies to. A simple Javascript addition in the source could allow the viewer to expand/collapse the sections he judges obsolete for his intended use. That would also solve Ghost's concerns about excessive overhead.

[BigMc]

Every Wiki can export to offline formats.

But for the API reference a Wiki is no good choice. The reference has to be edited at the same time as the code, otherwise the developer forgets it. On the other hand the reference must be available for multiple AGS versions at once, including the development version.

Is it easy to programmatically open a help page (using a simple URL) on a given keyword? as you know, that's how the Editor's code does it at the moment, using Windows' built-in functions for .chm files. Old but efficient: You highlight a word, then you press F1, and then boom, the help opens directly on the right page.

There's already a search function included in the Natural Docs pages. It should be easy to hook into that with a link including a keyword.

[Snarky]

The current online version seems like it's missing a lot, and doesn't have the same search capabilities as the chm version.

Hey Snarky, could you clarify what online version you're talking about? Did you try the prototype I uploaded above? Give a specific example of how the .chm works better?
Also, for clarity's sake, please make sure you say "web-based" or "online" when appropriate. It can be web-based AND offline.

I'm referring to this: http://www.adventuregamestudio.co.uk/manual/

I would actually argue that it can't be web-based and offline (you can only access the web when online), though it can be html-based or browser-based and offline. In any case, I used the words I meant to use. There should be an online version of the manual for viewing on the web and linking to when people ask coding questions etc, and an offline version for referencing when you're working with AGS and may not have an internet connection. This second version could in principle be CHM or HTML.

I just had a look at the version you posted, and it does a good job at mimicking the look, features and behavior of CHM (images are broken, though), so the only real benefits I see is that CHM doesn't require launching a web browser (which takes longer to load than the simple CHM viewer), and keeps everything in one file. On the other hand, a browser lets you do stuff like open multiple tabs, so there are pros and cons.

In any case, Precision Helper lets you export to CHM, so we could easily support both, no?

Regarding Wiki-ing the manual, I tend to think that the other idea I had - to have a comment thread under each entry (probably linked to forum accounts) - would actually be better.

[Monsieur OUXX]

I'm referring to this: http://www.adventuregamestudio.co.uk/manual/

Not very sexy indeed. This has to be upgraded soon :-)

I would actually argue that it can't be web-based and offline (you can only access the web when online), though it can be html-based or browser-based and offline

Yeah, yeah, I shouldn't have nitpicked on the terms, I got owned I meant browser-based indeed.

There should be an online version of the manual for linking to when people ask questions, and an offline version for working offline.

It would be very easily achieved with the prototype I posted, as they are virtually identical.

images are broken, though

Good thing you said it, I didn't notice.

using a web-browser takes longer to load than the simple CHM viewer

Off we go embedding Midori in AGS. Relax, just kidding. what do people think about that? Would it be a real pain? Once your browser is loaded in memory it's not too long to open another page.

Precision Helper lets you export to CHM, so we could easily support both, no?

Yes, for the time being. the long-term goal is to get rid of the .chm format, which is unsupported for over 6 years now.

The idea to have a comment thread under each entry (probably linked to forum accounts)

...To forum accounts, or to forum threads?

[Snarky]

I meant that you'd need a forum account to post comments on the manual (much like you need to comment on games in the db). Each entry would in effect have its own forum thread.

My experience with the "more modern" help in programs like Word and Visual Studio is that it's not nearly as responsive and quick to navigate around as with good old CHM (while really not adding much at all), but this Precision Helper HTML build does seem much better.

[RickJ]

...But I'd like it even more if there was a way to add useful articles (I learned all about the way you write functions as part of a struct by looking how SSH's modules did just that, for example) quickly to the helpfile...

I don't think Ghost is talking about a wiki at all.  What's needed here is the ability to access multiple help files from the editor's menu.  If someone were to make a module they could also make a help file, perhaps using the same tools and methods use to make the AGS help file.  There would also be value in having tutorials and other supplemental docs as add on help files.  There would be help files that are present on every AGS project and there would be help files present on per project basis.  So probably the ones present on every AGS project would live with the editor install directory and the per project ones would live in the project directory.  Help files tied to a module would be available to every AGS project but only included if the project uses the module.   

Of course to manage everything there would have to be categories of help, both standard and user created.  This would require the AGS editor to support the concept of sub-menus.  Ohhh! if only someone would think to implement such a feature how sweet life would be . 

I don't like the idea of automatic updates to help files.  Although a manually initiated tool that could update one or all would possibly be useful.   

[Monsieur OUXX]

What's needed here is the ability to access multiple help files from the editor's menu.  (...)   There would be help files that are present on every AGS project and there would be help files present on per project basis.

I'm working on that atm. See this thread: http://www.adventuregamestudio.co.uk/yabb/index.php?topic=46219.0

[BigMc]

Of course to manage everything there would have to be categories of help, both standard and user created. 

Why do you want to split between standard and user created? That means the standard one gets less updated and users will start something new instead. And there will be overlaps. Why not one good documentation where everyone can contribute?

EDIT: Ok, for modules, but that is another problem than making contributing to the main documentation easier.