Documentation: instruct exactly how to start/spawn Koreader

[m040601]

Hi, thank you for your work in this very usefull tool. I have 3 suggestions for making the documentation crystal clear and more straightforward for first time users. Maybe this all seems pointless and "obvious" to you, because you're the creator and are already intimate with Nickelmenu.

1. The name you choose for the file, "doc" is a little bit confusing.

It took me a while to realize that this file is both a "doc" in the sense of containing instructions, and a "config" file, in the sense that you comment out what you want to configure the menu.

Yes, of course, it's all written there. You can even name it what you want, split it etc. But either I'm getting too old or I feel it could be made more intuitive this way.

Maybe you could rename it into Readme.txt and place it in a folder called "docs" or "help" under the folder "nm" ?

Then create a file called nm.config or nm.config.example with just a couple lines. Only the most importat lines and commented out.

2. More crystal clear what you get on the "box"

You do have it on the README front page:

After it installs, you will find a new menu item named NickelMenu with further instructions which you can also read here.

"Here" also means, the "doc" file is also placed on the Kobo device itself, so could you please update the README to be less confusing for first time users. Something like:

After it installs, you will find a new menu item named NickelMenu. A file named "doc" was placed under ".adds/nm/" with further instructions. You can also read that file online, https://github.com/pgaskin/NickelMenu/blob/master/res/doc

3. Koreader

I guess the number one reason most people install it, is to use it also with Koreader.

You do document extensivly how to customize the menus. It's a big file, with examples for telnet and everything.

But not a single line on how to "correctly" start Koreader ! Please also remember, that not everyone wants the install the Koreader version prebundled with Nickelmenu and Kfmon.

I currently start Koreader from Nickelmenu with:

menu_item :main :Start Ko spawn :cmd_spawn :/mnt/onboard/.adds/koreader/koreader.sh

But I am not 100 % sure . I would like to see it written by you in the example config. I dont' want to be jumping from the example file or the docs to forum postings on mobileread and back to the docs for such an important thing.

Please dont force people to go online to the forum to get ideas how to customize Nickel Menu for basic things. Documentation should be self contained and offline.

If you have other cool examples, put them also in the docs distributed.

Thanks in advance

[NiLuJe]

Out of scope?

Shockingly enough, when searching for documentation about installing KOReader, you should look at... the KOReader documentation.

[pgaskin]

It took me a while to realize that this file is both a "doc" in the sense of containing instructions, and a "config" file, in the sense that you comment out what you want to configure the menu. Maybe you could rename it into Readme.txt and place it in a folder called "docs" or "help" under the folder "nm" ?

That decision was made quite carefully for multiple reasons.

1. We don't want users to make changes to it, as it will be replaced when updating NM (i.e. you aren't supposed to realize it's a config file).
2. If it's a .txt file, Nickel will import it as a book. Although this could arguably be a feature, some people may not want it.
3. It serves as a placeholder for the config folder.

More crystal clear what you get on the "box" "Here" also means, the "doc" file is also placed on the Kobo device itself, so could you please update the README to be less confusing for first time users.

That could probably be done. Note that the README was something of an afterthought, as the MR thread was meant to be the main way people find it (that's how it ended up with my other kobo mods, with the exception of kepubify and dictutil).

I dont' want to be jumping from the example file or the docs to forum postings on mobileread and back to the docs for such an important thing.

That's up to the @koreader people. @NiLuJe, do you think I should encourage launching it that way, or are there any potential issues with that (bugs, not seeing relevant notes about KOReader, etc)?

If you have other cool examples, put them also in the docs distributed.

Is there anything in particular you have in mind?

[NiLuJe]

I'd rather not have yet-another potentially out-of-sync place where KOReader documentation is scattered ;).

So, I stand by my earlier message: KOReader documentation should be in... KOReader documentation ;).

[m040601]

That decision was made quite carefully for multiple reasons.

Understood. All very valid and makes things clear now

....as it will be replaced when updating NM

Yes as I suspected. Important information.I would suggest then, changing:

# Place your configuration files in this folder (/mnt/onboard/.adds/nm). They
# can be named anything, and should consist of ...

to

# Do not edit this file as it will be replaced when updating NM
# Place your configuration files in this folder (/mnt/onboard/.adds/nm). They
# can be named anything, and should consist of ...

[m040601]

the MR thread was meant to be the main way people find it

And that's also how I found it.

I understand MR is the "second home" of all this (fast changing) kobo projects. And for many people,it is a place where you hang out daily.

For others it is a place you check now and then. If you have to go online, and hunt and peck through dozen of postings, just to start a piece of software, because the included documentation is missing something importan, that's cumbersome. A forum is neither a text file, nor is it incompatible with it.

I'm not going to insist. I made my point and tried to make you aware from a "end consumer" perspective. There is also this thing called being offline.

Anyway. Hope you can continue to document well your changes, on the Github releases page (or even an included CHANGELOG file ? )., everytime a new version comes out. As you have been doing since the begining

PS: Much enjoyed reading your, How to manage your dotfiles using Git | Patrick Gaskin https://pgaskin.net/posts/git-dotfiles/

One of the less cumbersome ,most straightforward, cleverly thought and well written pieces I haveseen among thousands of "how to git your dotfles" on the Internet.

[m040601]

That's up to the @koreader people.

I'm getting confused here ?! What does this all have to do with Koreader ?

I know where the Koreader docs are and how to get the exact version I want..That's one piece of the software I want to use. I dont' want bundles or Kfmon or more stuff that I dont need.

The second piece of software I want to use is called NickelMenu. It's github repo is here. I dont even need Koreader to use Nickelmenu.

You have lines in the NM "doc" helping users how spawn telnet, ftp, config the menus to o start a game, sudoku, wifi etc.

Is it too much to ask you, on your NM project, to add a line to your "doc" fle, how to start Koreader with cmd_spawn ?

[NiLuJe]

@m040601: As unlikely as it sounds, KOReader could change location/script name or whatever, and you'd end up with stale and broken documentation in a place that's not the canonical place for KOReader documentation.

(And, yeah, I insist, describing how to start KOReader belongs -- primarily -- in KOReader's documentation).

The (vast majority of the) rest of the NM documentation mentions stock, Nickel behavior.

[NiLuJe]

And, what do you know, exactly what you're asking for is... here, in the KOReader documentation.

[pgaskin]

I have made some improvements to the documentation based on your feedback.