Author Topic: Moving default documentation for online docs  (Read 676 times)

Moving default documentation for online docs
« on: 02 Sep 2018, 19:26 »
Hello,

I would like to suggest moving the default ags manual to a online help, and f1 just running a search on this online help in the user own browser. Most softwares uses online manuals these days.

We are hitting some hard issues to support using the current .chm help with easier to edit and maintain help. The new help gives per topic markdown files that can be edited online instead of the old 22k lines of LaTeX text file and a ton of magic.

Here is how is the online manual now:
https://adventuregamestudio.github.io/ags-manual/index.html

And here is the repository for it:
https://github.com/adventuregamestudio/ags-manual

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Moving default documentation for online docs
« Reply #1 on: 02 Sep 2018, 20:02 »
I thought the idea was to install HTML pages locally and open them from the Editor's folder? Or is it what you mean?

Regarding context help, is not there any way to open actual page with correct paragraph instead of showing search results?
« Last Edit: 02 Sep 2018, 20:10 by Crimson Wizard »

Snarky

  • Global Moderator
  • Mittens Earl
  • Private Insultant
    • I can help with proof reading
    •  
    • I can help with translating
    •  
Re: Moving default documentation for online docs
« Reply #2 on: 02 Sep 2018, 22:07 »
I strongly object to this suggestion.

Re: Moving default documentation for online docs
« Reply #3 on: 03 Sep 2018, 03:16 »
Snarky, the suggestion being moving from .chm to a folder with .html files or hosting online? Would it be ok if it was a folder with html files on the ags install folder?

Gurok

  • Rottwheelers
  • When life hands you lemons, combine them with the mop
    • I can help with AGS tutoring
    •  
    • Best Innovation Award Winner 2016, for improving and extending the AGS scripting language
    •  
    • I can help with proof reading
    •  
    • I can help with scripting
    •  
    • Gurok worked on a game that was nominated for an AGS Award!
      Gurok worked on a game that won an AGS Award!
Re: Moving default documentation for online docs
« Reply #4 on: 03 Sep 2018, 03:39 »
My personal feeling is that this issue is possible to fix but was bigger than you expected. I don't think a different solution is required. I think the alternative would defeat the purpose of this task. The idea, as I understand it, was to synchronise the two help systems (web and CHM) and retain the convenience of the manual with all of its features.
It isn't uncommon that open source tools are deficient in some way. I think you should wait and let morganw have a go at fixing the index.
I'm not sure what the basis is for "most software uses online manuals these days". I have quite a bit of software that ships with CHM, and I think you'll find a lot of the Windows-specific stuff out there still uses CHM even though Microsoft have abandoned it. It's always a shame to me when I encounter an application that points me to a website for help or worse, has help that lists keyboard shortcuts in a modal dialogue. It would be an even greater shame for a project that has a CHM-based manual to lose it because creating a system to keep it up to date was "hard". Partly because it's very user friendly, but also because you have the correct output already and only have to devise a system that produces output matching what exists.

Snarky

  • Global Moderator
  • Mittens Earl
  • Private Insultant
    • I can help with proof reading
    •  
    • I can help with translating
    •  
Re: Moving default documentation for online docs
« Reply #5 on: 03 Sep 2018, 06:20 »
Snarky, the suggestion being moving from .chm to a folder with .html files or hosting online? Would it be ok if it was a folder with html files on the ags install folder?

Both, and no. I think the convenience of CHM is one of the main things that makes the AGS help system so good. Just press F1, and it opens instantly, at the article for whatever you highlighted. A browser-based solution cannot offer that.

Gilbert

  • * KILL* * KILL * * KILL *
    • Lifetime Achievement Award Winner
    •  
Re: Moving default documentation for online docs
« Reply #6 on: 03 Sep 2018, 07:11 »
Personally I wouldn't mind dumping the CHM file in favour of loose html pages or other more accessible formats(I think the CHM format is becoming obsolete and there are still people having permission problems viewing such files, etc. right?).
However, I strongly disagree to have the manual online only. If the editor could still be used without the system being online(I think? unless things had changed recently) why would the manual be online only? Some computers aren't always connected to the web for various reasons.

selmiak

  • ǝsıɔɹǝxǝ ʞɔǝu puɐ uıɐɹq
    • I can help with play testing
    •  
    • I can help with proof reading
    •  
    • I can help with translating
    •  
    • I can help with web design
    •  
    • selmiak worked on a game that was nominated for an AGS Award!
Re: Moving default documentation for online docs
« Reply #7 on: 03 Sep 2018, 20:58 »
can't we just use sphinx or some open source tool to manage the content and then add CHM output support to the feature suggestions and add a link to that to the forum banner and +1 it to the top priority and get it coded by someone else that eventually knows what he's doing and has fun doing it  :-D 8-)

Re: Moving default documentation for online docs
« Reply #8 on: 04 Sep 2018, 01:50 »
selmiak, the problem is literally sphinx. We are using it. It has bugs. Gurok is right, the issue is bigger than I expected. I think maybe morganw can fix, so I will wait.

About offline pages, the html we build have search implemented through a very lean javascript code, and it works offline and it's reasonably fast - faster than chm on my machine.

Danvzare

  • The Man with No Name
    • I can help with AGS tutoring
    •  
    • I can help with proof reading
    •  
    • I can help with scripting
    •  
    • I can help with voice acting
    •  
Re: Moving default documentation for online docs
« Reply #9 on: 05 Sep 2018, 15:13 »
I strongly object to this suggestion.
Same here, I hate it when I go to open a manual for a program, and my internet browser opens up, and then I have to wait a few seconds for the page to load. It's even worse when I'm not currently connected to the internet or it's having problems identifying what my default browser is.

I'd rather have an outdated manual than an online one any day.
I've had too many problems with online manuals. Especially searching in them for some reason. ???

Re: Moving default documentation for online docs
« Reply #10 on: 31 Oct 2018, 01:42 »
Hey, just to report that after a lot of effort from morganw we have working chm building from the wiki here and also a website with search building from the wiki so the help is successfully both online and offline!

>> github.com/adventuregamestudio/ags-manual <<

Please check the website. The wiki is open for contributions if anyone is interested, just pop a github account :]

Everything is built on the cloud, so just a browser is enough to contribute!
« Last Edit: 31 Oct 2018, 01:44 by eri0o »