Moving default documentation for online docs

Started by eri0o, Sun 02/09/2018 19:26:24

Previous topic - Next topic

eri0o

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

#1
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?

Snarky


eri0o

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

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.
[img]http://7d4iqnx.gif;rWRLUuw.gi

Snarky

Quote from: eri0o on Mon 03/09/2018 03:16:41
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

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

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-)

eri0o

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

Quote from: Snarky on Sun 02/09/2018 22:07:43
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. ???

eri0o

#10
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!

eri0o

Just to report the chm now has the content section showing up correctly and the links to self in a topic are also fixed.

If someone wants to contribute writing about the AGS Editor, the manual still has empty sections

SMF spam blocked by CleanTalk