carl wrote: ↑Wed Mar 08, 2023 4:51 pm
Hints are now in the release version of dcpomatic2_cli - --hints shows hints and stops if there are any. Let us know what you think!
Wow, that works PERFECTLY! I cannot tell you how much I appreciate this change---it's truly impressive how responsive you guys are! Not only were you willing to implement a feature that is going to be so valuable to my workflow, it happened within a couple of weeks. That's amazing!
I felt compelled to contribute in response to your generosity, so I am attaching a couple of proposals. No worries and no hard feelings at all if you decline to use either or both of them---I just wanted to try to give back in whatever way I could!
Watch out / heads up: Both patches make minor modifications to
src/tools/dcpomatic_cli.cc that I have tried to carefully check and I am reasonably confident will work without breaking anything. However, I have to reiterate that I do not have experience in C++ and, what's more, I do not have a development environment that I can use to test these changes. If you decide to use either patch, please triple-check my work to make sure nothing breaks!
The first patch contains one commit ("Update documentation and CLI UI with hint info") with a few ideas that I thought could make this new feature a little more accessible for users that didn't follow this thread:
- Change the description of --hints option to "analyze film for hints before encoding and abort if any are found": I was afraid that the previous text ("show hints and stop if any are given") could be ambiguous if the user wasn't familiar with what "hints" means in the context of this software (maybe it means give hints about how to use the command itself?, etc). I thought explicitly saying this option causes the command to analyze the film would really spotlight the power and functionality of the hints system in general.
- If hints are displayed, print a quick guidance message after the list of hints: I still think that it makes the most sense for the command to abort the job if hints are found, but there is a chance this behavior could be disorienting to some users. This change outputs a message to tell the user what is happening and give immediate guidance on how the user can move forward.
- Add a brief description of the hints system to the users' manual: The hints DCP-o-matic provides are, in a word, incredible. I thought it was unfortunate that this amazing functionality is only mentioned tangentially in ch. 22 of the user's manual (how to enable/disable this feature through the XML config file, not what it actually does). Honestly, I think the hints system could justify its own chapter to brag about everything it does, and I would be happy to help write that if others agree. However, this change just describes how hints fits into the workflow a GUI user would go through to encode a DCP.
My biggest motivation for adding a bit of information to the user's manual was to provide some sort of context for a user that sees the --hints option described for the CLI command and searches the documentation for "hints" to learn more.
Incidentally, I came close to updating the command options in ch. 15 in order to include the new --hints option, but then I realized that you've got a very clever setup where your doc/manual/cli.py script does that automatically. That's super neat!
The second patch is unrelated to the first, and it does make a bit of a design change. I'd completely understand if you don't want to mess with either patch, but especially so for this one.
This patch proposes outputting the hints text on STDERR instead of STDOUT. I put some rationale and explanation in the Git commit message included within the patch file, but the bottom-line motivation is selfish. The new
--hints option is incredibly helpful and I feel ashamed to ask for more, but if it used STDERR it would make it a bit easier to script around. (It's definitely possible to use it as-is, which would not have been possible before you implemented the
--hints option... that's why I fee a bit bad asking for more!)
In any case, I hope these patches are helpful and, even if they are not, thanks for putting up with my attempt to thank you in the best way I know how---giving a feeble attempt to help out.
Thanks again for all your work on this; I think your software is incredibly useful and I'm grateful for the huge effort you and everyone else have put into it!