Topic: New HAT for AGS

[Ali]

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]

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

[Ghost]

Downloaded and tested 1.0- looks comfortably familiar but navigates better.
Good job (says the n00b).

[Monsieur OUXX]

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!

[tzachs]

Just had a quick test of your manual, it looks great!
I support switching to it in the website.

[monkey_05_06]

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.

[Monsieur OUXX]

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

[Crimson Wizard]

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]

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.

[BigMc]

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.

[BigMc]

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]

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.       

[timofonic]

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

[monkey_05_06]

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]

@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!
 

[timofonic]

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]

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