I have a script in /etc/profile.d to display a custom message upon terminal signin.
The hestia cron job: v-update-user-stats seems to trigger this script and thus sends me an email. I tried to silence that email with the cli but here are the results:
There are a lot of errors/missing details from the cli documentation. I have a running list. I really appreciate hestia and all the work that goes into it and I am committed to using hestia, but the documentation issues have resulted in a lot of wasted hours for me. I almost always have to look at the code to get the expected syntax and/or how the cli command is going to function, which defeats the purpose of documentation.
I wonder if there is something COLLECTIVE we heavy cli users could do about that i.e. NOT just me making 50+ pull requests every time I find something missing in those docs.
Missing quoted example that might catch other folks off guard about the non-quoted * expansion.
Does the [COMMAND] string need to be quoted if there is a space for it to work? And does quoting the [COMMAND] string mess up the input like it did in my above example or only when a * is present?
There is a sentence that makes no sense: When executing commands, any output is mailed to user's email if parameter REPORTS is set to 'yes'. There is no “REPORTS” parameter mentioned in the usage. Or maybe that’s in the GUI somewhere? And I would need to look at the code to see that means.
And no indication of the default behavior of [RESTART] if omitted or if it restarts the cron daemon or hestia daemon. which may be obvious to the maintainers of hestia or expert sysadmin. But I wouldn’t know for sure without looking at the code.
That is four errors/omissions for one CLI command. Which could have been fixed in a shorter amount of time than it took me to write this.
And again there are dozens or hundreds of these things likely waste a lot of hours of people’s time that could be fixed very easily.
Can we do that COLLECTIVELY come up with a way to fix this doc?
If you type things in command line you need to be aware expansion of strings. Adding in all command ’ around each variable makes the documentation harder to read. And if you use it with php you probally want to use it with something like GitHub - hestiacp/phpquoteshellarg: php quote shell arguments so it is covered exactly.
Restart behaviour by default is “Reload” unless it is not supported then it is “Restart” In case you edit the cron it will restart the cron part…
I don’t see the need to add every where single quotes in each example. Because it might be needed… We should assume users at least know basics in bash. But if you use special chars like ", ', *, $ thing can happen that you don’t except.
If you use it in a programming language you should always use escaping method to prevent hackers doing thing you don’t except…
My point is about DOCUMENTATION, not the specific answers to the errors/omissions in this CLI command.
You took the time to answer the questions about the errors/omissions but I assume did not update the documentation. Which leaves this as an issue for others in the future. Which is the point of what I’m saying. I’d say 25-50% of the issues posted on this forum could be mitigated with documentation updates. The time is spent replying to issues but not updating the documentation which is not efficient, doesn’t solve the problem for users that encounter this down the road and wastes everyone’s time.
And we differ in opinion about 1 + 2. I am relatively new to bash but not programing languages. I (and many others) learn the syntax through using it. I hadn’t connected the dots about * expansion in the command line because I hadn’t used it in that way before. And generally find the differing expansion/syntax/special character/formatting rules for every language a challenging thing especially when writing and using multiple languages/markups. Adding an ADDITIONAL quoted example to TWO cli references it not going to hurt anything, but rather help users like me who are not-yet-experts like you. I understand the idea of hestia is for more advanced users. I’m onboard, but LET’S MAKE THE DOCUMENTATION BETTER for everyone and help save people’s precious time!
Should be added to the docs. No one is going to know that from that one sentence in the docs and it will waste their time when they try to find it.
Should be added to the docs. (And added documentation of the default behavior of dozens of CLI commands.) No one should have to look in the code to find this basic info out. Any good documentation is going to state default behavior of optional arguments and the clear requirements/syntax for all arguments .
You seem to be THE gatekeeper of this project. I want to contribute, not fork. So again:
How can we satisfy your specific documentation needs and give the info needed to the rest of us who don’t know every detail about hestia so we can SAVE TIME? And how can we improve the docs EFFICIENTLY and COLLECTIVELY?
I know this info and have already contributed once via pull request.
I can’t do this on my own as there are 486 cli commands and I don’t know the answers to missing documentation without digging in the code, which would take me days and days. But you (and maybe others) immediately know the answer without looking.
Maybe we could:
Set up a real-time collaborative sessions with 2 or more people.
Fix the command documentation headers in batches.
Track progress in realtime with a google sheet. (I already created it.)
Leave a live video/screen sharing feed and text chat running.
Everyone edit directly on github with a new branch. You could accept commits in realtime.
Knock it out quickly in a couple sessions.
Maybe @sahsanu would contribute? Or whoever else you think?
Could even be fun…?
The time would pay for itself. Both in your issue responses AND definitely wasted user time.