New HAT for AGS

Started by Monsieur OUXX, Wed 13/06/2012 21:35:38

Previous topic - Next topic

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

#21
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

#23
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.

monkey0506

#25
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

#26
Quote from: monkey_05_06 on Fri 15/06/2012 16:10:10
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

Quote from: Monsieur OUXX on Fri 15/06/2012 17:32:27
Quote from: monkey_05_06 on Fri 15/06/2012 16:10:10
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

#31
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.       


timofonic

#32
Quote from: RickJ on Sun 17/06/2012 19:53:58
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...).

monkey0506

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

Quote from: RickJ on Wed 20/06/2012 06:17:12
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

Quote from: timofonic on Wed 20/06/2012 03:20:54
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

Quote from: selmiak on Sun 12/01/2014 19:57:37
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

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

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.

SMF spam blocked by CleanTalk