Author Topic: Help file... here we go again. (Read 13776 times)

eri0o · « **Reply #60 on:** 17 Jul 2018, 12:20 »

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 · « **Reply #61 on:** 17 Jul 2018, 12:31 »

Quote from: eri0o on 17 Jul 2018, 12:20

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.

Quote from: eri0o on 17 Jul 2018, 12:20

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":

Quote

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 · « **Reply #62 on:** 17 Jul 2018, 14:41 »

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 · « **Reply #63 on:** 18 Jul 2018, 00:16 »

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

Quote

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 · « **Reply #64 on:** 18 Jul 2018, 02:10 »

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 · « **Reply #65 on:** 18 Jul 2018, 08:08 »

Quote from: eri0o on 18 Jul 2018, 02:10

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

I think it should be fixed now.

eri0o · « **Reply #66 on:** 18 Jul 2018, 10:31 »

it is!

morganw · « **Reply #67 on:** 19 Jul 2018, 19:08 »

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 · « **Reply #68 on:** 19 Jul 2018, 19:20 »

Cool!

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

Quote

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 · « **Reply #69 on:** 19 Jul 2018, 20:00 »

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 · « **Reply #70 on:** 20 Jul 2018, 11:41 »

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 · « **Reply #71 on:** 20 Jul 2018, 13:02 »

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 · « **Reply #72 on:** 26 Jul 2018, 01:53 »

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 · « **Reply #73 on:** 29 Aug 2018, 22:40 »

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 · « **Reply #74 on:** 29 Aug 2018, 23:30 »

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 · « **Reply #75 on:** 30 Aug 2018, 00:12 »

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 · « **Reply #76 on:** 30 Aug 2018, 00:32 »

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 · « **Reply #77 on:** 30 Aug 2018, 00:41 »

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 · « **Reply #78 on:** 30 Aug 2018, 17:07 »

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 · « **Reply #79 on:** 30 Aug 2018, 17:36 »

Quote from: eri0o on 30 Aug 2018, 00:41

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.