Wiki manual pages out of date

[cat]

Wiki is like 10 years old compared to recent release, it is not even updated to AGS 3.2.1 (last version made by Chris Jones).
(I feel like repeating this for the 10th time in past couple of years, because people keep getting into similar situation ).

Maybe we should mark those wiki pages on the top of the page? We could make a banner that says "This article is outdated and only applies to old versions of AGS"

[Crimson Wizard]

Maybe we should mark those wiki pages on the top of the page? We could make a banner that says "This article is outdated and only applies to old versions of AGS"

Actually, all of the wiki pages that cite manual are outdated, and probably relate to AGS 3.1.*.
The separate online manual is corresponding to AGS 3.2.1.
IMO actual solution is in configuring a repository for documentation source, which anyone can edit, and which automatically builds online and offline version of the manual.

[cat]

Actually, all of the wiki pages that cite manual are outdated, and probably relate to AGS 3.1.*.

Are they in a common category so they are easy to find? I really think we should mark them as outdated, so people know what they are dealing with.

[Crimson Wizard]

Actually, all of the wiki pages that cite manual are outdated, and probably relate to AGS 3.1.*.

Are they in a common category so they are easy to find? I really think we should mark them as outdated, so people know what they are dealing with.

Can't say if category is consistent (I hope so), there is one called "Manual entries".
There seem to be a plain copy of whole manual starting of the root page.

BTW, there is already a small message at the top of each page:

This page was last modified 19 August 2012, and could be out of date with the current AGS version.

Maybe people don't notice it?

[cat]

Ok, this is the template:
http://www.adventuregamestudio.co.uk/wiki/Template:Manual_entry

It links to http://www.bigbluecup.com/manual/ which, of course, doesn't work anymore. Is there an online version of the current manual somewhere? I'd try to update the template and add a warning about the outdatedness of those pages.

Oh, could you maybe split this discussion into a new thread? It is not related to the original topic anymore.

[Crimson Wizard]

It links to http://www.bigbluecup.com/manual/ which, of course, doesn't work anymore. Is there an online version of the current manual somewhere?

There's one linked on the AGS home page: http://www.adventuregamestudio.co.uk/manual/
It is also outdated and corresponds to 3.2.1.

Oh, could you maybe split this discussion into a new thread? It is not related to the original topic anymore.

Done.

[cat]

So, there is no current version online? Is the chm file somewhere downloadable? Shall we link there? Or just add a note to use the manual that was shipped with AGS?

[Crimson Wizard]

So, there is no current version online? Is the chm file somewhere downloadable? Shall we link there? Or just add a note to use the manual that was shipped with AGS?

CHM is not the best way to distribute or link to, because it is only (officially) supported by Windows.
But when creating CHM the intermediate output is HTML files, which probably may be uploaded somewhere. Maybe that was the way online manual created?

[cat]

Maybe that was the way online manual created?

Hm, probably. Can we do this again once the 3.4.1 is finished?

[Crimson Wizard]

Hey, can we actually replace the online manual now? It is about 8 years old, and I cannot even link an article to new feature when replying on forums.

To remind, the manual at http://www.adventuregamestudio.co.uk/manual/ is seemingly made of the HTML files which are an intermediate output of the manual CHM file building process. This means that one could just run manual generation in the repository, and take HTMLs instead of final CHM, and upload them to site.

The manual in wiki pages should perhaps be removed, and link point to the http://www.adventuregamestudio.co.uk/manual/.
If someone wants to work on the manual, they could do that in git repository.

At least that way we would finally have synchronized documentation.

[Gilbert]

I think it was Monkey0506 who started the Wiki's manual pages. I've told him that it's not very useful and would become outdated quickly, but he promised he would maintain it.
Given that the Wiki is now at a stale state (I think except during awards periods the only member who actively modifies it is me, which only means... the Hall of Fame page), I agree that it is no longer relevant, and if not outright remove it, we should at least update the warning to signify it's no longer up to date.

[selmiak]

This is great progress and a wiki synched with the manual delivered with AGS is very convenient. May I propose the goal to have the AGS builts on git and on the adventuregamestudio.co.uk domain rebuild and update every time someone changes the manual, or better once a day if a change was made to the manual.
I wouldn't remove the manual pages in the wiki, rather add a fat and bold header to show it is outdated and a link to the new version of that specific page on git. below the warning and link there should still be the old version of the text. Or maybe I'm just about keeping old stuff because I like 320x200 px point and clicks, propably it is better to just have the link, but to the correct page on git to avoid search engine confusion and double entries with old and up to date versions. So I'm wondering, can the old outdated text be kept on the wiki below the link, maybe even with smaller font and be hidden from search engines?

[eri0o]

I was never able to edit the wiki. If I recall, I started in the forums just to complain about this with AGA.

[Crimson Wizard]

I don't see why keeping manual in the wiki, outdated or not, but that's not the main point.
What I mean is to replace the manual pages at http://www.adventuregamestudio.co.uk/manual/ if possible.
That would be enough for starters.

This is great progress and a wiki synched with the manual delivered with AGS is very convenient.

What progress? Nothing is done. This is why I keep posting here.

May I propose the goal to have the AGS builts on git and on the adventuregamestudio.co.uk domain rebuild and update every time someone changes the manual, or better once a day if a change was made to the manual.

Oh well, I suggested this year or two ago.
The biggest question is how to upload it to site. Besides that, it's mainly a matter of running a python script found in repository.

[AGA]

I can give you (or whoever) access to that folder, the same way you do for releases, CW.  Somebody needs to take responsibility for getting (and keeping!) it up to date though...

[selmiak]

To remind, the manual at http://www.adventuregamestudio.co.uk/manual/ is seemingly made of the HTML files which are an intermediate output of the manual CHM file building process. This means that one could just run manual generation in the repository, and take HTMLs instead of final CHM, and upload them to site.

That sounded like these html files are stored on the github servers somewhere already. Sorry that I got you wrong there CW. I know too little about building files on and with github to help there. The problems seem not to be the generation of the html files but the where to store them and how users can access the generated manual html pages? on git or on ags.co.uk, you just said "site"?

I can give you (or whoever) access to that folder, the same way you do for releases, CW.  Somebody needs to take responsibility for getting (and keeping!) it up to date though...

Is there some scp command running from wherever to copy the files from git to ags.co.uk or do you manually download the files from github after building and then manually upload the files to the server CW or AGA? I think it is useless to do that for every little change in the manual!
What about a cronjob on the ags server that checks once a day if some changes happened on the AGS git repo builts and then gets these files, no matter if .exe files for AGS or .html for the manual pages. So much for the theory...

[Crimson Wizard]

I can give you (or whoever) access to that folder, the same way you do for releases, CW.  Somebody needs to take responsibility for getting (and keeping!) it up to date though...

I could at least upload these once for 3.4.1, because manual is 8+ years old already. What happens next is a question of who is going to maintain the thing.

To remind, the manual at http://www.adventuregamestudio.co.uk/manual/ is seemingly made of the HTML files which are an intermediate output of the manual CHM file building process. This means that one could just run manual generation in the repository, and take HTMLs instead of final CHM, and upload them to site.

That sounded like these html files are stored on the github servers somewhere already. Sorry that I got you wrong there CW. I know too little about building files on and with github to help there. The problems seem not to be the generation of the html files but the where to store them and how users can access the generated manual html pages? on git or on ags.co.uk, you just said "site"?

The HTML files are not stored on github repository, they may be generated from the sources (in LeX format) found on github repository (using a script located in the same place). This is how we build manual for AGS releases. HTML pages are intermediate output in this process: first LeX is converted into html, then CHM file is built from html. HTML pages themselves are not stored anywhere. But they may be taken and copied to the AGS website.

[morganw]

What is there is terms of server infrastructure, now that TeamCity is gone?
If there is nothing but the webserver, can it pick up tagged releases with git or is it more generic/restricted web hosting?

[AGA]

We run a Linux virtual server with root access, so in theory could do whatever we want.

[morganw]

I would think that if each new release was tagged on Github, and release binaries were also on Github, it would be possible to link everything so no-one has to be manually editing things when a new version is released. They have a REST API where you can query for the latest release and its download link, so worst case, you just query for the latest "stable" release and build static pages on the web server. The python requirement is for additional passes after conversion from LaTeX (so those changes could be done with sed or awk if you don't want python installed) but I imagine it wouldn't be too difficult to just make the intermediate HTML pages part of each release (so include a static HTML site as well as the CHM manual).

[Crimson Wizard]

I pmed this to AGA, but will duplicate it here too.

So, today I tried to upload new manual content to the website, but some issues were found, so had to revert.

1. Pages on website use styles from external css file. While pages generated in repository have embedded css, and they are different (background, font, etc).
2. Pages on website have some additional script for toolbar display.
3. Website manual has additional html pages for contents, index etc. Manual in repository does not generate html pages for these. This means that even if I upload new topic pages, the contents tree will remain 3.2.1, and links won't match.

Would it be possible to find out who have created this online manual, and how?

[selmiak]

a link would be helpful?
to all pages, the old page on ags, the new page on ags, the new page on git please.

[Crimson Wizard]

to all pages, the old page on ags, the new page on ags, the new page on git please.

Existing manual: http://www.adventuregamestudio.co.uk/manual/
Random page on existing manual: http://www.adventuregamestudio.co.uk/manual/ags1.htm

Current manual source on git: https://github.com/adventuregamestudio/ags/tree/master/Manual
To build html pages: run run.cmd (may have to install Python 2.7).

Archive containing both versions for comparison: https://www.dropbox.com/s/v958t0938w76cyk/AGS--manualpages.zip?dl=0

[selmiak]

wohah, there is also an outdated manual on the ags server... all the time I was thinking you were talking about this manual-wiki: http://www.adventuregamestudio.co.uk/wiki/Contents_(manual)
which is hosted on the same domain but even more outdated! This is a mess, time for some spring clean up

So my opinion on this is, one of the 2 manuals  on adventuregamesudio.co.uk has to go. Whichever one is easier to update from one source should stay, so probably the static manual you just linked to should stay, if at all. we need _one definite source_ for the manual. There the wiki I just linked would be great as everyone can edit and update with a forum account. But then all the changes would have to be transfered to git again. So my conclusion is, the definite source for the manual should be on github, where it is already and where the binaries of the engine are too. This also means, all these wikipages in the http://www.adventuregamestudio.co.uk/wiki/ domainrange either just disappear or redirect to... either the manual on http://www.adventuregamestudio.co.uk/manual/ or to the manual on github. oh the messy confusion...
It is kind of bitter and if some interested person wants to write some good changes to the manual, this person first needs to make a github account. This could be a barrier for some, but if you really want to help make the AGS manual better this should not stop you. my opinion, not a fact. it sure is convenient to have the option to write changes to the wiki with a forum account, but who does that anyways, so imho github is the main source...


just out of curiosity, how would you change stuff in the manual on git? How do you edit this:
https://github.com/adventuregamestudio/ags/blob/master/Manual/htmlfiles/acintro.htm
and is there a way to display the html on github as it would show in the browser or within the AGS helpwindow?

[Crimson Wizard]

wohah, there is also an outdated manual on the ags server... all the time I was thinking you were talking about this manual-wiki:

I clearly stated what I was talking about, posting the link several times, starting since very first posts in this thread.

just out of curiosity, how would you change stuff in the manual on git?

By learning how to use github and text editor.

https://github.com/adventuregamestudio/ags/blob/master/Manual/htmlfiles/acintro.htm

These are some unused files that should have been deleted. The actual manual source is in file called "ags.tex" which is a LaTeX document.

[selmiak]

sorry, my fault, I just assumed you were talking about this /wiki manual and didn't know that /manual was something different but somehow the same and just didn't click the link. sorry for wasting your time and making you post the links once more.


The ags.tex has (WARNING) very long loading times.
Is this the WHOLE MANUAL delivered with the AGS editor in ONE FILE??? That is nice and a great source. But then you'd have to know or learn LaTeX to edit the manual, which is another barrier, but it's like that it seems.

[selmiak]

what about this for a start?
http://www.adventuregamestudio.co.uk/wiki/Credits_(manual)

[Crimson Wizard]

Is this the WHOLE MANUAL delivered with the AGS editor in ONE FILE??? That is nice and a great source. But then you'd have to know or learn LaTeX to edit the manual, which is another barrier, but it's like that it seems.

I do not know if this was sarcasm, but having it in one file does not really make it a great source, because it makes it difficult to search and edit.
For that reason the solution that was proposed and discussed long time ago was to change format to something else, even if plain html.
Here is a link to related discussion: http://www.adventuregamestudio.co.uk/forums/index.php?topic=51340.0
This is where we discussed possible formats, having manual source only in one place, automatic upload to site, and so on.

Since that thread exists I did not want to discuss it here again, because I practically have to repeat myself multiple times. I was posting here for only one reason: trying to update online manual to the latest 3.4.1 version.

Wiki is a separate question. I would not care about it much if lots of people would not rely on it thus sticking to outdated material.

what about this for a start?
http://www.adventuregamestudio.co.uk/wiki/Credits_(manual)

What about it?

[selmiak]

what about this for a start?
http://www.adventuregamestudio.co.uk/wiki/Credits_(manual)

What about it?

the forum software screwed up the link, click it again in my edited post...

[Crimson Wizard]

You probably should not be editing each page individually. As cat mentioned in her post above, there is a template for "manual entry" which supposed appears on every page in manual category:
http://www.adventuregamestudio.co.uk/wiki/Template:Manual_entry

But, wiki is not interesting to me, I do not want to decide anything about it.

[selmiak]

Is this the WHOLE MANUAL delivered with the AGS editor in ONE FILE??? That is nice and a great source. But then you'd have to know or learn LaTeX to edit the manual, which is another barrier, but it's like that it seems.

I do not know if this was sarcasm, but having it in one file does not really make it a great source, because it makes it difficult to search and edit.

not really sarcasm, just too quick to post, it is a great source as it is all in one place, but somehow I clicked send before writing down what you wrote down. split it in parts to make it load faster and easier to edit and all the format changes from the other threads... but for that, the other thread is there, push it to restart the discussion or do something, I have no idea about LaTeX or .chm formats or whatelse is out there

[selmiak]

You probably should not be editing each page individually. As cat mentioned in her post above, there is a template for "manual entry" which supposed appears on every page in manual category:
http://www.adventuregamestudio.co.uk/wiki/Template:Manual_entry

But, wiki is not interesting to me, I do not want to decide anything about it.

direct links would be more convenient, but there you go, the manual entry template now also links to the /manual

[Crimson Wizard]

Can we please, REMOVE the manual from Wiki? People KEEP referring to these pages, because apparently the warning is not distinct enough. They don't find functions they need and assume they don't exist, then ask how to script things.

[Gilbert]

I think, at least the link in the WIKI's front page should be updated to the external one from the AGS site. Couldn't do this though as it requires admin right to edit the front page it seems.

[Crimson Wizard]

Can we please, REMOVE the manual from Wiki? People KEEP referring to these pages, because apparently the warning is not distinct enough. They don't find functions they need and assume they don't exist, then ask how to script things.

BUMP.
It happens again: https://www.adventuregamestudio.co.uk/forums/index.php?topic=56826.msg636600584#msg636600584

I think, at least the link in the WIKI's front page should be updated to the external one from the AGS site. Couldn't do this though as it requires admin right to edit the front page it seems.

I cannot edit the main page either...
Still I'd suggest to remove these manual pages completely. After all, if old manuals have any historical value they are packaged within corresponding AGS editors, and these may be downloaded from agsarchives torrent (https://www.agsarchives.com/agsarchives.torrent).

[Gilbert]

The problem was that the Engine Limit page was not marked "Manual Entry" so it did not have that large warning box on top of it.
I've now deleted all the pages marked as "Manual Entry" (with the first page giving a link to the updated online manual, as this page is still being linked by the Main page) plus the Engine Limit page.
There are certainly many other outdated pages but I'd rather leave them as-is and only act "on-demand" to avoid complications.