Comments on 'Run from Source Code' wiki page and Spell Checker documentation

[kakaroto]

Replying to comment from https://github.com/olivierkes/manuskript/pull/583#issuecomment-520499263

Perhaps @kakaroto can test these and also check the instructions?

I don't have the time lately to test any of that, but back when I wrote it, I did test all combinations of spellcheckers on linux, windows 10 (32 bit and 64 bit python).

I do have a couple of comments about the instructions, though since this is long and it might spark a new discussion, I didn't want to hijack the other issue so I created a separate issue to discuss things.

With regards to the spellcheckers, it all looks good to me. I would put the It does not come with any dictionaries of its own, but if pyspellchecker is installed, manuskript will use those in conjunction with symspellpy. (or a shortened version of it) within the italic part for symspellpy as that seems to list the pros and cons and someone might just read the italic part and say "oh, it's faster, i'll use that" then wonder why it doesn't have any languages.

It might be a good idea to finally have that wiki page that explains how to create new spellcheck dictionaries for symspellpy from my comment here : https://github.com/olivierkes/manuskript/issues/505#issuecomment-466632839 I'm referring specifically to this part of the comment :

I thought to suggest putting that information in that page, but it would probably be better on its own page (a "how to create symspellpy dictionaries") and just link to it from the 'run from source' page. Note that my instructions were on linux and I didn't try to install aspell on windows (I do think it exists) to see if the commands work the same.

The "Install Git and Manuskript" refers to installing Git and using command line tools, which may not be the easiest way for most people. I personally used TortoiseGit which makes it much easier, and since this is on github, there's also Github Desktop which might be more user friendly than command lines as well. You also give the git clone command and mention git pull but people reading these kinds of guides would probably be pretty clueless so it might be better to :

• Link to already created guides that might be more exhaustive such as https://help.github.com/en/articles/set-up-git or https://help.github.com/en/articles/getting-changes-from-a-remote-repository
• Mention the 'download zip' method since someone who wants to 'run from source code' doesn't necessary mean 'run a development version using git'. There are easier ways to download the latest source code and run it without having to deal with git (remember the target audience of such a guide).

Finally, in Appendix A, step 2 has pyenchant in the list of dependencies to install. I would remove it and mention "optionally a spellchecker and pandoc as described earlier" instead in step 3.

[worstje]

I was the one to amend the run-from-source on Windows instructions, but only because I noticed they were lacking while looking up some other version-related details. You can amend whatever you feel is correct to amend yourself, I reckon.

Same for the stuff on the dictionaries. Honestly, I have no clue how they work, or how to do them on linux, or how to add the dictionaries, nor any interest in learning just to amend that particular part of the instructions... so a separate page written on that by someone who knows the guts of those particular bits of manuskript is probably the most sensible way to go here? I think you did half the work already by just making this post.

Good point on the downloading from zip for Windows. Including that might be useful. I thought that was in there already, but I think that is only on the Linux one. (Which may or may not need some changes to accomodate spellcheckers and dictionaries, too.)

[gedakc]

Thanks @kakaroto for creating a new issue for this discussion. Improving the documentation is an excellent goal, and something we can strive for over time. We are all busy so this typically happens when the "itch to fix" gets strong enough to pull our attention from other work.

Fortunately for us PyEnchant, although not actively supported, is a fully function spell checker that works on all of the OS platforms we currently support (with the known exception of 64-bit python on Windows). Hence I do not see a pressing need to migrate all platforms to a different spell checker. Further it is possible that someone may pick up development of PyEnchant. I know this happens because I've done this myself with other Free Software projects, such as GParted and this project. :-)

Based on what I've observed, the majority of Manuskript users download and install one of the packages, and do not install from source code. Hence the "Run from Source Code" instructions are more likely to be followed by users (or potential developers) trying to help us out with an issue. As such we can offer help as needed while we are troubleshooting an issue with them.

In conclusion I think this spell checker documentation issue is a good first step at capturing the required information. Hence I have added a link to this issue on the Run Manuskript from Source Code on Windows wiki page.