Jibble

Author Topic: New HAT for AGS  (Read 12105 times)

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
New HAT for AGS
« on: 13 Jun 2012, 21:35 »
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)

« Last Edit: 15 Jun 2012, 11:56 by Monsieur OUXX »
 

Re: New HAT for AGS
« Reply #1 on: 13 Jun 2012, 23:04 »
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

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #2 on: 13 Jun 2012, 23:16 »
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.
 
 

Re: New HAT for AGS
« Reply #3 on: 13 Jun 2012, 23:51 »
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.

Quote
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.
« Last Edit: 14 Jun 2012, 00:06 by BigMc »

monkey0506

  • SEND PIZZA.
    • Best Innovation Award Winner 2017, for his work to help AGS games reach the widest possible audience - through popular distribution platforms (Steam, Galaxy) as well as other operating systems (Android, Linux)
    • monkey0506 worked on one or more games that won an AGS Award!
    •  
    • monkey0506 worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #4 on: 14 Jun 2012, 00:12 »
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

  • Guest
Re: New HAT for AGS
« Reply #5 on: 14 Jun 2012, 01:05 »
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?

Re: New HAT for AGS
« Reply #6 on: 14 Jun 2012, 08:22 »
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.

Re: New HAT for AGS
« Reply #7 on: 14 Jun 2012, 09:19 »
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

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #8 on: 14 Jun 2012, 09:22 »
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.

« Last Edit: 14 Jun 2012, 09:24 by Monsieur OUXX »
 

Ghost

  • Guest
Re: New HAT for AGS
« Reply #9 on: 14 Jun 2012, 09:22 »
That is called a Wiki.

Sounds like witchcraft!  ;-D 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

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #10 on: 14 Jun 2012, 09:28 »
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

  • Global Moderator
  • Global Moderator
  • Mittens Lord
  • Private Insultant
    • Best Innovation Award Winner 2018, for his numerous additions to the AGS open source ecosystem including the new Awards Ceremony client and modules
    • Snarky worked on one or more games that won an AGS Award!
    •  
    • Snarky worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #11 on: 14 Jun 2012, 10:12 »
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.
« Last Edit: 14 Jun 2012, 13:07 by Snarky »

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #12 on: 14 Jun 2012, 10:54 »
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.

 

Re: New HAT for AGS
« Reply #13 on: 14 Jun 2012, 11:19 »
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

  • Global Moderator
  • Global Moderator
  • Mittens Lord
  • Private Insultant
    • Best Innovation Award Winner 2018, for his numerous additions to the AGS open source ecosystem including the new Awards Ceremony client and modules
    • Snarky worked on one or more games that won an AGS Award!
    •  
    • Snarky worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #14 on: 14 Jun 2012, 11:37 »
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.
« Last Edit: 14 Jun 2012, 11:39 by Snarky »

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #15 on: 14 Jun 2012, 13:08 »
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?
« Last Edit: 14 Jun 2012, 13:10 by Monsieur OUXX »
 

Snarky

  • Global Moderator
  • Global Moderator
  • Mittens Lord
  • Private Insultant
    • Best Innovation Award Winner 2018, for his numerous additions to the AGS open source ecosystem including the new Awards Ceremony client and modules
    • Snarky worked on one or more games that won an AGS Award!
    •  
    • Snarky worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #16 on: 14 Jun 2012, 13:52 »
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

  • fix'n one thing and break'n two ...
    • I can help with scripting
    • I can help with story design
    • RickJ worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #17 on: 14 Jun 2012, 14:28 »
Quote
...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

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #18 on: 14 Jun 2012, 15:21 »
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

 

Re: New HAT for AGS
« Reply #19 on: 14 Jun 2012, 16:27 »
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.
« Last Edit: 14 Jun 2012, 17:02 by BigMc »

Ali

  • What will become of the baron?
    • Ali worked on one or more games that won an AGS Award!
    •  
    • Ali worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #20 on: 14 Jun 2012, 19:54 »
Whatever you choose, please use something that will allow users to search for symbols like "&&". In my early days of AGS, when I could never remember what logical operators were called, I could never find the pages about them!

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #21 on: 15 Jun 2012, 00:14 »
I posted version 1.0 of the html-based help (see first post of the thread). Fixed all known issues.
Who is the admin of the website? The old help could be immediately swapped; quick win!

Oh, and Ali, you'll be happy to know that you can search "&&" in it :)
« Last Edit: 15 Jun 2012, 14:26 by Monsieur OUXX »
 

Ghost

  • Guest
Re: New HAT for AGS
« Reply #22 on: 15 Jun 2012, 00:23 »
Downloaded and tested 1.0- looks comfortably familiar but navigates better.
Good job (says the n00b).

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #23 on: 15 Jun 2012, 11:58 »
I posted version 1.1 of the html-based help (see first post of the thread).


I repeat my question: Who is the admin of the website? The old help could be immediately swapped for a quick win!
« Last Edit: 15 Jun 2012, 14:26 by Monsieur OUXX »
 

tzachs

  • Mittens Vassal
  • AGS Baker
  • Parking Goat- games that goats like!
    • I can help with translating
    • tzachs worked on one or more games that won an AGS Award!
    •  
    • tzachs worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #24 on: 15 Jun 2012, 15:44 »
Just had a quick test of your manual, it looks great!
I support switching to it in the website.

monkey0506

  • SEND PIZZA.
    • Best Innovation Award Winner 2017, for his work to help AGS games reach the widest possible audience - through popular distribution platforms (Steam, Galaxy) as well as other operating systems (Android, Linux)
    • monkey0506 worked on one or more games that won an AGS Award!
    •  
    • monkey0506 worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #25 on: 15 Jun 2012, 16:10 »
Seconded. It does look pretty nice. Definitely much nicer than the current online manual, and it can of course be kept up-to-date automatically (one of the major lacking features of the wiki version).

Edit: One thing missing from this that's present in the CHM is that search terms aren't highlighted. Dunno if there's a simple way of doing that (haven't looked at how any of this is actually coded), but it makes the search far less usable than the CHM.
« Last Edit: 15 Jun 2012, 16:12 by monkey_05_06 »

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #26 on: 15 Jun 2012, 17:32 »
One thing missing from this that's present in the CHM is that search terms aren't highlighted. Dunno if there's a simple way of doing that (haven't looked at how any of this is actually coded), but it makes the search far less usable than the CHM.

Well, considering it's generated automatically, I'm very reluctant to add some coding to it. That would bring the project to a whole new level.
I agreed with what you say, but on the other hand, modern browsers make it very simple to search a word in a page/set of frames (I mean, now you don't have to select the correct frame beforehand, and you don't have to click "Find" after entering the keyword in the "search" box, like it used to be).
« Last Edit: 15 Jun 2012, 17:43 by Monsieur OUXX »
 

Crimson Wizard

  • Local Moderator
    • Lifetime Achievement Award Winner
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Crimson Wizard worked on one or more games that won an AGS Award!
    •  
    • Crimson Wizard worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #27 on: 15 Jun 2012, 19:07 »
That looks beautiful, but is it possible to add "quick-find" input box to the Index page that would scroll list down to the first match found?

Monsieur OUXX

  • Mittens Vassal
  • Cavefish
  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
    • Monsieur OUXX worked on one or more games that won an AGS Award!
    •  
    • Monsieur OUXX worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #28 on: 15 Jun 2012, 19:21 »
One thing missing from this that's present in the CHM is that search terms aren't highlighted. Dunno if there's a simple way of doing that

Well, considering it's generated automatically, I'm very reluctant to add some coding to it. That would bring the project to a whole new level.

Actually I've just tried, and it does highlight the searched word in the search results. Did I misunderstand what you meant?

@Crimson wizard: I keep your suggestion in mind, but I'd like to remind everyone that the main purpose of this thread is to first settle on a HAT that could allow us to walk away from the .tex format and the .chm format.
 

Re: New HAT for AGS
« Reply #29 on: 15 Jun 2012, 20:02 »
Why do you want to change away from .tex now? If you want the documentation source to be simple files (and not a Wiki or source code), TeX is a very good format for that. And it shouldn't be difficult to remove the tex2rtf specific stuff and use it as input for a different HAT.

Re: New HAT for AGS
« Reply #30 on: 16 Jun 2012, 12:06 »
I created a prototype to show that the Wiki can also be used to create something that can replace the chm. It's similar to output Monsieur OUXX created. These things are called "WebHelp".

I exported the articles from the Wiki as DocBook XML, which can be used to create WebHelp output. It's not polished, images are not included, etc but for that it would have to be polished in the Wiki. Since the content of the Wiki is outdated anyway, it may be best to reimport the whole documentation from scratch. As I already said, I don't think that the API reference should be generated from Wiki articles, but from source code comments.

Here is the download link to the prototype: http://netload.in/dateiQ3Q32BuD7k/wiki-webhelp.zip.htm

RickJ

  • fix'n one thing and break'n two ...
    • I can help with scripting
    • I can help with story design
    • RickJ worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #31 on: 17 Jun 2012, 19:53 »
Quote
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?
I am not advocating that the standard help file be split.   What I am suggesting is that there are other materials beyond the scope of the AGS Manual and that it would be useful if those materials could be made available in the same form as and from the same menu as the standard help file.   You concede the point about modules but how about such things as templates, tutorials, programming conventions?  For group projects there could also be project specific guidelines, storyboard, instructions and policy on archiving and repository submissions, etc.   

I don't see how any of that would fragment the AGS Manual.  A wiki on the other hand would do exactly that; over time the AGS manual would become fragmented, self inconsistent, less concise and less understandable.   Changes to the standard AGS Manual ought to go through the save review process and receive the same scrutiny as changes to the editor and engine code.       

« Last Edit: 17 Jun 2012, 19:56 by RickJ »

Re: New HAT for AGS
« Reply #32 on: 20 Jun 2012, 03:20 »
Quote
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?
I am not advocating that the standard help file be split.   What I am suggesting is that there are other materials beyond the scope of the AGS Manual and that it would be useful if those materials could be made available in the same form as and from the same menu as the standard help file.   You concede the point about modules but how about such things as templates, tutorials, programming conventions?  For group projects there could also be project specific guidelines, storyboard, instructions and policy on archiving and repository submissions, etc.   

I don't see how any of that would fragment the AGS Manual.  A wiki on the other hand would do exactly that; over time the AGS manual would become fragmented, self inconsistent, less concise and less understandable.   Changes to the standard AGS Manual ought to go through the save review process and receive the same scrutiny as changes to the editor and engine code.       

Stagnation?

Are you being ironical? The only thing that saved AGS are the unofficial forks, that are revitalizing the project a lot. Where's the strong hierarchy there? ;)

Also, I see many people in the community are too centered in Microsoft platforms and that's why don't think about the lmits of using formats like CHM. Open Sourcing not just the game engine but the editor would mean to port this last one to other platforms by using Mono, or new editors for other platforms too (Mac, iOS, Linux...).
« Last Edit: 20 Jun 2012, 03:53 by timofonic »

monkey0506

  • SEND PIZZA.
    • Best Innovation Award Winner 2017, for his work to help AGS games reach the widest possible audience - through popular distribution platforms (Steam, Galaxy) as well as other operating systems (Android, Linux)
    • monkey0506 worked on one or more games that won an AGS Award!
    •  
    • monkey0506 worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #33 on: 20 Jun 2012, 04:38 »
The fact of the matter is that the editor is and has been open source, and no one has taken the time to ensure that it will fully load with and/or create a port of it to Mono. And I would honestly be surprised if anyone seriously wants to try and develop a video game on their iPad. That doesn't even make sense.

The majority of users are running Windows to develop their games. Even if official editors were available for Mac and Linux, it wouldn't create a huge influx of change in this statistic, as there are alternatives already available (emulation, etc.).

If you would read the context of what RickJ (and others) have said, none of us have any specific allegiance to the CHM format, but rather simply to the benefits that it offers. Alternatives with similar features are available, as has been pointed out, and the whole topic is under review. Otherwise this thread wouldn't even exist.

Just because a program isn't updated every six months doesn't mean it automatically becomes unusable. AGS is not going to die, and I for one would really appreciate if you would stop your filthy fear mongering.

RickJ

  • fix'n one thing and break'n two ...
    • I can help with scripting
    • I can help with story design
    • RickJ worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #34 on: 20 Jun 2012, 06:17 »
@Timo ... WTF?

1.  I didn't say anything about CHM!
2.  I didn't say anything about MS, Linux, or any other OS
3.  I didn't say anything about mono, forks, stagnation, or anything of that nature.
4.  Your response to my comments are irrelevant to the conversation, please go back and read the previous posts so you know what is being discussed.

what I said was ...

WIKI BAD! DEVELOPERS DOCUMENTING THEIR OWN WORK GOOD!  OTHER PEOPLE CONTRIBUTE, DEVELOPERS REVIEW GOOD!

I appoligize for shbouting but some people don't hear very well... ;)

Wiki is a bad idea because there will always be clueless people about who think they know more than everyone when in fact they know very little. 

This is not even the main point of my comments, the main point was ...

ABILITY TO ADD SUPPLEMENTAL HELP FILES TO AGS HELP MENU GOOD!
 





Re: New HAT for AGS
« Reply #35 on: 20 Jun 2012, 08:32 »
Wiki is a bad idea because there will always be clueless people about who think they know more than everyone when in fact they know very little. 

I was a wiki editor and even Mediawiki is quite powerful in permissions stuff. You can create groups, assign certain permissions to those groups and even make certain pages be edited only by certain groups.

For example: You could create the "documentation team" group and only those people could edit certain flagged wiki sections.

The comment about stagnation was due to the idea of code rewieving, something that isn't happening and isn't possible at this stage due to a lack of developers and a management adapted to the Open Source model. Sorry if it sounded offtopic and not related to the main discussion.

I understand written English quite well, despite I'm not a native English speaker :)

Crimson Wizard

  • Local Moderator
    • Lifetime Achievement Award Winner
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Crimson Wizard worked on one or more games that won an AGS Award!
    •  
    • Crimson Wizard worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #36 on: 20 Jun 2012, 09:50 »
The only thing that saved AGS are the unofficial forks, that are revitalizing the project a lot. Where's the strong hierarchy there? ;)
Pardon?
Timofonic, I seriously do not understand your point sometimes.
The "only" thing that "save" AGS are people who are making games with it. And they are doing that a lot, and for a long time.

Oh, right, sorry for off-topic :P

selmiak

  • ǝsıɔɹǝxǝ ʞɔǝu puɐ uıɐɹq
    • I can help with play testing
    • I can help with proof reading
    • I can help with translating
    • I can help with web design
    • selmiak worked on one or more games that won an AGS Award!
    •  
    • selmiak worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #37 on: 13 Jan 2014, 01:43 »
I'd like to help but as a non native speaker myself I make enough errors myself.
Why not paste it all to a wiki and grab the most current version with some code magic every time a new built is released. But as this open up ways to destroy stuff there should be some editing restrictions on the wiki (not neccesarily the main AGS wiki).
as crimson wizard pointed me here I thought about what would be ideal, I have no idea how much of this is reasonable ;)
the best thing would be to have the documentation on the ags wiki where everyone can easily add stuff and correct errors and grab the most recent version of this for the newest built of AGS ;-D
but as this is still the internet where the wild things are and people can just make accounts for nada and 'edit' articles it would be bestest to have some kind of postcount limit or so to edit the documentation files that are delivered with the newest official built of AGS. I don't like having to apply to add to the wiki as this will totally oppose the wiki idea and keep involved people from spontaneously editing stuff. And having all the help files displayed on the AGS wiki anyways (without edititing options for just everyone) is still in scope of my cautious bestest idea.

Joseph DiPerla

  • Joseph DiPerla, Adventure Game Creator Wannabe!
    • I can help with backgrounds
    • I can help with characters
    • I can help with play testing
    • I can help with story design
    • I can help with translating
    • I can help with voice acting
    • I can help with web design
Re: New HAT for AGS
« Reply #38 on: 08 Feb 2014, 16:01 »
I wanted to get everyones thoughts on this as I can't seem to download Monsieur OUXX's version of the manual any longer... If you check out my Star Wars Game that I am developing and running at sw-bfs.com(Slow going since I am programming all the game features myself), you will notice a rules section. Part of how that works is that you have chapters. Each chapter has its own set of rules which are sectioned off. You can actually see that when you click on the intro. I did something similar with the FAQ. The beauty of the system I created is that when you have administrative priviledges, each chapter/section will have an Add/Delete/Edit button right on the page so that you can edit the rules as you would like. There is only one missing feature on this: Downloading for offline use.

However, on the forums, in one of my test threads for administrators, there is an option to download an entire thread into a story mode PDF or Doc file for offline reading. I could easily apply that to My rules feature and allow the manual to be easily updated online and viewable both on and offline. I can adapt the whole thing for use as an AGS Manual an change the way it displays. I can have it easily export the whole manual to PDF or Doc.

There are only two problems I can see with this, which I can work on. One would be that some may want this to be in HTML as it is easily viewable in web browsers everywhere and would allow for a better sectioned manual. I can do that certainly. I can add it as a third export option. It may take a little longer to implement, but I can do it. The benefit of this would be too that if you are in the AGS Editor and you need help with a particular section of the editor, you can hit F1 or whatever key you would like and it could take you to the right html file to get help rather than take you to the index page/table of contents.

The second issue is that it would be very difficult to make an accurate search function within the HTML version. I can possibly write a Javascript function that would search all the HTML pages for the words provided and display it as search results. However, that is also a little bit of extra work.

But despite this, like I said, this would be beneficial as it can allow easy/fast online editing of the manual and provide an on the fly solution for generating and downloading a PDF, Doc and HTML Help file version. If you think this would be a good idea and would like to use something like this, please say so and I will get to work on it right away. If you prefer Monsieur OUXX's solution or another, that is fine too. I just figured I would give this as an option.
Joseph DiPerla--- http://www.adventurestockpile.com
Play my Star Wars MMORPG: http://sw-bfs.com
See my Fiverr page for translation and other services: https://www.fiverr.com/josephdiperla
Google Plus Adventure Community: https://plus.google.com/communities/116504865864458899575

Crimson Wizard

  • Local Moderator
    • Lifetime Achievement Award Winner
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Crimson Wizard worked on one or more games that won an AGS Award!
    •  
    • Crimson Wizard worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #39 on: 15 Feb 2014, 16:01 »
As you may know I was recently updating AGS manual by editing the TeX file... and frankly I do not want to do that again. Well, maybe I just haven't learn all the capabilities and power of TeX yet. Or maybe the editor I used was terrible. But that's it.

I haven't work with documentation much before, but these are thoughts that came to my mind after having some practice with it.
1. The source should be always shared and accessible by all involved in development, both programmers and writers. This means it should be on the web.
2. There should be a way to keep changes history. Keeping documentation source in Git repository, for example. There may be alternatives.
3. If we aim for both online and offline documentation, they should share same source. This means that there should be a (preferrably automated) way to a) copy and install documentation to website, b) download and convert documentation to the help file (or whatever form the offline doc should be presented in).
4. Personally, I like the idea of multiple source documents more, than keeping everything in one file. But this depends on format and editor's usability. If editor allows to navigate source format freely and easily, it might as well be one file.
5. Regarding automated creation of script API documentation from comments in code. This may be a nice idea, but remember that AGS script is being used by people with different skill; sometimes they need more than formal description of function parameters: further explanation, examples maybe. If the API help is constructed entirely from code, this means that either programmers should create whole articles right in code (and not every programmer is a good help writer), or writers should edit source code.

There's a slightly different alternative: we have a agsdefns.sh resource for the Editor that declares everything exported for user scripts. Perhaps we could find a way to create a list of help topics from that.

Billbis

  • R, what else?
    • I can help with translating
    • Billbis worked on one or more games that was nominated for an AGS Award!
Re: New HAT for AGS
« Reply #40 on: 15 Feb 2014, 16:43 »
What I'll say may be completely irrelevant but:
-there is an online version of the French manual: http://admin.no.uchi.free.fr/dokuwiki-2008-05-05/doku.php
-it's a wiki: editable and keep tracks of modifications.
-you can download the offline version of this manual into a .chm file. (Main page of the wiki, "Télécharger la version hors-ligne du manuel français (19/10/2012)")
-however, this .chm file isn't updated in real time. I have no idea how it was generated (automaticly or manualy ?). I'll ask Kitai (he is in charge of this online manual) about this.
So there may be a way to convert the english wiki manual into a .chm file without much trouble.