Topic: Help file... here we go again.

[Monsieur OUXX]

Continuing from those threads :
http://www.adventuregamestudio.co.uk/forums/index.php?topic=46223.0
http://www.adventuregamestudio.co.uk/forums/index.php?topic=46220.0
http://www.adventuregamestudio.co.uk/forums/index.php?topic=46471.0

The help file is getting more and more out of sync with the actual Editor. It's no big deal for most script functions, but there are many new features recently (e.g. : multiple platform builds).

The issue with the help file is that it's generated from some old LaTeX dialect, which in turn creates an old-school Windows help file (.chm files).
A few years ago I converted the .chm file to some Html-based online help, using a professional tool. That's great, but I don't think that's a good long-term solution. CHM files are a mess because that's starting to be a really old format (see the kind of trouble I had). Others tried other things along the years.
We need to find a solution.

[Crimson Wizard]

There is one suggested by Alberth: use Sphinx.
Here's his pull request: https://github.com/adventuregamestudio/ags/pull/173

My own wish was to have a single repository of help source, that could be autmatically (using some scripts) converted to multiple outputs: a Windows CHM, some Linux format, and HTML for web site.

I wanted to check that out but could not find time yet. If anyone does that, that would be wonderful.


EDIT: I found the original thread: http://www.adventuregamestudio.co.uk/forums/index.php?topic=50730.0

[abstauber]

I also did some research and Sphinx seems to be the only free alternative. All other tool are ridiculously expensive and/or not suitable for collaboration.
It seems like Alberth already did most of the work and converted everything

[Monsieur OUXX]

Really really cool.

[Crimson Wizard]

Monsieur OUXX, since you seem to be interested in this, can you take Sphinx files created by Alberth and try out what needs to be done to compile them as AGS help file?

[Snarky]

I'm a bit surprised that the scripting reference is entirely separate from the code (and presumably from whatever documentation is used to generate the tooltip help in the editor). Sphinx seems to have a plugin that allows it to pull in doxygen comments from sourcecode files, as long as they're in the right format. Would it make sense to move the api documentation to the engine source?

[abstauber]

In the meantime I compiled the .rst files from Alberth:
http://shatten.sonores.de/wp-content/uploads/2014/12/htmlhelp.7z

I had to install Python 2.7 and Sphinx following this guide:
http://sphinx-doc.org/install.html

After that it were just two steps:
1)make htmlhelp
2)hhc AGSdoc.hhp (inside the build/htmlhelp folder)

This build complains about a missing index file, but I just did a quick compilation test, so this shouldn't be a real issue later on.

[Alberth]

Glad to see new interest in my documentation patch

@Snarky:
It really depends what you want to achieve. Automagic merging of code documentation saves perhaps some typing. You also never miss any documentation.

On the other hand, controlling the order of content may be harder (alphabetical order is easy, keeping things topic-wise or release-wise together is more complicated). You also get the problem of versioning. Imagine a function f, that was added in 1.2, changed in 1.5, changed again in 2.4, and removed in 2.7. How would you handle this with code for say version 2.8? Python.org solves this by making a manual for each version separately, AGS currently has one manual for all versions.

If you keep all text together in some directory, it's relatively easy to find things. If you scatter documentation throughout the code, it becomes harder to find some piece of text, and a documentation change may cause conflicts in code changes and vice versa.

Last but not least there is also the matter of audience. Code documentation is usually not oriented at an end-user. It's brief, full of technical terms, just enough to know how to call the code from another method. An end-user typically needs a few pages explaining which functions exist, how function work together to achieve something in a game, and an example or two with explanation what it does.

@abstauber:
Thanks for trying. I don't have Windows, so I cannot build nor use the Windows help files.

[Snarky]

It really depends what you want to achieve. Automagic merging of code documentation saves perhaps some typing. You also never miss any documentation.

On the other hand, controlling the order of content may be harder (alphabetical order is easy, keeping things topic-wise or release-wise together is more complicated). You also get the problem of versioning. Imagine a function f, that was added in 1.2, changed in 1.5, changed again in 2.4, and removed in 2.7. How would you handle this with code for say version 2.8? Python.org solves this by making a manual for each version separately, AGS currently has one manual for all versions.

If you keep all text together in some directory, it's relatively easy to find things. If you scatter documentation throughout the code, it becomes harder to find some piece of text, and a documentation change may cause conflicts in code changes and vice versa.

Last but not least there is also the matter of audience. Code documentation is usually not oriented at an end-user. It's brief, full of technical terms, just enough to know how to call the code from another method. An end-user typically needs a few pages explaining which functions exist, how function work together to achieve something in a game, and an example or two with explanation what it does.

Well, the current AGS scripting help is sorted alphabetically (by class), and looks like it wouldn't be out of place in source comments, IMO. (But on that last point it's really the developers' opinions that count.) I assume it would go in either the .cpp or .h files here: https://github.com/adventuregamestudio/ags/tree/master/Engine/ac As you can see, there is no documentation in the source code currently, so there wouldn't be any conflict.

It's not correct that AGS currently has "one manual for all versions." Rather, it has a different version of the manual for each different version of AGS (distributed with the build), but only the latest version (at least in theory) is online.

Yes, it might be a drawback in some situations that different parts of the documentation would be split across hand-written articles and snippets extracted from the source code. But it might also have benefits: for example it should make it easier to ensure that the API and the documentation are in sync. I tend to think those benefits would outweigh the much less frequent (?) cases in which having to edit documentation both in the source code and in standalone help files adds a bit of overhead.

I would guess that the drawback is rather that it's a bit more complicated to set up (now we have to learn some basic Doxygen as well, set up that, etc.), and might take more work to convert the current documentation. And by putting reStructuredText comments throughout the code, we're more tied to Sphinx; it would be a little bit harder to switch to a different HAT in the future.

[Alberth]

Well, the current AGS scripting help is sorted alphabetically (by class), and looks like it wouldn't be out of place in source comments, IMO. (But on that last point it's really the developers' opinions that count.) I assume it would go in either the .cpp or .h files

In my experience with C++, near the actual implementation works best, as that gets changed when you change semantics of the call. It also helps in keeping the .h file less cluttered so it is easy to read.

As you can see, there is no documentation in the source code currently, so there wouldn't be any conflict.

I browsed through the code for half an hour to see if I could understand what belonged together but didn't get very far.

As for lack of comments, yeah, I noted. It's the same with almost every open source project. It's unfortunate that people (no offense intended to anyone, it's just an observation) don't take 1/2 a minute to write a few lines about the call interface (in terms that are easy to understand if you don't know the function) when they have it fresh in memory, so everybody now and in the future can read it in 10 seconds and have all relevant details on the first try, instead of having to reverse-engineer the interface in 30+ 1/2 minutes with the additional risks of missing some crucial implicit note or assumption which will surface as a bug 6 months later, which takes an amount of time that is not really usefully  countable in 1/2 minutes.

I started systematically documenting every function/method I wrote since about 8 years ago, and I found it increased my productivity. It takes a lot less mental effort to read 4 lines explaining how to call some function I wrote 3 years ago than it takes to reverse engineer that function without messing up. It makes the difference between "just call that function and get on with the problem you're working on" versus "oh my god, what did I do here again? There was something special here, I need more coffee.". I can also handle larger code bases with less effort now.

Besides the .rst patch, I haven't done anything in the AGS project yet. (Trying to read the manual failed already :p ) I do like the application domain, but I already write compilers/execution engines as day job. AGS doesn't run natively at my linux system, which makes it very hard to do anything useful. If I decide to do more code-oriented things, documentation will be high on my list in this project. My standard tactic in such a case is to start throwing documentation patches at the project (I don't want to reverse engineer anything more than once). However, if such patches are refused or existing devs see no reason to stop adding undocumented code or don't update existing documentation, I'll stop fairly quickly as well. No offense, but there is no point in me doing such work if new work gets created as we speak, so to say.

It's not correct that AGS currently has "one manual for all versions." Rather, it has a different version of the manual for each different version of AGS (distributed with the build), but only the latest version (at least in theory) is online.

Oh sorry, didn't know that. I normally never use builds, I tend to compile everything from source, as sooner or later I want to fix something annoying

by putting reStructuredText comments throughout the code, we're more tied to Sphinx; it would be a little bit harder to switch to a different HAT in the future.

Less than you're now tied to tex2rtf & friends. Unlike the current tex source, there is a free RST parser framework available in Python (docutils project iirc) that you can use if you want to. Writing a simple line-based text conversion script like I did, and pushing all the source code in a somewhat uniform format took a few days. As long as you stick to mostly plain text, it can be converted relatively easily.

[RickJ]

I started systematically documenting every function/method I wrote since about 8 years ago, and I found it increased my productivity. It takes a lot less mental effort to read 4 lines explaining how to call some function I wrote 3 years ago than it takes to reverse engineer that function without messing up.

I agree.  In addition, the exercise of explaining what one has done brings a tremendous amount of scrutiny and focus that tends to reveal inadequacies and outright bugs before they manifest and are identified in the usual time consuming manner.  This also means a tremendous boost to productivity is realized in the long run. 

Also I think Alberth has identified two seemingly conflicting needs with regards to the help file.  First there is a need to accurately document built-in functions and editor/engine features.  The best way to keep these things up to date is to maintain that documentation along with the code.  If both are in the same place then there is little excuse for them being out of sync.

The second need is for 'tutorial' or 'user' type documentation that illustrates how to use a collection of functions and features to accomplish some goal.  This kind of documentation is more easily maintained as a separate document.

I would like to add a third need here that should also be considered.  Third party modules and plug-ins extend AGS by adding additional functions/classes etc that also need documentation. 

It would be nice if all three needs could be satisfied with one coherent mechanism.  Wouldn't it be possible using RST/Sphinx/Python to come up with a modular help system that could be used for all three purposes?  For example  I was thinking along the lines of the help menu having multiple entries, one for each help module? 

[Snarky]

I think discussing this in the abstract is getting us off track. We're talking about the API documentation of the AGS scripting language. Here's the current documentation for Mouse.ChangeModeView() (to pick an example at random):

Changes the view used to animate the specified mouse cursor.

Mouse.ChangeModeView(CursorMode, int view)

Changes the specified mouse cursor mode's animation view to VIEW.

You can pass view as -1 to stop the cursor from animating.

This allows you to dynamically change the view used for the cursor's animation while the game is running.

Example:

mouse.ChangeModeView(eModeLookat, ROLLEYES);

will change the Look cursor's view to ROLLEYES.

See Also: Mouse.ChangeModeGraphic, Mouse.ChangeModeHotspot

How would you want to split this between "API documentation" and "user help/tutorial," and do you really think you're better off maintaining it in separate places? No, I think this should either all be in the source, or all in a separate document.

As for lack of comments, yeah, I noted. It's the same with almost every open source project. It's unfortunate that people (no offense intended to anyone, it's just an observation) don't take 1/2 a minute to write a few lines about the call interface (in terms that are easy to understand if you don't know the function) when they have it fresh in memory, so everybody now and in the future can read it in 10 seconds and have all relevant details on the first try, instead of having to reverse-engineer the interface in 30+ 1/2 minutes with the additional risks of missing some crucial implicit note or assumption which will surface as a bug 6 months later, which takes an amount of time that is not really usefully  countable in 1/2 minutes.

Well, AGS isn't really an open-source project at heart. It's a one-man project that was open-sourced after ten years of development. Sure, better source code commenting is probably a good idea moving forward, but that's really up to the devs, and very much aside from the question of how to best provide documentation for the users. Which documentation has to include the AGS scripting API.

Less than you're now tied to tex2rtf & friends. Unlike the current tex source, there is a free RST parser framework available in Python (docutils project iirc) that you can use if you want to. Writing a simple line-based text conversion script like I did, and pushing all the source code in a somewhat uniform format took a few days. As long as you stick to mostly plain text, it can be converted relatively easily.

That's a completely separate matter. The point is that if the documentation is all in one file/directory, it can fairly easily be converted to some other format. If it's generated from various snippets throughout (one part of) the source code, it gets much more complicated to do so. Going through it by hand would be tedious and error-prone, while trying to write a script to convert RST text embedded in Doxygen format embedded in C++ comments to some other format does not sound like fun, or particularly easy.

I would like to add a third need here that should also be considered.  Third party modules and plug-ins extend AGS by adding additional functions/classes etc that also need documentation. 

It would be nice if all three needs could be satisfied with one coherent mechanism.  Wouldn't it be possible using RST/Sphinx/Python to come up with a modular help system that could be used for all three purposes?  For example  I was thinking along the lines of the help menu having multiple entries, one for each help module?

That would require the help system to generate the help files on the fly depending on which modules/plug-ins were included. Also, AGS is written in C++ while modules are written in AGS script and plugins in whatever language the developer chooses.

In general, this is not how software works. Photoshop help doesn't try to integrate help for any PS plugins I may have installed. Nor does Firefox offer integrated documentation for each of my extensions. All of that is up to the developers of the plugins/modules/extensions. Of course, in AGS there's nothing stopping them from providing a Sphinx help file, though I think most module devs would consider it overkill.

[RickJ]

How would you want to split this between "API documentation" and "user help/tutorial," and do you really think you're better off maintaining it in separate places? No, I think this should either all be in the source, or all in a separate document.

I wouldn't advocate splitting this up at all.  To build upon your example, what could go into a separate document would be a tutorial and/or example using all or some number of Mouse methods to implement a mouse interface for one kind of game or another. It's not the same as API documentation.

That would require the help system to generate the help files on the fly depending on which modules/plug-ins were included.

The module/plugin author would generate the help file as part of their development effort.  When the module/ plugin is installed the help file would just be p[art of the installation.  The game file could contain the help menu entries and filename bindings or the editor could just create the menu entries "on the fly" by doing a help directory list when the editor is first loaded.

Also, AGS is written in C++ while modules are written in AGS script and plugins in whatever language the developer chooses.

Both use remarkably similar syntax; same comment characters, line terminators, etc.  The RST would be the same in either case, embedded in comments.  One wonders how difficult it would be to get Sphinx to read module files? A while ago I made a module document extractor tool using AGS itself.  However, AGS's file writing limitations prevent it from being production ready.  It wasn't a trivial effort but it wasn't a monumental task either. 

[Snarky]

I wouldn't advocate splitting this up at all.  To build upon your example, what could go into a separate document would be a tutorial and/or example using all or some number of Mouse methods to implement a mouse interface for one kind of game or another. It's not the same as API documentation.

I refer you to my first post:

I'm a bit surprised that the scripting reference is entirely separate from the code (and presumably from whatever documentation is used to generate the tooltip help in the editor). Sphinx seems to have a plugin that allows it to pull in doxygen comments from sourcecode files, as long as they're in the right format. Would it make sense to move the api documentation to the engine source?

The discussion is about the best way to maintain the AGS scripting API reference as it exists in the current manual, assuming we move to Sphinx as the HAT. No one has suggested moving the general manual and tutorial articles (either the ones that are already part of the manual or purely imaginary ones) into source code comments; that would be absurd.

The module/plugin author would generate the help file as part of their development effort.  When the module/ plugin is installed the help file would just be p[art of the installation.  The game file could contain the help menu entries and filename bindings or the editor could just create the menu entries "on the fly" by doing a help directory list when the editor is first loaded.

Module authors can already write a (separate) help file in RST, generate docs from it with Sphinx and distribute it with their module. The only benefit you might realize with this suggestion is the ability to launch the help from within AGS. Personally, I think a great benefit of current modules is that they're very simple to make and distribute, and that the file format is simply a plain text file (so I can, for example, examine the code without opening AGS, particularly while I'm on a Mac). You'd lose that simplicity. Also keep in mind that Sphinx just batch-generates documentation. The output (whether PDF, HTML/CHM, LaTeX or whatever) are "dumb" files which won't magically integrate with each other: AGS would need to somehow modify them on the fly, which is much more involved than simply launching the CHM viewer like it currently does.

Both use remarkably similar syntax; same comment characters, line terminators, etc.  The RST would be the same in either case, embedded in comments.  One wonders how difficult it would be to get Sphinx to read module files? A while ago I made a module document extractor tool using AGS itself.  However, AGS's file writing limitations prevent it from being production ready.  It wasn't a trivial effort but it wasn't a monumental task either.

In order to read RST embedded in source code comments, Sphinx uses plugins. For whatever reasons it has different plugins for C++ and Java, so it's not hard to imagine it would need a separate plugin for AGS Script. (I suspect the reasons are more to do with standard commenting practices in each language, e.g. javadoc vs. doxygen, but unless we want to force ALL module authors to write ALL their comments in RST, the problem could still persist.)

Ultimately, I think the current module documentation works pretty well, and there's no need to try to integrate it with AGS documentation, which would just place a higher burden on module authors. Now they would have to learn RST, install and run Sphinx to generate documentation, distribute more files with the module, test the integration of the help file with AGS, etc. All for what? Looking at some of the top modules on the forum, here's what users need to know in order to use the A.S.S Savegame module, for example:

// !MAKE SURE "save screenshots in savegames" IS ENABLED UNDER General Settings IN AGS!
// And don't forget to import gSave.guf and gLoad.guf; this script will not work without them.

// When you want to open the save GUI, all you have to do is call: sl_save();
// And to open the load gui - you guessed it: sl_load();

Would you really gain much from having that in the manual rather than at the top of the header file (where modules are conventionally documented)?

[abstauber]

Maybe we should split this into separate threads: decision and discussion
Otherwise I guess we might never get started - and the help file situation is really not the best.

To sum things up, there's just one usable Help Authoring Tool: it's Sphinx.
Moving over to Sphinx isn't hard, as Alberth already provided a conversion tool and did the conversion.
At the moment the AGS help file is huge and rewriting it from scratch would be a tremendous task. It will need to be split up, but it can wait.
Moving all the documentation into the actual source code (my opinion) would make things even worse and waste countless hours, although I'd like to hear CW's and Guroks take on this.

I've just converted the documentation of the 9Verb-template to Sphinx:
http://shatten.sonores.de/wp-content/uploads/2014/12/9Verbs_sphinx_doc.zip

After having that done I'd like to underline that a rewrite of the AGS help file will take ages. Also I highly doubt that module authors are willing to learn how to write .rst files But for the included templates, we should provide the documentation somehow.

@CW: Since you are building the current chm files, what do you think about moving from the .tex file to .rst ?

[Snarky]

Maybe we should split this into separate threads: decision and discussion
Otherwise I guess we might never get started - and the help file situation is really not the best.

Yes, sorry I brought it up. I thought the decision part was a no-brainer, if as you say:

To sum things up, there's just one usable Help Authoring Tool: it's Sphinx.
Moving over to Sphinx isn't hard, as Alberth already provided a conversion tool and did the conversion.

In fact, it sounded like it was more or less done, and just a matter of fixing some small issue and then committing it to the repo (or whatever the git equivalent). I see now from the pull request and sample HTML output that there are still some rough edges.

At the moment the AGS help file is huge and rewriting it from scratch would be a tremendous task. It will need to be split up, but it can wait.

We wouldn't want to rewrite it from scratch anyway, would we? I think some parts could be better, but it's very much a matter of incremental improvements.

Moving all the documentation into the actual source code (my opinion) would make things even worse and waste countless hours, although I'd like to hear CW's and Guroks take on this.

Whether or not it's better in principle, I'm less and less convinced myself that the benefits outweigh the hassle.

[Monsieur OUXX]

Monsieur OUXX, since you seem to be interested in this, can you take Sphinx files created by Alberth and try out what needs to be done to compile them as AGS help file?

Sorry, I didn't see that. Yes, I definitely should do that.

- Yes, I think .tex should be converted to .rst
- I don't think the documentation should be in the code. I thought it was better in the past, but I realized that it's better to keep the doc easily accessible to people who don't mess with the code. They can do their thing quietly in their corner, without worrying about pulling/committing github code and such and browsing through the Visual Studio solution. All they need is one file and a text editor.

[GarageGothic]

Possibly the wrong thread, but I've been unable to read any of the actual articles in the help file after upgrading to Windows 10 - I can see the index and contents fine, but no articles show up when I click them. Anyone else experiencing this, and do you have a workaround?

Edit: Tried a different chm viewer app called UltraCHM and I get the same result as with the MS viewer.

[Crimson Wizard]

Yes, this is wrong thread, here we discussed different format for manual...


For you problem, try to use this solution: http://www.adventuregamestudio.co.uk/forums/index.php?topic=52398.msg636517886#msg636517886

[GarageGothic]

Thanx Crimson, worked great.

[Crimson Wizard]

It's sad that this endeavour just ended with nothing. I can make a guess that people were expecting me to do something, but I cannot do everything, and I had other priorities at a time. I actually hoped there would be a community work in this.

My natural question: is this actually still needed? The fact that no one tried to improve situation in about 1.5 years since the last talk looks like either everyone is waiting for someone to start, or no one really cares about this anymore(?).
I'd like to know following:
- is moving to another help system still wanted?
- am I expected to do something about it? Because, frankly, most of the related tasks could be done by anyone, not just me.


My opinion all this time was that manual is simply lacking material. For example, there is almost no structured information on how Editor works (for example, in the form of per-task or per-window reference).
Speaking honestly, is there someone who will be ready to work on such articles? Because it was possible all this time to add them even without changing manual format.



Splitting the overall problem, there are following issues that may in theory be solved separately:

1. Lacking documentation and/or bad manual structure (articles organized in a way that makes it hard to find what you want). For example, Editor is never properly explained, sans the Tutorial, but Tutorial mentions only few things you need to know to make your first demo game.
How to solve? Someone should simply write the text. That's it.

2. Bad source format. The current source format of the manual is an old version of LaTeX, and all manual is written as one huge file. Also, personally I could not find a satisfactory (that would be at least intuitive) tool to edit the source, so I myself do that in a common text editor.
How to solve? Look around for better format (some were already suggested in the past: Sphynx, etc). Tell us how source is edited, are there good utilities for that (provide examples). After the format is decided, make a plan for converting current manual: design guidelines (consistent presentation, styles), write automatic conversion script (latter is done by savvy person).

3. Slightly (?) outdated end format. AGS Editor is distributed with the manual as a CHM file. CHM is outdated, and sometimes does not run properly on latest versions of Windows. For the least we may try to upgrade it to WinHelp 2.0. Since AFAIK both are created from HTML pages, it should not matter which source format was chosen, there will always be a way to compile manual source into what we want (source -> HTML -> CHM/WinHelp2/other).
After end format is confirmed, Editor should be "taught" to work with that format (to keep context help working). Latter will be done by programmers, so don't worry about it.

4. Manual is "hidden" from editing by most community members. What I mean is that its source is located inside the AGS code repository, which may be psychologically complicating (?). Besides, you need to know and use Git to commit any changes there. Is there a way to make editing process easy enough for any regular community member to add/fix material, like they may do with Wiki?

5. Online manual(s) are out of date. There are two online manuals on AGS server, one is this: http://www.adventuregamestudio.co.uk/manual/ , and another is in the Wiki: http://www.adventuregamestudio.co.uk/wiki/Contents_(manual)
First was updated 2 major versions ago (5 years old), second - 3 major versions (7 years old!).
Question one: is there really a need for the one in the Wiki? No one is updating it anyway.
Question two: is there a way to automate primary online manual update? I guess the answer mainly depends on how the manual editing itself is organized (points 2 and 4).


This is to outline the potential tasks.


To be honest, this is probably my last attempt to initiate this work. Seeing no one is interested makes me indifferent myself, and if such activity is not wanted, I will just focus on limited range of tasks I do and never return to this myself.

[sonneveld]

I can help.  I think it might be a good idea to just throw away all formats and host the documentation on https://readthedocs.org/ .  It automatically builds docs for restructuredtext/markdown. This would mean resurrecting the doc pull request that converts all documentation to rST.

It would be worth finding out if people need documentation. Something that's google-able would be helpful for newcomers.

[Crimson Wizard]

Nick, this reply of yours is pretty confusing.

I think it might be a good idea to just throw away all formats and host the documentation on https://readthedocs.org/
<...>
It would be worth finding out if people need documentation.

Do you mean -  throw away help file (offline documentation)? Basically, you suggest to convert manual to RST, and then use it to create online documentation?

I would not like to disband offline docs. Imagine a person goes somewhere with no internet connection (or bad connection), and want to continue working on game.
Unless that site allows to download docs (in which form?)...

[selmiak]

I have an idea. tell me what you think.

we make a new separate wiki only for the manual on the ags server. everyone with an forum account can edit it, just like the normal AGS wiki. This new wiki is only for the manual, the manual wiki so to say. Or the wiki manual, whatever you prefer and gets used the most I think.
Then with some code magic we strap the complete content, the topics of the articles and the links and convert this content from the wiki to some (html) format the helpdisplay in ags and windows can display. grab what is on that manual wiki and make ags help display this.
At the beginning it will be empty like every wiki so we should first fill it. we should gather some 5-10 or even more people to at first transfer the current manual to the wiki. everyone get one letter, check this letter, then the next one, the more people help converting the old manual content to wiki format the faster this will happen.
Then we can add new topics for new functions over time and it will always be up to date in the wiki manual already. We could even have some cronjob on the server to gather the new wiki pages and pack it to the ags distribution files. I think it is close to impossible to add some malicious code to wiki markup that will break out from the helpdisplay sandbox and screw with users computers.

almost everyone can write wiki markup and if not, it is very easy to pick up, tech savvy people like the forum users that want to help write the technical manual will get into it in no time. The easier the pages are to edit to more people can help and the faster things get done in that scale.

so my conclusion for this idea is to find some code wizard that can or thinks he can convert some wiki markup to some helpfile display content. he or she shall chose the wiki software and the help file display software and get coding. once this code works we only need to fill the wiki and voila.

[Crimson Wizard]

so my conclusion for this idea is to find some code wizard that can or thinks he can convert some wiki markup to some helpfile display content. he or she shall chose the wiki software and the help file display software and get coding.

There is certainly software that does this. Recently I found one: http://pandoc.org/

[Gurok]

I would not like to disband offline docs. Imagine a person goes somewhere with no internet connection (or bad connection), and want to continue working on game.
Unless that site allows to download docs (in which form?)...

Agree completely. This might also be an intentional thing, e.g. Someone might go somewhere remote to get away from the Internet and write their game. Actually, that sounds like a rather nice idea for a holiday, come to think of it.

so my conclusion for this idea is to find some code wizard that can or thinks he can convert some wiki markup to some helpfile display content. he or she shall chose the wiki software and the help file display software and get coding.

There is certainly software that does this. Recently I found one: http://pandoc.org/

I saw you mention this on GitHub too and I just want to clarify.

Was your suggestion to use Pandoc to go from some Wiki->rST and then Sphinx2 (as currently nominated on GitHub) to go from rST->CHM?

It's unfortunate that CHM output doesn't seem to be a priority for the Pandoc people:
https://github.com/jgm/pandoc/issues/2056

[Crimson Wizard]

This might also be an intentional thing, e.g. Someone might go somewhere remote to get away from the Internet and write their game. Actually, that sounds like a rather nice idea for a holiday, come to think of it.

Haha, my thoughts exactly.

I saw you mention this on GitHub too and I just want to clarify.

Was your suggestion to use Pandoc to go from some Wiki->rST and then Sphinx2 (as currently nominated on GitHub) to go from rST->CHM?

It's unfortunate that CHM output doesn't seem to be a priority for the Pandoc people:
https://github.com/jgm/pandoc/issues/2056

No, my suggestion on github was to use Pandoc to convert LaTeX to rST (both are source formats).

We apparently do not need to use Pandoc to get CHM from rST: http://www.adventuregamestudio.co.uk/forums/index.php?topic=51340.msg636501803#msg636501803
Sphynx builds HTML Help project from rST, and Microsoft's own "hhc" utility compiles CHM.
If Pandoc could convert to HTML Help too, it could be used in the same process (although that is not the main point).

Also, we were wanting to get rid of CHM altogether. It is just that we may have to keep it for some time (if solving the issues step by step).

The remaining question is just which (offline) help viewer to use instead of CHM.

[sonneveld]

Pandoc's a document converter but it wouldn't be the final step. You'd still need a document tool like Sphinx to create offline documentation for chm.

I'm not sure the wiki is a great idea. You still want to have documentation tied to your particular branch in the AGS repository.  How would the wiki treat documentation that would be different for stable and development branches?

However there is something to be said for making it easier to contribute.

Picking a different markup language for the manual would be a good first step. Despite RestructuredText possibly being better suited for documentation, I think a lot of major projects are using Markdown for documentation because more people are familiar with it and that lowers the barrier for people to contribute. Even Microsoft has started using it for some of their github backed docs.

Github allows people to fork repository, edit files and create pull requests all within the browser. That is almost a wiki-like experience but with better change controls.

Nick.

[Alberth]

I would suggest to first define what you want from documentation, then consider the format and place of the source, then consider how to get there from what you have now.

"what you want" would include
- online/offline (both I think)
- purpose of the documentation (what does it contain, what can you learn from it)
- up-to-date-ness of the documentation (how bad is it if it runs behind a year or more)
- users of the documentation
- editors of the documentation (who for what parts mostly)
- try to come up with more properties that you desire from the documentation

[Crimson Wizard]

Ok... I will give this another try.

I would suggest to first define what you want from documentation, then consider the format and place of the source, then consider how to get there from what you have now.

- online/offline (both I think)

Yes, both, because it would be more comfortable to know that people can use documentation even without internet connection. Of course format could be same (like, you can view html pages from your HDD too).

- purpose of the documentation (what does it contain, what can you learn from it)

Priority is given to end-user documentation for AGS Editor and engine.
For AGS Editor, ideally, documentation should include sufficient information for a person who first met AGS to create and deploy games in it: feature overviews, explanation of workflow, detailed each window description, basic tutorials, and of course script API reference.
For the engine - at least the basic information on its work from the game-dev and player's perspective: (games) installation requirements, paths and files it uses, manual configuration, command-line arguments.

- up-to-date-ness of the documentation (how bad is it if it runs behind a year or more)

It should be up-to-date with the latest official final (non-beta) release.

- users of the documentation

For AGS Editor documentation: game developers,
For engine end-user documentation: game developers and players (because the former should be able to reference something for the latter).

- editors of the documentation (who for what parts mostly)

Program developers must be able to update documentation when new release is out (script API, features).
Any other volunteer should be given a chance to contribute anytime whenever they think some articles needs improvement of corrections.
In simple case, program developer writes basic articles, and contributors help to fill in the gaps. (Not every programmer can write good tutorial)

- try to come up with more properties that you desire from the documentation

Offline docs should be browseable on most platforms (not something Windows-only).
Index and Search functionality. Capability to display images. Basic formatting capabilities (tables, lists, etc).


Other points.
There should be single source (repository) shared for the online and offline documentation.
Offline docs may be same format as online one (if applicable), just installed on disk (e.g. html files).
Ideally an automation should be set up: online documentation is updated as soon as source is modified, and offline version is available for download from the host location. Respective version of offline docs are also included with the AGS Editor installer.

How to upgrade from old manual
Setting up simple format conversion, then tidying up manually.

What about organizing documentation parties: announce a "week of improving documentation" - gathering volunteers, then giving them articles to improve.

[eri0o]

Hey,

I used to use pandoc and sphinx, I was passing on the AGS topics and this is the first thing I thought "I know how to automate this!"

I have a project here (it's slightly abandoned) that has a help file built from Markdown source: https://github.com/ericoporto/fgmk/tree/master/docs

I use pandoc to go from .md to .rst and sphinx to build my help files (QtHelp and html).

You can take a look at the generated html help here: http://ericoporto.github.io/fgmk/

Can someone point me the source files?

[Crimson Wizard]

Can someone point me the source files?

https://github.com/adventuregamestudio/ags/tree/master/Manual


EDIT: if you run "run.cmd" (you also need to have Python 2.7 installed), the HTML files are created as an intermediate output. These may be easier to use than source TEX file.

[morganw]

Since the CHM format was reverse engineered you can also get the HTML files from the CHM file, by extracting it with 7-zip.

[Crimson Wizard]

We really need to do something with this. Any kind of progress would be better than nothing.
Many parts of manual are getting more obsolete with every year, and there are new topics that should be covered.

I used to use pandoc and sphinx, I was passing on the AGS topics and this is the first thing I thought "I know how to automate this!"

I have a project here (it's slightly abandoned) that has a help file built from Markdown source: https://github.com/ericoporto/fgmk/tree/master/docs

I use pandoc to go from .md to .rst and sphinx to build my help files (QtHelp and html).

You can take a look at the generated html help here: http://ericoporto.github.io/fgmk/

Alright then, the resulting html pages look good in general. Some time ago someone told me that nowadays Markdown is becoming popular and may be a good choice.

So, why not start doing something?

The plan:
1) First of all, let's create a new repository for the manual. That would be cleaner, and also easier to give access to various people without worrying they will break engine code by mistake.
2) Let's make several Markdown pages, only to test its abilities. Copy few manual topics, or some topics from Wiki. Then add pandoc/sphynx scripts as in eri0o's example, and try making html documentation and see how it looks and works.
3) If everything works good, decide on how to convert existing manual. We could automate and write scripts, or use one of the tools like pandoc (I recall finding some method to make such convertion before, need to review earlier posts in this thread). Of course, we'd have to fix style manually afterwards.
4) If all above works - move forward. We'd need to invent how the offline manual will work from now on. Could use some converter to create Windows Help file from the markdown/rst sources with sphynx, or even go Unity3D style and distribute html pages.

The new manual will be open for all people to edit (with pull requests, or directly), it may host both official documentation, and tutorials written by users, and articles from Wiki, etc.

[eri0o]

Ok, I have some ideas on this... First, a way to get the manual from the repo...

update_manual_files.sh

Spoiler: ShowHide

Code: Bash

1. #!/bin/bash
2.  
3. release_branch="release-3.4.1"
4. function git_sparse_clone() (
5.   rurl="$1" rbranch="$2" localdir="$3" && shift 3
6.  
7.   mkdir -p "$localdir"
8.   cd "$localdir"
9.  
10.   git init
11.   git remote add -f origin "$rurl"
12.  
13.   git config core.sparseCheckout true
14.  
15.   # Loops over remaining args
16.   for i; do
17.     echo "$i" >> .git/info/sparse-checkout
18.   done
19.  
20.   git pull --depth=1 origin "$rbranch"
21. )
22.  
23. git_sparse_clone "https://github.com/adventuregamestudio/ags.git" "$release_branch" "$release_branch" "Manual/*"
24.  
25. cd "$release_branch"/Manual/
26.  

then the ags.tex has to be converted to Markdown. Pandoc can help there, but it will fail on lines 2845 ... 2851:

Code: LaTeX

1. ...
2. }\row{{ \verb$%d$ } & { Integer (use to display value of int and short variables) }
3. }\row{{ \verb$%0Xd$ } & { Integer left-padded with up to X zeros }
4. }\row{{ \verb$%s$ } & { String (use to display string variables) }
5. }\row{{ \verb$%c$ } & { Character (displays the ASCII character of the supplied value) }
6. }\row{{ \verb$%f$ } & { Float (displays a float variable) }
7. }\row{{ \verb$%.Xf$ } & { Float to X decimal places }
8. }\row{{ \verb$%%$ } & { Display the percent character (ie. no variable) }
9. ...
10.  

I can't deal with percent between a pair of money sign ($), so each percent on those lines has to be escaped.

Once that is done, you can convert.

pandoc -S ags.tex -o ags.md

Some things will break. These are some weird non latex marking used in the AGS documents: LTSSimg , GTSS, ILBRK. This will result in no image links. Once you get to the markdown part, though, that's where I stopped last time... here in this github repo... Note that since then, Sphinx has started to support Markdown, so the whole Md to Rst conversion can now be skipped.

Meanwhile, recently I have been back into using LaTeX through Overleaf, they recently acquired Sharelatex. The problem is the free account is very limited - only 60 files, the ags docs is comprised of 64 files in my best reduction...

[Crimson Wizard]

pandoc -S ags.tex -o ags.md

Some things will break. These are some weird non latex marking used in the AGS documents: LTSSimg , GTSS, ILBRK. This will result in no image links. Once you get to the markdown part, though, that's where I stopped last time... here in this github repo... Note that since then, Sphinx has started to support Markdown, so the whole Md to Rst conversion can now be skipped.

Mmmm.... this conversion results in 1 huge file? Is there a way to split it?

Will that make things easier if you do not use original TEX file, but HTML pages prepared by the script in AGS repository instead? It already removes ILBRK, GTSS and LTSS tags on its own.

[eri0o]

Which conversion? I haven't got to the part of using Sphinx yet... I am still at step 1!

1) First of all, let's create a new repository for the manual. That would be cleaner, and also easier to give access to various people without worrying they will break engine code by mistake.
2) Let's make several Markdown pages, only to test its abilities. Copy few manual topics, or some topics from Wiki. Then add pandoc/sphynx scripts as in eri0o's example, and try making html documentation and see how it looks and works.
3) If everything works good, decide on how to convert existing manual. We could automate and write scripts, or use one of the tools like pandoc (I recall finding some method to make such convertion before, need to review earlier posts in this thread). Of course, we'd have to fix style manually afterwards.
4) If all above works - move forward. We'd need to invent how the offline manual will work from now on. Could use some converter to create Windows Help file from the markdown/rst sources with sphynx, or even go Unity3D style and distribute html pages.

What I am thinking, is there a way to automate step 1 and 2 ? I don't know.

So I recently learned there is no Markdown specification, meaning one must be adopted...

Also, this is a better way to generate headers (atx headers are defined by # character preceding the header text instead of a line of ===== or ----- under the header text)

Code: Bash

1. pandoc -f latex ags.tex --atx-headers --to=markdown -o ags.md

Now with this, I am thinking on how to split the single markdown in multiple files... I have to say that at the end, being able to ctrl+f through the manual is useful.

About batch converting the .htm files, you are talking about Manual/htmlfiles folder in the repo?

convert_htm_to_md.sh

Code: Bash

1. #!/bin/bash
2. find . -name \*.htm -type f -exec pandoc -o {}.md {} \;

These html files are a bunch of td/tr html tables, so the output is useless...

Oh right, about Sphinx. Why did I talked about it... It's the only thing I know that can generate the Windows help file.

[Crimson Wizard]

Which conversion? I haven't got to the part of using Sphinx yet... I am still at step 1!

I mean from Latex to MD, if MD is supposed to be the new source(?).

What I am thinking, is there a way to automate step 1 and 2 ? I don't know.

I meant simple manual (as in "by hand") test just to see how it works. Writing that plan I assumed that you don't want to participate, since you left this topic one year ago without saying anything, so I thought you are no longer interested. Therefore we'd have to learn how to work with conversion from point zero.

I have to say that at the end, being able to ctrl+f through the manual is useful.

But that's crazy... how will people read and edit that monster?

About batch converting the .htm files, you are talking about Manual/htmlfiles folder in the repo?

No, I am talking about html files generated with the scripts in Manual folder. Run run.bat on Windows and it converts tex into 100 htmls.
This is an intermediate step between TEX and actual CHM.

I could upload them somewhere in case you do not have access to Windows -

https://www.dropbox.com/s/snrrhug5ugrc52l/ags-manual-htmlpages.zip?dl=0

If converting these to MD is possible, these could be better start than 1 giant TEX file.


But once again, is MD a good format? I don't know, this is something I was planning to find out.

[eri0o]

Oh, I was not talking as editing a single file, just having a possible visualization option at the end...

Ok, so there is a compile_documentation_unix.sh, but it only builds the tutorial. But I liked three lines...

Code: Bash

1. sed -i 's/ILBRK/<br>/g' *.htm
2. sed -i 's/GTSS/>/g' *.htm
3. sed -i 's/LTSS/</g' *.htm

This is what is doable!

While I understand the md would be the new source, I am too lazy to generate by hand - it's over 22k lines!

Anyway, from the html files you upload to dropbox, I generated this!

My command was the naive bash+pandoc: find . -name \*.htm -type f -exec pandoc -o {}.md {} \;

Edit: Just noticed one has to place the images directory on there to be able to see images in a markdown previewer.
Edit2: All links are broken since they link to an htm instead of md file, but this can be replaced using sed.
Edit3:  find . -type f -iname "*.md" -exec sed -i 's/\.htm/\.htm.md/g' {} \;
Edit4:  very quick very bad conversion repo here.
Edit5: github wiki test. All links are broken except for the right side pane..
Edit6: Fixed links with :  find . -type f -iname "*.md" -exec sed -i 's/\.md//g' {} \;
Edit7: quick example of sphinx output for the markdown docs

[morganw]

But once again, is MD a good format? I don't know, this is something I was planning to find out.

It is the easiest option I know of to write the pages, and if someone is making changes they would be able to do it directly on the GitHub web interface, so I think it is a good idea. I believe this is the original spec, and GitHub just add a few extra bits like tables and task lists. Worst case, if it needs to come off GitHub, any GitHub specific content would need to be changed, but I think the online editing is enough of a benefit to outweigh the risk (plus there are lots of tools for bulk processing text).

To begin with, is there anything that can just be deleted? There is still a load of stuff in there about licensing which no longer applies (I've never heard of a 'swapware license'). I am currently trying to make a replacement verb coin template, but even if that doesn't end up getting added I'm not sure why the existing verb coin template has manual entries, whilst the templates that people are likely to actually use have nothing.

[Crimson Wizard]

To begin with, is there anything that can just be deleted? There is still a load of stuff in there about licensing which no longer applies (I've never heard of a 'swapware license'). I am currently trying to make a replacement verb coin template, but even if that doesn't end up getting added I'm not sure why the existing verb coin template has manual entries, whilst the templates that people are likely to actually use have nothing.

Part of the reason I asked to have sources converted to separated files is that IMHO manual's structure is terrible. Script API reference is probably the tidiest part of it, but the rest is quite confusing, and even after many years I fail to find what I need quickly without running search.
For example, there is no section dedicated to the Editor's UI, and info about that had to be retrieved from various articles spread around, and only tutorial has any screenshots.

This is why my proposal is to first invent content structure for the new manual, then move useful material from the old one (throwing out unnecessary bits). Then - fill in the gaps (some gaps are going to be huge though...)

[eri0o]

Ok, first idea of topics listing

• Getting Started in AGS

. Introduction on how to use Room Editor, Character Editor, Views and all, but very lean. This can be an updated version of the Tutorial we have.

• General Settings and Default Setup
• Room Editor (detailed)
• Character Editor (detailed)
• Inventory Items (detailed)
• Sprites and Views.
• Audio (and without scripting yet!)
• Dialogs
• GUI Editor
• Mouse Cursor
• Fonts
• Translating a game
• Dealing with Voice Over
• Scripting (lots of other things can reference to here!!!)
• Global Variables
• Text Parser
• Templates
• Plugins
• Bulding your game
• Contributing to AGS Project
• License stuff

[Crimson Wizard]

I was thinking to suggest a bigger chapter split at the root level:

* Getting Started in AGS
** FAQ
** Game features (quick reference, explaining what AGS has and can do)
** Tutorials

* Editor reference (explains how to work with the Editor, use UI etc)
** Room Editor (detailed)
** Character Editor (detailed)
** etc

* Engine reference (explains stuff about running the game, and engine on its own - for advanced users)
** Setup program
** ?

* Script reference (all the scripting and API)

[Monsieur OUXX]

+1 for this organization

I would recommend highlighting some subjects that are often overlooked with AGS though :
- Localization
- Talkie games

[eri0o]

After tweeting github about broken Wiki on mobile, got an interesting suggestion. Adding a improve this page button that starts a pull.



The problem is the person editing has to have a Github account and understand how the fork pull request flow works.

[tzachs]

Yes, it's a cool feature that should in theory encourage contributions. I already have it for MonoAGS docs website, still waiting for the first contributor.

[morganw]

I think that, in terms of script reference, it would be possible to generate this on demand, because the information is already entered so that the compiler/autocomplete can use it:

Code: C#

1. builtin managed struct Character {
2.   /// Adds the specified item to the character's inventory.
3.   import function AddInventory(InventoryItem *item, int addAtIndex=SCR_NO_VALUE);
4.   /// Manually adds a waypoint to the character's movement path.
5.   import function AddWaypoint(int x, int y);
6. ...

So what is entered as / converted to Markdown doesn't necessarily need to cover the script functions. I'm currently doing nothing for a week after surgery on my foot, so I can try to work on the manual for a few days if I know what and where the final result should be.

[Crimson Wizard]

I'm currently doing nothing for a week after surgery on my foot, so I can try to work on the manual for a few days if I know what and where the final result should be.

So, I can create a new "ags-manual" repository in the community group. But I got distracted and haven't quite realized what was the outcome of eri0os's experiments. I recall he tried several things, including storing pages in a github Wiki. I am unaware how you access that through git means, and whether its possible to work with on your local disk if you prefer to edit files directly.
His findings are listed here, it seems: http://www.adventuregamestudio.co.uk/forums/index.php?topic=51340.msg636589833#msg636589833


Anyhow my proposal stands this:
1) we seem to have decided on having source in Markdown, so be it.
2) the new repository may be thought as an experiment where nothing is set in stone, but the general idea is to have current manual converted into Markdown and brought to a better chapter/page structure.
3) Big LaTeX file may be found here, as usual: https://github.com/adventuregamestudio/ags/tree/master/Manual
If you cannot convert this to HTML yourself (still not certain if conversion works fully on Linux): https://www.dropbox.com/s/snrrhug5ugrc52l/ags-manual-htmlpages.zip?dl=0
4) Suggestions on chapter structure: http://www.adventuregamestudio.co.uk/forums/index.php?topic=51340.msg636589906#msg636589906
That, and my own post after that suggests larger division on root level.

Probably, manual source (in markdown) should be placed in its directory (e.g. "src" or "docs"), because we may also have some conversion scripts in the repository?

I think that, in terms of script reference, it would be possible to generate this on demand, because the information is already entered so that the compiler/autocomplete can use it:

Code: C#

1. builtin managed struct Character {
2.   /// Adds the specified item to the character's inventory.
3.   import function AddInventory(InventoryItem *item, int addAtIndex=SCR_NO_VALUE);
4.   /// Manually adds a waypoint to the character's movement path.
5.   import function AddWaypoint(int x, int y);
6. ...

So what is entered as / converted to Markdown doesn't necessarily need to cover the script functions.

Do you mean generating articles this way, or actual help content? Currently in the script reference articles are larger than that, having elaborations, warnings, examples etc.

[morganw]

So the

Do you mean generating articles this way, or actual help content? Currently in the script reference articles are larger than that, having elaborations, warnings, examples etc.

My main concern is that the scripting reference will go out of sync with the actual scripting implementation, so ideally I'd like to try and get the scripting reference generated from the same source as the autocomplete data (auto-complete could just ignore the extra information for examples, warnings, etc).

In terms of everything else though, I didn't see a repository called "ags-manual", unless my permissions are hiding it from me.

If trying to auto-generate the script reference, and also incorporate another repository as a general manual, is it easier to just make the changes in the main repository instead of creating another, and have an HTML version of the manual build as an an additional project? This also means no more CHM files, as long as context sensitive help can still go to the correct section.

[Crimson Wizard]

I've just created it: https://github.com/adventuregamestudio/ags-manual
If someone else wants to participate, please tell me and I could add you to contributors for this particular repository.

If trying to auto-generate the script reference, and also incorporate another repository as a general manual, is it easier to just make the changes in the main repository instead of creating another, and have an HTML version of the manual build as an an additional project? This also means no more CHM files, as long as context sensitive help can still go to the correct section.

Sorry, I am not following your suggestion. What "changes to the main repository" do you speak of, and what is the idea about having HTML pages as additional project? I thought we had intent to have all docs source in Markdown?

My point of having separate repository for the manual is that I hoped to give community members a way to freely edit the documentation. IMHO it will be very inconvenient to have them edit repository with the source code.

Generated pages could perhaps be simply pushed to the manual repository by the doc update script (same as starts generation)?

[morganw]

Sorry, I am not following your suggestion. What "changes to the main repository" do you speak of, and what is the idea about having HTML pages as additional project? I thought we had intent to have all docs source in Markdown?

My point of having separate repository for the manual is that I hoped to give community members a way to freely edit the documentation. IMHO it will be very inconvenient to have them edit repository with the source code.

HTML pages as a project within the Solution, which would render the markdown files and build the script reference from autocomplete data. I see the point about it being in a different repository though. I've been helping Erio here for the moment, so I guess he will move that across after some more cleaning up. Personally I'd prefer the script reference to be generated from where the scripts are, and then keep the rest of the manual separate, but getting the whole thing as markdown first wouldn't stop that later. I did briefly discus with Erio and Gurok who thought it wasn't worth using the autocomplete data to generate it, and they had persuaded me, until I found that the manual links to non-existent functions, and is missing at least one function entirely.

[Crimson Wizard]

HTML pages as a project within the Solution, which would render the markdown files and build the script reference from autocomplete data.

Probably this is something beyond my knowledge, because I still did not understand anything. Can you give an example, like where HTML page is kept, what it has inside, how does it "render markdown file" etc?

Personally I'd prefer the script reference to be generated from where the scripts are, and then keep the rest of the manual separate, but getting the whole thing as markdown first wouldn't stop that later. I did briefly discus with Erio and Gurok who thought it wasn't worth using the autocomplete data to generate it, and they had persuaded me, until I found that the manual links to non-existent functions, and is missing at least one function entirely.

I am myself very reluctant of having larger help text inside the script header. In fact, I noted that in my previous reply at first, but then decided to cut that out.
I see both benefit and disadvantages for either approach. I've seen how tzachs is documenting his MonoAGS API in code, with examples etc, and being documentation for coders that seem to make sense.
My biggest concern in regards to script header though is that having expanded help text there for each function and property would clutter the script API declaration and make it not easy to work with the file. Another thing is that if someone who is non-coder would like to ammend a script API article, they'd have to work with that file which is easy to break (and cause compiler error) and which cannot be previewed as MD, so all formatting has to be done either by heart or typed in some MD editor with preview first, and then copied into script header.

[morganw]

Probably this is something beyond my knowledge, because I still did not understand anything. Can you give an example, like where HTML page is kept, what it has inside, how does it "render markdown file" etc?

It is still markdown, but when you build the solution it renders the markdown to HTML (you can use something like Sphinx, or render the pages individually and add some Javascript to jump to particular sections). Then the web based manual is just a copy of the build, the Editors built in manual is also just a copy of the build.

I am myself very reluctant of having larger help text inside the script header. In fact, I noted that in my previous reply at first, but then decided to cut that out.
I see both benefit and disadvantages for either approach. I've seen how tzachs is documenting his MonoAGS API in code, with examples etc, and being documentation for coders that seem to make sense.
My biggest concern in regards to script header though is that having expanded help text there for each function and property would clutter the script API declaration and make it not easy to work with the file. Another thing is that if someone who is non-coder would like to ammend a script API article, they'd have to work with that file which is easy to break (and cause compiler error) and which cannot be previewed as MD, so all formatting has to be done either by heart or typed in some MD editor with preview first, and then copied into script header.

Maybe there is a way to cross reference the two, so one can verify the other in the short term.

I've cleaned the pages on erio's wiki: https://github.com/ericoporto/agshelp/wiki
...there are just some tables left to reformat, and I'll try to rename the file to fix the titles, but the conversion was generally pretty good.

[Crimson Wizard]

It is still markdown, but when you build the solution it renders the markdown to HTML (you can use something like Sphinx, or render the pages individually and add some Javascript to jump to particular sections). Then the web based manual is just a copy of the build, the Editors built in manual is also just a copy of the build.

Oh, you meant it other way around. At first I thought you are talking about having HTML pages as source files inside solution.
Last question, by saying "Editors built in manual", do you mean literally built-in in the executable as a resource?

[morganw]

Sorry, I was a little vague. For the Editors built-in manual, I meant replace the CHM file with the rendered HTML pages (so just include them as part of the installation) and have the builtin help shortcuts (e.g. pressing F1) open those files.

[Snarky]

Please, no. CHM is still a better format for bundled help docs than HTML (if only because the reader opens almost instantly, while a browser takes a few seconds to load).

[eri0o]

Hey, just curious what you guys think.

new organisation, some links will lead nowhere for now though...

morganw is the one that fixed most things wrong on the conversion!

edit: people already alerted me some stuff:

- resolution, aspect ratio, full-screen/windowed are important definitions to have at the start of the project, so maybe adding something on FAQ and Tutorial and linking to a page with thorough definitions on this;
- Building for different platforms how to (Windows/Linux/MacOS/Android/...).
- this is more a recurring question on Discord : how to publish your game.
- how to install ags should be on the getting started. I see CW releases the versions on the forums, is the forum the place to link there to get latest stable of AGS? I was also thinking on adding a little bit of Wine on how to install for Linux/Mac people.

[morganw]

I've checked the page links, and apparently there are 346 broken ones, out of a total of 2516. Or perhaps my link checker is broken.
Either way I'll try to fix something tomorrow.

[eri0o]

updated the README. | html page render

Moved conf.py to directory _source/, now the agshelp.wiki is cloned as directory source/ and later conf.py is copied onto it. Renamed Home.md to index.md, so that index.html is created correctly (instead of Home.html).

I noticed the \ line break is not recognised by Sphinx markdown.

I recommend using a new blank line below a line that needs a line break, it's not pretty in markdown but works. Otherwise, when there is a list of links, let it be a list of links like:

Code: Adventure Game Studio

1. - [link1name](link1)
2. - [link2name](link2)
3. - [link3name](link3)

I believe the Recommonmark plugin should understand the list of links represents a toctree and act accordingly.

Since morganw fixed a ton of inconsistencies are gone and many links works which can be seen in both the wiki and the rendered web pages.

[Crimson Wizard]

Hey, just curious what you guys think.

I'd like to propose changing the Scripting division to -
* Scripting language (with articles regarding scripting syntax and tutorials)
* Script API (with functions & properties and enums reference)
* (optionally) Template/module reference - to describe ones coming with AGS and other most popular ones.

(Right now the "Reference" chapter under "Scripting" contains random set of articles)


Another major question I have, is Sphynx potentially able to create Index out of the markdown? Imho good index may be very useful especially when looking for script functions.

[eri0o]

First, about the index, I don't know and would need to research. For this to work, one time links have to be recognized as toc tree (need to use bullets in markdown) and references like See Also must not be recognized as toc tree.

In the new Scripting Language section, are these valid topics? I really don't know how to teach programming.

Scripting Basics

First Time Scripting
- .asc and .ash extensions
- How to edit
- Hello World
- How to build and run
- Building error
- Runtime error
- Script ordering

Arithmetic and Strings in AGS Script
- Initializing Variables
- Arithmetic expressions
- Order of Operations (should have a see also link-to-big-list-of-operators)
- String
- Constants with Enum and #define

Writing less code
- Creating a Function
- Struct
- Preprocessor

Controling program Flow
- Conditional expressions with if
- Switch
- While loop
- Variable Scope and nested blocks

Arrays and pointers
- accessing arrays and pointers
- arrays and pointers in arythmetic

Managed Struct

Loading a Module

Tutorial: Pong in AGS

[Crimson Wizard]

First, about the index, I don't know and would need to research. For this to work, one time links have to be recognized as toc tree (need to use bullets in markdown) and references like See Also must not be recognized as toc tree.

I do not think it is links what define index, that sounds more like reverse-engineering an index table. Only if there's no other way, perhaps...
In Latex index keywords are assigned to articles using dedicated command. If Markdown itself does not have such feature, maybe there are special tags recognized solely by Sphynx, or maybe there is a way to assign these differently, like have a separate table of index? Personally I have no idea how this works for Sphynx, just throwing in some thoughts what I'd try to look for.

In the new Scripting Language section, are these valid topics? I really don't know how to teach programming.

I believe you could simply use existing topics for now. My proposal was merely to split current Scripting chapter in two parts. The rest could be done by community members over time.

Following existing topics could be used in "Scripting language":

Scripting tutorial part 1
Scripting tutorial part 2
Pointers in AGS
Calling global functions from local scripts
The script header
String formatting
Multiple Scripts
Understanding blocking scripts
Dynamic Arrays
Extender functions
Game variables
Script language keywords

The rest of the existing topics belongs to Script API.

[eri0o]

I think I found a way, it is the following, I would create a page like theindex.rst and create a toctree with maxdepth 4 and place only one element named index (the renamed Home.md), and then Sphinx would create an index like thing. The alternative I have is manually creating an index. This is because it's relatively hard to findout the hierarchy of a bunch of markdown files thrown in a flat folder.

[morganw]

I think I've fixed all the links, as now it only flags ones on the front page:

agshelp/checklinks agshelp.wiki/*.md

Bad link EditorRoom on page agshelp.wiki/Home.md (line 17)
Bad link EditorCharacter on page agshelp.wiki/Home.md (line 18)
Bad link EditorSprite on page agshelp.wiki/Home.md (line 20)
Bad link EditorView on page agshelp.wiki/Home.md (line 21)
Bad link EditorInventoryItems on page agshelp.wiki/Home.md (line 22)
Bad link EditorRoom on page agshelp.wiki/_Sidebar.md (line 18)
Bad link EditorCharacter on page agshelp.wiki/_Sidebar.md (line 20)
Bad link EditorSprite on page agshelp.wiki/_Sidebar.md (line 24)
Bad link EditorView on page agshelp.wiki/_Sidebar.md (line 26)
Bad link EditorInventoryItems on page agshelp.wiki/_Sidebar.md (line 28)

Found 888 pages/anchors
Total links: 2706
Bad links: 10

I've also switched the the line breaks from \ to double spaces, which makes it format correctly in "unflavoured" Markdown editors, but the Sphinx build still doesn't seen to pick it up. I guess there might be an option to pickup the double space, if not I'll look at converting these lines into lists.

[eri0o]

Hey morganw! I am doing something wrong because I get an error on everything...

here in the .travis.yml, the third line after script, has the line of how I am running the link checker. the result is being placed here on every build

I have the same error on my computer ( Ubuntu 16.04, awk 4.1.3 )

Also, on the Travis-CI, it's being triggered by the agshelp repository instead of the agshelp.wiki repository. I don't know if I can trigger by changes on the wiki, but will check it out if it's possible!

[morganw]

I have the same error on my computer ( Ubuntu 16.04, awk 4.1.3 )

I think it should be fixed now.

[eri0o]

it is!

[morganw]

I've created the 3 missing pages, so the build gets deployed again. I also changed the build to work with a symlink for the index page, so now all the config and template options can stay in the other repository. This was mainly to get the build date onto the page, which isn't part of the alabasta theme for some reason, so now you can actually see that deployed HTML has actually been changed.

Slight issue, in that the link checker is now checking links in the symlink (so errors in Home.md are shown twice), so I'll have a think about how to fix that.

To sum up, changes that are valid should now be appearing here: https://ericoporto.github.io/agshelp/

[Crimson Wizard]

Cool!

One thing I noticed so far is that tables did not port properly, for example here:
https://ericoporto.github.io/agshelp/UpgradeTo33

obsolete function/variable replace with SetVoiceMode Speech.VoiceMode SetSkipSpeech Speech.SkipStyle SetSpeechStyle Speech.Style game.close_mouth_end_speech_time Speech.AnimationStopTimeMargin game.speech_text_align Speech.TextAlignment game.skip_speech_specific_key Speech.SkipKey game.talkanim_speed Speech.GlobalSpeechAnimationDelay

[morganw]

I had to redo the tables manually as the original Markdown had no table support, and the lack of conversion just gave rows of dashes which are valid Markdown. I'll see if I can search for any I've missed and redo them. They are pretty easy to make using the GitHub Markdown variant. I tried to post an example, but unfortunately it contains 3 dashes.

[morganw]

I think I've found all the tables and have finished fiddling with the checkout script. It'll now work on Windows with the BASH shell you get from the Git installer, the Windows Subsystem for Linux (TM), or the standard Bourne shell. It didn't work previously on Windows as I hadn't realised that Git on Windows disables the use of symlinks by default. Perhaps there is a better way to build without modifying the source, which doesn't use a symlink...

I need to take a break and work on something else for a while, but I'll check back in to see what happens with the recruitment thread.

[Crimson Wizard]

Thank you Looks like the manual finally getting to the better version.

Unfortunately I found another broken table, and its HUGE, but maybe I will find time to fix it myself later today. Still did not try out how editing this thing works.

[eri0o]

Morganw, you are amazing, you fixed so much stuff that went wrong with the conversion! And that checklinks script is a life saver!

Hey! Thanks to CW, the repo is being moved to here : github.com/adventuregamestudio/ags-manual !

The other one still works, and for the time being, I will port any modification manually from one to the other, but once TravisCI is working and building correctly on the new one, it should be the correct one to develop for!

Edit:

It's live here: adventuregamestudio.github.io/ags-manual/

morganw and snarky, please use the  ags-manual under adventuregamestudio !!!!

[Crimson Wizard]

I just realized what bothers me most about editing wiki instead of having manual pages in repository: it's impossible to distinct between versions. How are we going to tell which version of the page belongs to which version of the AGS?
How that would be possible to build manual for the older version if we need to release a patch?

[morganw]

I think eri0o has already set it up so that built html and chm file have a release tag, and I think the wiki repository can also have a tag.

[eri0o]

The wiki is just a repo, so it can have branches. Unfortunately the interface only supports editing the master branch. The branches have to be edited locally.

github wiki help on branches

But the sad part is using the wiki, looses the cool github repo interface.

What we can do is have the content in another repo, or the same repo, with branches.

The releases themselves have tags - currently they are a snapshot of the mds and a chm. The github pages only follow the latest master.

[Crimson Wizard]

Oh, so its like a real repository, only not shown as one on github? But it's possible to access using git from your computer?

[eri0o]

yes! So... I've been thinking... The original idea of the wiki was to have more contributions, since we needed the manual entry for the Editor stuff (how to use the room editor, place an object, it's properties on the editor, edit a GUI, create inventory items, ...).

I think it's better if we use the wiki to generate the manual for AGS 3.5.0 an then on store the pages on the own repo and use the normal PR+issues for contributions on the manual pages. (since the wiki isn't exactly a king in popularity)

I like the idea of just using a branch per ags version and all.

Also, later, the html generated pages should have a downloadable .zip on the release page, and then we can create a task that unzips the releases on separate folders on gh-pages... This is for The Future ™ .??:

Edit: CW, do you know what is needed for f1 to work with the generated .chm inside AGS ?

[morganw]

When I checked recently, I think there was an extra file present which looked like it had some extra index data in it. It does work at the moment when the script keyword matches an index name, so any issues could be just the lack of indexing, or the missing of the extra file.

[Crimson Wizard]

Edit: CW, do you know what is needed for f1 to work with the generated .chm inside AGS ?

Editor sends command to the help file using Help.ShowHelp from .NET.
For context-sensitive help the "command" is KeywordIndex and parameter is for example script function name.

According to the page, compiled help must have "keyword index" inside.

I don't think if any extra files are required, albeit maybe for CHM generation.