Should [p:]message be an option?

[ndw]

I was asked earlier today about how to make debugging messages appear only when a static $debug flag is true.

This works:

<p:identity use-when="$debug" message="Hi mom"/>
<ex:my-actual-step/>

But it's a bit clumsy and if ex:my-actual-step doesn't actually read the output of p:identity, there's the possibility that the message could be output after the step runs.

This would be nicer, in many ways:

<ex:my-actual-step>
  <p:with-option name="message" use-when="$debug" select="'Hi mom'"/>
</ex:my-actual-step>

It happens that I treat message attributes as a special kind of magic option (because that was the easiest way to implement the fact that they're AVTs) so XML Calabash allows this.

I don't think this is conformant with the spec, but should it be?

[djbpitt]

At the moment the strategy @ndw describes above works with XML Calabash but not with Morgana:

morgana movies.xpl -static:debug=true
Compilation error(s):
Error XS0031 at file:///Users/djb/Dropbox/dh-course/ixml/private/movies.xpl [43/33]: Option 'message' is not declared for '{http://www.w3.org/ns/xproc}xslt'.

Fair enough, of course, if that type of option isn't currently valid, but +1 to Norm's suggestion that it would be a useful feature.

[xml-project]

As MorganaXProc is mentioned by @djbpitt:

I don't think this is conformant with the spec

No, I do not think, that is, what the specs says. "message" is not a regular option implicity defined on any step.

But it's a bit clumsy and if ex:my-actual-step doesn't actually read the output of p:identity, there's the possibility that the message could be output after the step runs.

I think we invented attribute "depends-on" for these cases.

Most of all: I would like to see XProc 3.1 finished as soon as possible, so I think this is another XProc next case.

[ndw]

Yes. I think we've overlooked something here, but it's probably too large a change to attempt to squeeze in now. The workaround, using p:identity and depends-on is awfully clunky, but it works.

[ndw]

No, actually, that doesn't help. The goal is to have a message that's only output when some static $debug flag is true. You can use depends to make sure that they run in the right order, but if you use-when the identity step out of existence when $debug is false, then your pipeline won't compile.

You'd have to have two versions of each p:identity step with the same name depending on $debug and not($debug), respectively, with and without the message.

Yuck. (I mean, it might still be too late to fix, but YUCK.)

[djbpitt]

If the identity+message step depends on the working step, instead of the reverse, and we then @use-when the identity+message step out of existence, I think (I'm not at a computer now, so I can't check) we should still compile. I think that may constrain the messages to report what we just did, and not we're about to do, which is also yuck, but perhaps less so than having two complete versions to accommodate with and without debug. I still like allowing message as an option that is internal to the working step but able to host its own @use-when, but I understand that it's properly up to implementers to decide whether that's a can't-release-without vs would-be-nice-sometime-in-the-future priority.

[xml-project]

Just a quick idea: instead of having to add an option message to any step (and spell out the prose for this): Would it make sense to have a special step dedicated to this problem. It has two options (one boolean, one string). If the boolean is true, the string is writen like [p:]message. In any case, the step behaves like p:identity.
Adding one more step is not as hard (and time consuming) like adding an option to every step.
Does this make sense?

[djbpitt]

How would the functionality of the proposed special step differ from using the current identity step with use-when for the Boolean and message for the string that the Boolean? I guess the Boolean wouldn't have to be static, but could we get that functionality now by wrapping an if test around identity+message?

[xml-project]

@djbpitt If "use-when" is false, the step if not in the graph (no connection, no p:depends). The step, I was thinking about, is in the graph, but emits the message only if the boolean is true. So the construct could be:

<p:magic emit="{$debug}" text="The message" name="magic" />
<ex:my-actual-step p:depends="magic"/>

[djbpitt]

@xml-project Aha! So with the new <p:magic> approach the p:depends will always succeed. Yes, I think this would be better than the current situation.

At the same time, if we think that allowing message as an option on many steps is the best solution, even if it is not realistic while finishing 3.1 is a higher priority, would <p:magic> just be of temporary value? If so, implementing it might mean choosing a temporary convenience that will linger confusingly after it has lost its utility. If that's an accurate way to view the situation, might it be better to skip the temporary solution, live with the currently available workarounds (like wrapping <p:identity> with @message in <p:if>), and fix it in a more durable way by adding a message option once 3.1 is done.

[xml-project]

@djbpitt I think p:magic (or what ever name we use for this step) could be a permant solution which co-exists with a future general "message" option on all steps.

[ndw]

How about:

<p:declare-step type="p:message">
  <p:input port="source" sequence="true"/>
  <p:output port="result" sequence="true"/>
  <p:option name="test" required="true" as="xs:string"/>        <!-- XSLTSelectionPattern -->
  <p:option name="select" required="true" as="xs:string"/>      <!-- XSLTSelectionPattern -->
</p:declare-step>

Using select and making it a selection pattern seems to quietly side-step the fact that you'd really like the option to be named message. If test is true, the string value of the select expression is output, otherwise it isn't. In either case, the step acts like the identity step.

It occurs to me that one nice feature of this approach is that if the test expression is statically known to be false, the processor could omit the step entirely, meaning it has zero cost "in production". (Not that the cost of an identity step is significant.)

[djbpitt]

@ndw With apologies for what I realize are surely naive questions:

1. How does XSLTSelectionPattern in the test option behave differently than a typical Boolean test expression, and how does it, in the select option, behave differently than a typical @message string?
2. How does the <p:message> step, as constructed, send a result to stderr, rather than stdout?

[ndw]

The XSLTSelectionPattern annotation is just an indication that it's an attribute that contains an XPath expression.

I was speaking informally about it. I think the step description would have to say something like "if the effective boolean value of the test expression is true then..."

The @message string is an attribute value template, where this select attribute is explicitly an expression:

message="3+4" prints "3+4"
select="3+4" prints "7"
message="{3+4}" prints "7"
select="{3+4}" is a syntax error.

I don't think XProc says anything explicitly about stderr and stdout. We say something weasely like "make available" because what does stderr or stdout mean if it's running in a browser, for example?

It hadn't occurred to me that p:message messages should go anywhere different from ordinary @message messages...

[xml-project]

@ndw Two minor question for the implementation:

1. as port "source" must be a sequence port. If one document appears on source, this is the context item for test and select, right? I guess the context item is undefined in the other cases.
   2. I am not sure XSLTSelectionPattern is right, why not XPathExpression. I am not sure we are matching nodes here, but select from a tree. What did I miss? Sorry, I was confused.