Parameters for 'auto-label-app', etc.?

[MenteaXML]

It's not clear to me why 'auto-label-app', etc., are variables rather than parameters.

In principle, if they were parameters, it would be possible to add autonumbering in the formatted output of 'Orange' content, where <label> isn't allowed, by setting the parameters when invoking the XSLT processor.

[wendellpiez]

I think the idea here was that overrides would take the form of importing stylesheets rather than stylesheet parameters providing a run-time interface.

If these are to be stylesheet parameters, are we confident that Boolean values are okay? (1) not all environments support passing Boolean values to the processor, and (2) they are going to be somewhat more obscure and potentially problematic (or aren't they?) for beginners debugging.

For example, passing in the string "false()" will get you true() etc.

If these were exposed, maybe they should be strings, or (better?) layered with string-value parameters:

<xsl:param name="provide-app-labels" as="xs:string" select="'no'"/>

<xsl:variable name="auto-label-app" select="$provide-app-labels=('yes','true')"/>

These could be either in the main XSLT, or in a shell stylesheet for Orange.

[Klortho]

But, do you lose anything by simply changing variables to parameters? The default behavior would still be exactly the same, wouldn't it? And for those processors/environments that do support boolean params, you've added some flexibility.

[wendellpiez]

It's not the default behavior I'm concerned with. I am suggesting doing more, not less. Why do more? Because I have sympathy for the poor XSLT developer who struggles with this for three hours only to discover that her supposed Boolean values are being passed as strings (so that 'no', 'false' and 'false()' are all interpreted as true() etc.), and no exception is thrown. And because it's not much more.

I see my suggestion above uses XSLT 2.0, and this is (still) a 1.0 stylesheet. So my code would have to be:

<xsl:param name="provide-app-labels" select="'no'"/>

<xsl:variable name="auto-label-app"
  select="($provide-app-labels='yes') or ($provide-app-labels='true')"/>

In 2.0 we have other options, including declaring $auto-label-app (and the others) as a Boolean parameter. But this leaves the functionality unavailable to those using processors that can only pass strings in.

(FWIW, BaseX calling Saxon9 is still one of those processors. We're not talking only about underpowered old stuff.)

[MenteaXML]

What's useful to do probably comes down to a balancing act between "a point of entry for JATS users who may not have the resources to create them from scratch" and "you should have no expectation that these stylesheets will create production ready files in any arbitrary system."

If "users who may not have the resources to create them from scratch" extends to users who don't grok XSLT at all, then the maintainers may want to make the stylesheets do reasonable things for the different flavours of JATS 'out of the box'. This current parameter-related issue was posted partly to soften people up to the next idea of a parameter for specifying the JATS type that would do (one interpretation of) the right thing with the other parameters, but Wendell's idea of a shell stylesheet for Orange would work (though you'd need two, or rather six or maybe eight shell stylesheets: one for each output type for each JATS flavour (and maybe two for BITS, too)).

If it's just that the current xsl:variable become xsl:param, as long as you document that the parameters turn things 'on' with any string value other than an empty string, then you don't need to fret overly about people getting confused, IMO.

It would also be possible to make a 'auto-label' parameter that took comma-separated values of the form 'fig,table-wrap,sec', etc., that would turn numbering on for tokens matching known strings (much easier to do in XSLT 2.0, but if done in XSLT 1.0 you'd still only need to write the code the once). It all depends on what the maintainers see as the balance between "point of entry" and "you should have no expectations".

[Klortho]

Just to clarify: I'm not against your suggestion, Wendell, I'm just worried that it's a bit more work and so less likely to actually get done, whereas s/variable/param/ is pretty easy.

[wendellpiez]

Yes, agreed on almost everything. I wish I agreed that documenting a behavior would be sufficient to ensure users knew about it. Unfortunately I think the documentation is more useful as a pre-emptive response to requests for help than it is as an information channel as such. (Being able to say RTFM is always good even if one never does.)

Nonetheless one could also put comments in the code, which are perhaps less likely to go unnoticed by desperate hackers.

Tony, what would you think of a single shell XSLT that exposed parameters for all the various mixed-and-matched hybrids you foresee? (Or two XSLTs, one for each output type.) Documentation of how to use it (including the trap of string values other than '' being Boolean true()) could be included as comments. In a separate module, all this would be easier to see and use than it would in the main XSLT.

If the maintainers were to decide that this isn't worth it ... wire the interfaces into the main XSLT and be done ... I suggest that the "'false' is true()" potential bug is called out not just in formal docs, but in comments in the code where desparate hackers might actually have a chance to see them.

As for work (Chris :-), it's really a matter of guessing what minimal work can be done here to save people (including but not limited to ourselves) work in the future (including work sorting out complexity and facing down confusion).