Wiki manual pages out of date

Started by cat, Fri 08/12/2017 14:12:19

Previous topic - Next topic

cat

Quote from: Crimson Wizard on Tue 05/12/2017 15:51:06
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

Quote from: cat on Fri 08/12/2017 14:12:19
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

Quote from: Crimson Wizard on Fri 08/12/2017 14:38:23
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

#3
Quote from: cat on Fri 08/12/2017 14:51:14
Quote from: Crimson Wizard on Fri 08/12/2017 14:38:23
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:
Quote
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

Quote from: cat on Fri 08/12/2017 15:44:08
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.


Quote from: cat on Fri 08/12/2017 15:44:08
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

Quote from: cat on Fri 08/12/2017 16:25:05
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

Quote from: Crimson Wizard on Fri 08/12/2017 16:34:09
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

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

Quote from: selmiak on Sun 11/03/2018 11:46:15
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.

Quote from: selmiak on Sun 11/03/2018 11:46:15May 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

#15
Quote from: Crimson Wizard on Sat 10/03/2018 18:14:27
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"?

Quote from: AGA on Tue 13/03/2018 06:16:09
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... :P

Crimson Wizard

Quote from: AGA on Tue 13/03/2018 06:16:09
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.


Quote from: selmiak on Tue 13/03/2018 09:53:26
Quote from: Crimson Wizard on Sat 10/03/2018 18:14:27
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).

SMF spam blocked by CleanTalk