Proposal: add print hints

[MartijnR]

For data collection clients that support printing of forms or records, an often-requested feature is to add some instructions or information that should only show up on print-outs.

Example use cases:

• print an empty form and display additional instructions for the interviewer to take with her in the field or use during training
• describe skip logic in a human-readable way to use when collecting data by pen and paper.

This proposal is facilitate this by adding a form="print" to <hint> values, just as done for media (and in line with an existing obscure documented feature of form="long" and form="short" for labels and hints).

<itext>
    <translation lang="default">
        <text id="/data/a:hint">
            <value>a normal hint</value>
            <value form="guidance">a print hint</value><!-- the new feature -->
        </text>
    </translation>
</itext>

I believe ODK Collect currently ignores any unknown "form" attribute values (as it should). Test form:
Print_Hint_Test_2.xml.txt

[lognaturel]

This seems unambiguously useful and is idiomatic as far as I understand it. We haven't formalized our spec committee yet but I think it would be good to get in the habit of getting at least three voices involved. @alxndrsn @dorey

I never stopped to consider the implications of long and short. Those are super useful.

[dorey]

Would print hints be translatable in the same ways that label and hint are?

[MartijnR]

Yes, they would, in the same way as labels, hints etc.

[dorey]

Sorry, yeah i saw the <itext> and understood the original issue right after I posted that...

[lognaturel]

@dorey, does that mean you're in favor? 😊

[dorey]

Yes! Sorry , I am 👍 for this approach

[MartijnR]

Thanks @dorey @lognaturel

If others don't offer objections/changes, I'll prepare a PR in the next few days and will open an issue on Pyxform when merged.

[alxndrsn]

Look like I'm a bit late on this one, but at first glance the form attribute seems ambiguous in a standard designed to define forms. Would it be clearer to use media like HTML and CSS do?

[lognaturel]

Although I agree with you, I think the attribute name shouldn't really be part of this conversation since it's been part of the specification for a long time for the long and short forms. Something like variant probably would have been better but I think deprecating form would cause a lot of problems without much upside.

In the mean time, I derailed us at XLSForm/pyxform#142 when I realized that this variant might have value beyond just showing up on a printed piece of paper. I don't really know where we should go from there, process-wise. I think we let the conversation run its course there and summarize here? Should we perhaps revert the commit that added print and reopen the issue?

[MartijnR]

Yes, form is unfortunate, but agree not enough benefit to change at this stage.

Let's see what comes out of pyxform. I can revert the commit in the mean time until we know the new form value.

[MartijnR]

Note for future commit: the reversal also reverted some other existing form attribute documentation improvements, so those should be re-reverted probably.

[MartijnR]

I think we can finalize this here, and then subsequently provide the spec to pyxform (for the xlsform transformation output of <!--more-->).

Shall we go for a neutral form="guidance"? It is tempting to use the form="long" (which already exists in our spec), but since the description of that feature does not quite match what we want to use this new feature for, we probably shouldn't.

As a proposed description:

The guidance version is only supported on hints and is meant to provide additional context or guidance for a question. This could be used e.g. during trainings or handouts to data collectors but it not shown by default on the client application during data collection.

[getodk-bot]

Hello @MartijnR, you claimed this issue to work on it, but this issue and any referenced pull requests haven't been updated for 7 days. Are you still working on this issue?

If so, please update this issue by leaving a comment on this issue to let me know that you're still working on it. Otherwise, I'll automatically remove you from this issue in 3 days.

If you've decided to work on something else, simply comment @opendatakit-bot unclaim so that someone else can claim it and continue from where you left off.

Thank you for your valuable contributions to Open Data Kit!

[lognaturel]

guidance works for me and there was significant agreement on the XLSForm side for using guidance here so let's make it so. Thank you @opendatakit-bot for bringing this back to top-of-mind.

[MartijnR]

Continuing here from the pyxform PR. The reason I got confused, and still am, is that when itext is used a single <hint> with different "forms" (attributes) makes sense, and I thinks corresponds to e.g. the big-image feature.

However, in this particular case if we want to show the guidance hint, we probably also want to show the regular hint (so one doesn't replace the other).

[lognaturel]

Yeah, that's also what threw me off. But I think it's up to clients to pick the variant they want for different parts of their UI. So for one part they'd grab the hint with no form if it exists and for another they'd grab the hint with guidance form if it exists.

[MartijnR]

Alright, and they can also decide to grab both. Yes, let's do it like that. Thanks!

[lognaturel]

Sorry I totally confused things with my wacky implementation!

[MartijnR]

No worries at all. We have a wacky form format! 👍