Of course, I’m aware of that section as that’s the one I’m questioning!
OK, so it’s not so much that Blockly must have the user mount their configuration folder, it’s more that there are certain openHAB blocks which rely on a specific configuration file within those folders, so it’s best if the user knows how to access them.
This feels like there should be a separate openHAB documentation page on how to access the configuration files, but I can’t immediately find one. Seems slightly clunky in this documentation!
Edit: either way I’ve cleaned up the start of that section to show the definitive method of finding the location of the configuration folder. I still think all the rest below that shouldn’t appear in this documentation but I’ve left it for now.
I’ve removed a couple of very specific sentences/bullets around configurations specific to openhabian (frontail), as I think this documentation should remain agnostic to installation method. I have moved the link to logging down into the relevant section within the blocks.
The file locations is documented in the installation instructions. That would probably be where such would go since that’s the only place in the docs that are really operating system specific. And all this would be OS specific. I don’t know that there is anything about accessing those folders though except in openHABian.
Please do not remove that, I intentionally added this information because of many people requiring that information. Do not expect everyone to be as experienced as you. Especially people who use blocklies aren’t usually and I don’t want to pinpoint to the spread out documentation of openhab. I have linked as much as I could whenever I found the appropriate documentation somewhere in the docs. Also this is exactly the part that I have already moved to the openhab docs and that already took me several hours on Sunday. It is much more than just copy and paste and I am doing this in my minimum leisure time. You offered to check my English writing and as you seem to be a native speaker I am happy if you do that. If you though do a whole review on the text, rewrite or even change the content and I have to review everything in terms of the content and we have to discuss this first before I can continue, then I probably have to say that someone else has to take over the process of moving it to openhab docs as I won’t be able to do that any time soon. If someone is volunteering to take over. I am completely open for that.
It sounds that I am not willing to have the text reviewed but this is not what I am saying. It is just if we want to go that way I won’t have the time to then move it to openhab docs as well.
It’s a wiki, feel free to roll back. I don’t think I removed any information, just re-wrote it (other than the specific openhabian parts as mentioned).
You said you’d moved the Introduction section, so I didn’t touch the Introduction section.
The description of how to do that in these docs of openhabian is pretty sparse and and technical which is why I added a more detailed way in the setup section. I don’t feel it is redundant but rather helpful in the introduction as finally people who want to use the sounds or other blocks need to find the conf folder easily. I wanted the docs as helpful as possible.
Sorry, maybe I should have been more specific, @hafniumzinc. My bad. I meant I moved everything until items & things which I lazily called “introduction” above.
Bravo gents, have at it T
Stefan, if you run short of time to push the documentation PR thru, I’ll work with Jerome and get it done. Please link your documentation fork so I can find it
Are you done with your edits? I have 3 edits from you and Andrew by now all of which I need to review individually for the whole text. There is nothing like git that only shows me the individual changes. Unfortunately there is no way to compare the current version to my last version and also the side by side comparison doesn’t work well as the old and new text is not perfectly lining up.
So can you please keep the number of edit sessions to a minimum? thanks.
You don’t have to because I am already have long conversations with Jerome in the background but his time currently is very limited. The PR is not the main work. Editing the text to become compatible with the openhab docs markdown, styling it nicely and cutting it down into several pages, polishing and uploading the images and finally checking if renders nicely is the main work which takes a lot of time.
I don’t want to make this more stressful than it needs to be. If you’re serious about comparing all the differences - rather than reviewing the current version as it is merged into the openHAB documentation - then you could be spending quite some time, and I don’t think that is worth it.
In that case I would just roll back to a version that you know you’re happy with, and merge that. I’ve saved a copy of my edits and can submit them as a PR (or multiple PRs) once the openHAB documentation is online.
But the problem is the docs here assume OH is running on Linux and the folders are shared to Mac. What about all the other many many different ways to deploy OH? By the time we cover them all that one section is going to become longer than the reference itself. If you don’t cover them all, then you’ve privileged one way to deploy OH over all others and left someone who, for example deploys OH using Docker on a Mac and uses Windows as a client completely out in the cold.
That’s one of the reasons why the OH docs are, by necessity, spread out the way they are. There really isn’t a good answer for that that I can think of.
So either that section needs to be beefed up to cover more cases (eventually, I’d say it can stay as is for the first draft submitted to the docs) or it needs to reference the parts of the docs that cover that information. If the current versions of those docs are not sufficient, perhaps they need to be updated there.
The OH docs have a policy of DRY: Do not Repeat Yourself. It’s not that we don’t think that having each page be comprehensive and self contained, it’s that we do not have the manpower to keep them up to date even when each topic is only covered once. Having something covered multiple times on multiple pages only means the docs take more effort to keep up to date and runs the real significant risk of becoming out out of date as changes are made in one place but not the other.
Don’t back out what you’ve done for now, but start thinking about how to cover it in the future because it either needs to cover the most common cases and become much more comprehensive, or we need to link to and rely upon the docs that are specific to how OH is installed.
I’m wondering if it needs to be in the Actions section with reference to the “File Locations” tables for the individual OS installation instructions. It’s not just Blockly that needs this information. Calling these Actions in any rules language needs to know where to put the sound files.
I try to beef that up and add more cases as much as I know (and yes I tried DRY as much as possible to always link to sources I know)
I agree that it would make sense to move that upwards to some place where it would explain that for all rule types and then link to that anchor. I would recommend I publish the content and we later refactor it to become part of a page that is more general to all rules.
Exactly, this is the documentation for blockly, keep it blockly centric, leave the beginners tutorials, file locations and installation to those sections
In OH2 I was using Jython to create rules. I was familiar with python, and excited by the prospect of pip-installing any library I wanted to help simplify rules and fill in gaps in bindings (there’s a high chance someone has written an API wrapper in python for even the most obscure thing!). The reality was, as oft-repeated in this forum, that Jython is stuck on python 2.7 which is just too old, and I was becoming increasingly frustrated with incompatibilities with newer python libraries.
Five minutes ago I completed the move away from Jython. Admittedly, I only have a small number of rules, though I like to think that that’s as a result of clever consolidation and ruthless culling, rather than my lack of skill. Even though it’s definitely the latter. Anyway, all but 1 of those rules now uses Blockly for the action part. Thank you to everyone in this thread for making that possible - great work guys!
(The 1 that couldn’t go into Blockly requires manipulation and calculations of values from a JSON string. It might perhaps work with the new discrete code block, but I’m OK with this one living as code for now)
You could split the difference and do most of it in Blockly and use the Inline Script block to do the JSON parsing. Underneath the block it turns into ECMAScript 5.1 so you could parse out the JSON and add them to variables for use later in the rule. You’d probably want to create the variable using blocks though so that the rest of Blockly can see it. The JS in JSON stands for JavaScript so the code would be pretty simple I’m sure.
Building rules with Blockly is kind of fun! It has a lot to recommend it and I’m really glad we have these new blocks. Now back to work (I hope to get back to the Getting Started Tutorial with a new example soon).
Thanks to @stefan.hoehn for the main work and also thanks to the contributors here.
We have currently added a complete set of articles for the blockly reference to the documentation and it will be available soon with one of our next website builds.
We should now close the wiki post here, to prevent different doc versions in several places.
We have decreased the entry hurdle for contributing to the docs in several points in the pas months, so it should be suitable to provide additional changes to the docs directly now.
do not remove that, I intentionally added this information because of many people requiring that information. Do not expect everyone to be as experienced as you. Especially people who use blocklies aren’t usually and I don’t want to pinpoint to the spread out documentation of openhab. I have linked as much as I could whenever I found the appropriate documentation somewhere in the docs. Also this is exactly the part that I have already moved to the openhab docs and that already took me several hours on Sunday. It is much more than just copy and paste and I am doing this in my minimum leisure time. You offered to check my English writing and as you seem to be a native speaker I am happy if you do that. If you though do a whole review on the text, rewrite or even change the content and I have to review everything in terms of the content and we have to discuss this first before I can continue, then I probably have to say that someone else has to take over the process of moving it to openhab docs as I won’t be able to do that any time soon. If someone is volunteering to take over. I am completely open for that.