Possible to get hints via command line?

[carl]

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!

[ancient-skyscraper]

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!

Thank you! I'll try to check it out tonight.

[ancient-skyscraper]

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!

[carl]

Hello,

Thank you for your very carefully-considered changes! I applied them both to the `main` branch, with just a couple of small adjustments, mostly because of my near-pathological hatred of the word "issue" (in the sense of "problem")

I also updated the manual on the website with the changes.

Thanks again!
Carl

[ancient-skyscraper]

I'm very glad the changes were helpful! I am really happy to be able to give back (even in a very minor way) to the amazing project you're doing.

I think the hints framework is an incredible asset to DCP-o-matic, and I'd love to help document it more if that would be helpful. Perhaps it could be another chapter near the end of the manual; the short blurb we added in Section 3.3 could be updated with a link to the new chapter for details.

If you think it would be worthwhile, I think I would start by trying to round up a list of every hints test that is run (by looking through src/lib/hints.cc) and then write a bare-minimum bit of documentation for each one (likely just summarizing or repeating the string that is output to the user). Eventually, I would love to try to understand each check and write up something about what condition(s) would trigger that particular hint, what the thresholds are, etc. This in-depth coverage might require a bit more expertise than I have, but I would be willing to give it a shot it you think it would be helpful.

my near-pathological hatred of the word "issue" (in the sense of "problem")

If you're willing to share, I'd love to hear your thoughts on why "issue" gets under your skin. I bet I could learn something that would improve the precision/sensitivity of my writing!

Cheers, and thanks again!

[carl]

If you think it would be worthwhile, I think I would start by trying to round up a list of every hints test that is run (by looking through src/lib/hints.cc) and then write a bare-minimum bit of documentation for each one (likely just summarizing or repeating the string that is output to the user). Eventually, I would love to try to understand each check and write up something about what condition(s) would trigger that particular hint, what the thresholds are, etc. This in-depth coverage might require a bit more expertise than I have, but I would be willing to give it a shot it you think it would be helpful.

That sounds great. I have no evidence to suggest how many people read the manual, but I am very happy to have it improved!

If you're willing to share, I'd love to hear your thoughts on why "issue" gets under your skin. I bet I could learn something that would improve the precision/sensitivity of my writing!

I don't think this is a widespread view, just a pet peeve! I just hate the euphemism I think, and prefer direct language where possible. However as the entire software industry now appears to use "issue" for everything I think I already lost the battle!

[ancient-skyscraper]

Fair enough---I'll try to work on that when I get some free time. I won't make it the highest priority, but I'll try to get something worked up!

I just hate the euphemism I think, and prefer direct language where possible

That makes sense!