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

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