Additional Help Resource (Not an issue!)

[Vijayanth-Reddy-K]

When I discovered that Simpletask let me use Lua programs to customise the app and refine the filtering and grouping as I wished to, I was elated. The only problem: I did know Lua.

While the Simpletask help manual has a Lua scripting page, I made the rookie mistake of assuming I could port my knowledge of other programming languages to here (assuming f.due would mean due variable/method of object f, for instance). It took quite a bit of Google searching and reading up for me to familiarize myself with Lua and understand what was happening in ST.

Additionally, features such as saved filters and the fact that you can combine lua scripts and other filtering options I only discovered when I stumbled across inputs in the issues. I use two devices, and my initial idea for having common widgets in both was to save all my Lua scripts as text files on one device, copy them onto the second device and individually recreate the widgets by using the Import from file option in the Lua script window. But then, I discovered that there is the right drawer, and instead of text files, I can have saved filters exported.

So, partly as a backup, and partly to chronicle and so better understand what I was doing, I opened a repository and created some additional "help files". These span Lua scripts I wrote (with some cool features like displaying a custom random welcome message), some tips I stumbled across buried in issues here and my understanding of Lua and how it is being used in ST.

@mpcjanssen @smichel17 I would be obliged if you could go through the files here and (a) suggest corrections if my understanding is flawed and (b) if they are useful, please feel free to incorporate/link them to the help files in the app.) ☺️

[smichel17]

I only have 3 minutes to look at this now so I quickly skimmed the files. They look really helpful!

I noticed @mpcjanssen recently added dokka as a dependency, in https://github.com/mpcjanssen/simpletask-android/commit/32503504def1821b74ac6bc98dfd4743a635ed73. Haven't discussed how he plans to use it / whether it affects documentation.

General comment: I'm torn between documenting how things are now, with all these workarounds, or just fixing them and documenting the new state.

Side note: I have a really busy semester and am not sure how much time I will have to actually code in the next 3 months.

[Vijayanth-Reddy-K]

They look really helpful!

Thank you!

General comment: I'm torn between documenting how things are now, with all these workarounds, or just fixing them and documenting the new state.

I know the feeling! It is one of the main reasons why my code is generally poorly documented. (I had to consciously add documentation while writing the Lua codes. ☺️)

[mpcjanssen]

The intention is to use Dokka to document the code internals (and to play with it). Markdown is perfect for usage documentation.

@Vijayanth-Reddy-K I will look at you files and I am not against including a tips and tricks file which would include this if you are OK with it.

[mpcjanssen]

@Vijayanth-Reddy-K I had a quick look and this does look very helpful. Would it be possible to condense this all in a single tips and hints file for inclusion?

Also (cool to know) Lua tables also have a meta table whose elements influence things like key lookup etc. For example all the Lua functions you use are looked up as elements of _G.

[smichel17]

If you want to learn lua more in depth, this was what I used. It's a pretty good resource.

[Vijayanth-Reddy-K]

@smichel17 I used a combination of the Lua Reference Manual, online reference and for understanding os.time(), the first edition of PIL (which google directs you to). My sole purpose in learning Lua was to add code in ST, and I'm satisfied for now with the final functionality I have, so no more Lua for now.. :) But I will keep this in mind for the future, thanks!

[Vijayanth-Reddy-K]

@mpcjanssen

I will look at your files and I am not against including a tips and tricks file which would include this if you are OK with it.

No issues. Just link the original page somewhere and say part of the tips and tricks (or all of them, depending on how many you include in the file you are creating) appeared first there. If you want to reword them as well, I do not mind. It doesn't have to be a word for word copy.

Would it be possible to condense this all in a single tips and hints file for inclusion?

If my replies on this forum are any indication, I do like to explain myself (a lot) and ramble. 😄 Also, being a new user to Lua, my jargon isn't really up to speed yet. And lastly, I have a busy workload over the coming few months atleast. 😞

So, I cannot help out with condensing the matter, I'm afraid. Please feel free to shorten it as you deem fit, before including it in the tips and tricks section you create. And maybe say, if the user wants a more detailed explanation, go to my page?

Also (cool to know) Lua tables also have a meta table whose elements influence things like key lookup etc. For example all the Lua functions you use are looked up as elements of _G.

Metatables were something I couldn't quite follow when I was reading up. But given they were not something I could modify, I didn't dwell on them too much either. So, I'm afraid I don't understand this statement. 😊

[smichel17]

Another general opinion: documentation is a lot like options, or code comments:

• If software needs a lot of options to be usable, maybe it just has bad defaults.
• If code needs comments to be understandable, maybe it's just bad code.
• If features need documentation to be understood, maybe they're just confusing.

Especially for an app like simpletask, 75% (or more) of the functionality should be so easy to use that it doesn't require documentation. Meaning, most users should never need to look at the documentation.

Documentation should be an enhancement, that makes it easier to understand the more powerful features (like lua scripting), not an excuse for leaving the core experience in a state of mediocrity.