Consider to add documentation hints inside RNC #3
Comments
|
This is an excellent idea (but I suggest a different implementation)
You are asking for standard strings to describe what the meaning of each
schematron element or attribute is.
*New Pattern:*
It could be done by adding fixed attribute values to a DTD or XML Schema or
RELAX NG, rather than comments.
However, there is a simpler way that already fits in with current tool
libraries: just do it using Schematron!
<sch:pattern id="documentation" role="documentation" ... >
...
<sch:rule ***@***.***" role="documentation" >
<sch:assert test="true()">An "id" attribute identifies the unique ID
value of the element</sh:assert>
</sch:rule>
This is the kind of thing that I would like to see on the planned "open
standard" Schematron site, actually. (Then it is available,
and SC34 can decide whether to also adopt it or not.) To read about that,
see
*https://schematron.com/2021/08/plan-for-alternative-open-standard-text-for-schematron/
<https://schematron.com/2021/08/plan-for-alternative-open-standard-text-for-schematron/>*
and
*https://schematron.com/2021/08/procurement-implications-of-an-open-standard-for-schematron/
<https://schematron.com/2021/08/procurement-implications-of-an-open-standard-for-schematron/>*
If it used a Schematron pattern, it could get decorated with richer text:
such as @Seealso @ICON by
vendors too.
<sch:pattern id="documentation" role="documentation" ... lang="en" >
...
<sch:rule ***@***.***" role="INFO documentation" seealso="
http://www.schematron.com/whatever.../attribute/id" >
<sch:assert test="true()" >An "id" attribute identifies the unique ID
value of the element</sh:assert>
<sch:assert test="true()" role="INFO details>The id should not start
with a letter ideograph, and may also contain digits or -_.
characters.</sh:assert>
</sch:rule>
If anyone is interested in devising a suitable list of these one-liners,
please go ahead and let me know, and they can be the basis
of a pattern. Or even to identify what it is about various element names
that people don't find relatively intuiative.
(Dave Pawson has kindly offered his Schematron FAQ as a general basis too
for paragraphs, and I have many descriptions too, so
I expect we can cobble something together.)
I *may* outside the general ISO requirements that they do not express
application things. So it might be a thing that could be
put into a non-normative annex, for example. Or as additional rules on the
standard's own Schematron schema.
What would be good is if it contains enough hooks to be compiled into
resource files. And that it allowed multilingual versions,
of course.
*Retrofittig existing schema pattern*
In fact, a well-written assertion in the existing Schematron schema for
Schematron should already be useable to give information about an element.
Currently, they only have assertions about things that are not in the
DTD/RELAX NG. But, for example, you could have in the general
patterns:
<sch:rule ***@***.***" >
<sch:assert test="true()" role="WARN">The id should not start with a
letter ideograph, and may also contain digits or -_. characters.</sh:assert>
</sch:rule>
and extend this to also be treatable as something to be compiled into a
properties resource or whatever.
<sch:rule ***@***.***" >
<sch:assert test="true()" role="WARN documentation">The ***@***.***
should not start with a letter ideograph, and may also contain digits or
-_. characters.</sh:assert>
</sch:rule>
I think the first approach of a seperate pattern, however, is cleaner, and
might allow better targetting for a particular use case.
Cheers
Rick
…On Mon, Aug 16, 2021 at 5:41 PM Tom Schraitle ***@***.***> wrote:
Problem
The current RNC schema of Schematron does not contain any documentation
related strings. It is not clear from looking at the schema what these
elements and attributes really mean. You *have* to read the specification.
Suggested solution
It is quite easy to document elements and attribute. For example, this is
an original snippet:
attribute id { xsd:ID }?,
to add documentation, use this:
## Identifies the unique ID value of the element
attribute id { xsd:ID }?,
To make this fly, I'd recommend:
- Make the documentation string short and sweet. There is no need to
add lengthy paragraphs.
- Provide links to the Schematron specification for further details.
- Create patterns when attributes are needed for more elements. That
simplifies and improves reuse. There is no need to repeat yourself.
Benefits
IMHO, adding documentation inside the Schematron schema has these benefits:
- Gives guiding aids. Some XML editors can show this as a popup when
trying to add a new element or attribute.
- Help beginners to get accustomed to Schematron schema. This works
quite good in combination with the first item.
- Reduces time spent to find out about the meaning of an
element/attribute. Sometimes it's enough to let your XML editor show the
help without looking for the specification.
- Allows to link it to the Schematron specification, if wanted.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#3>, or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AF65KKOXNJQKTJNN72QO3NDT5C6KTANCNFSM5CHFUOFA>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
|
It seems to me (though I can't tell for sure) that the schemas were intended to be read as part of the text of the standard, and this may be why they lack internal documentation. I think the right place for the documentation is actually the schemas, as @tomschr suggests, particularly since they are available under a separate licence. I see two issues with documenting them externally elsewhere by other means:
|
|
The Schematron should eat its own dog food, yes, but it should also use existing standard (and implemented) mechanisms where they exist. On a more mundane level, the https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/validate-xml-with-sch.html |
|
It turns out that Oxygen shows tooltips from annotations embedded in its |
|
Tony wrote:
Unless and until you can get editors to recognise role="INFO
documentation" as something special, the Schematron mechanism will result
in an explosion of error messages, blue squiggly lines, and blue margin
markers, or similar
Sure, and I certainly appreciate that Schematron is sometimes used in
progressive validation, after the grammar.
But why take a passive approach? Tom is making a specific request, sure;
but it is also something that shows up a limitation/opportunity in
Schematron, and it can be treated as useful feedback on gaps and
requirements.
The issue of what gets the job done for him today is useful; but the issue
of what underlies his request is more important for a standard, isn't it?
There is no need for providing one to exlude the other: augmenting the
RELAX NG but leaving the gap in Schematron is a wasted opportunity.
We could ask Oxygen (or PageSeeder), as primary users of such a convention
(as implementers), what solution they would find that would fit best, and
see what fitted in with their system best. The choices would be to make
some conventions on existing schematron elements, or to use some foreign
element, or to extend Schematron.
*Using Roles*
For example, would ***@***.******@***.***="tooltip"] be
easier for them to work with, completely avoiding any asserts or reports,
and perhaps tying in with QuickFix?
The Schematron schema (or the ***@***.***="tooltips" only) could be
compiled into suitable tables for fitting into a user interface better.
<sch:pattern id="interactive-tips" role="tooltips" lang="en">
<sch:rule context="street">
<p role="tooltip">Street is the street name, without St.,
Street, Ave., Avenue, Rd. etc. </p>
</sch:rule>
...
</sch:pattern>
Or is this a different kind of assertion role?
<sch:pattern ... >
<sch:rule context="address">
<assert test="street" role="tooltip-explain">Street is the
street name, without St., Street, Ave., Avenue, Rd. etc. </assert>
</sch:rule>
...
</sch:pattern>
Or a ***@***.***?
*Adding Allow *
Or is this in fact something that says that the assert/report dichotomy is
too weak? Does Schematron need to be able to express
patterns that are not mandatory, without it having validity impact? For
example, to say that
<sch:pattern ... >
<sch:rule context="address">
<*new:allow* test="street" role="tooltip-explain">Street is the
street name, without St., Street, Ave., Avenue, Rd. etc. </new:allow>
</sch:rule>
<sch:rule context="address/num">
<*new:allow* test="not(following-sibling::street)"
role="tooltip-next">Street is the street name, without St., Street, Ave.,
Avenue, Rd. etc. </new:allow>
</sch:rule>
...
</sch:pattern>
This is a pretty clunky approach, if generated by hand. But it opens up
the door for Schematron to break through into a different class of uses:
probabilistic schemas.
*Probabilistic Schemas*
The idea would just be to allow a probability attribute, so 0-100. The
probability could be used to re-order menu choice, or
to allow fuzzy patterns, or to guide users about markup outliers,
So probability of 100 is the same as a current assertion:
<sch:rule context="address">
<*assert* test="street" new:probability="100"
role="warn">Address must have a street </assert>
</sch:rule>
And a probability of 0 would be transformed into a report or have its
xpath negated
<sch:rule context="address">
<*assert* test="street" new:probability="0" role="warn" >Address
must not have a street</assert>
</sch:rule>
And a probability of 75 is an allowance
<sch:rule context="address">
<*assert* test="street" probability="75" role="info-tooltip"
Address usually has a street</assert>
</sch:rule>
And a probability of 5 can be e.g., an outlier
<sch:rule context="address">
<*assert* test="street" new:probability="5" role="info-tooltip"
Address rarely has a street</assert>
</sch:rule>
Or a sign of obsolescence/best practice
<sch:rule context="address">
<*assert* test="street" new:probability="50"
role="info-are-you-sure" >We don't use the Street element in new
documents</assert>
</sch:rule>
An implementation would decide whether to fail on new:probability or to
handle it in whatever way made sense.
The SVRL would report the probability attribute, or filter out ones that
are not useful.
Cheers
Rick
…On Mon, Aug 16, 2021 at 8:57 PM Tony Graham ***@***.***> wrote:
The ## comments the are the RNC shorthand for RELAX-NG documentation
elements. See clauses C.5.3 of ISO/IEC 19757-2:2008. As @tomschr
<https://github.com/tomschr> points out, some editors (notably Oxygen)
already use this standard mechanism to pop-up tooltips containing the
nearest ## comment (and I use this with schemas in multiple Oxygen
frameworks).
Schematron should eat its own dog food, yes, but it should also use
existing standard (and implemented) mechanisms where they exist. On a more
mundane level, the ## comments are presented as tooltips when something
is being inserted or when the mouse is over an element or attribute. Unless
and until you can get editors to recognise role="INFO documentation" as
something special, the Schematron mechanism will result in an explosion of
error messages, blue squiggly lines, and blue margin markers, or similar:
https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/validate-xml-with-sch.html
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#3 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AF65KKM2VODIECW7GHLOSSDT5DVIDANCNFSM5CHFUOFA>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
Even if the Schematron is the only schema and the document is revalidated as you type, current behaviour for Schematron messages is going to present every INFO message anywhere in the document.
@tomschr can work out which approach works best in their case, but why reinvent the wheel? Why see everything through the prism of Schematron? Why invent Fuzzy Schematron in response to a question about doc comments in Relax-NG? Instead of putting comments in an existing file and using an existing convention that shows them to the user, you want to split the comments into a (probably) completely different file and rely on machinery that doesn't yet exist?
IMO, what's important for a standard is that it codify useful and interoperable things. There's many and varied ways for something to get to the point of being shown to be useful and interoperable, of course, but I would resist calling something a standard if neither of those were true. I've been in a slow-moving exchange on xml-dev about the usefulness or otherwise of SGML's LPDs. There was a brief moment when I was reading about them before I used them when I thought they were useful and interoperable, but neither turned out to be true IMO. Being in the standard didn't make it so.
Except that you previously side-stepped anything to do with the RNC. |
That proposes "an alternative description of exactly the same technology as ISO Schematron describes". It's not obvious how 'new pattern' and 'exactly the same technology' are meant to fit together. |
|
Tony wrote:
Even if the Schematron is the only schema and the document is revalidated
as you type, current behaviour for Schematron messages is going to present
every INFO message anywhere in the document.
Why? You configure the application to know which phase (or patterns, or
roles) should be dealt with by a processor that picks what to validate. If
it is put into a phase, in particular, validation of that schema by an
existing validator would not have any effect. And if you use the <assert
test="true()"...> form, the assertion would never fail as part of
validation.
Why see everything through the prism of Schematron? Why invent Fuzzy
Schematron
Aren't I allowed to? ;-)
But three other things come to mind:
- first, that a standard that does not evolve risks dying;
- second, that innovation only happens when people know innovation is
welcome and useful; we all so easily get a category problem that while a
Standard productizes previous innovation, we think this means it must
stifle current and future innovation: now, sure, the advent of a standard
allows a growth of consumers, but a standard can help us think more
concretely about innovations, not prevent them; so I would love to see
more people come up with more ideas, implement them, work out compromises,
and for these to feed into future versions. (For that, maybe people need
know that exploration is not against the rules of the game, it *IS* the
game, and to have some possible directions?)
- third, no standards-making group, when presented with an issue and a
solution, does not look beyond the concrete to the conceptual, to see if
there is some broader issue. (They may ultimately find that the initial
suggestion was best, or that there was no appetite for the change, or no
appetite for implementation, etc., of course. A choice to augment the
RELAX NG is a legitimate tactical decision to help the user, not a
strategic decision to develop Schematron; the strategic choice is logically
prior to the tactical one.)
My involvement in Schematron evolution cut short prematurely when I had to
step back, with Schematron incomplete. For example, when I came up with
phases, it was obvious to me that it would need some sequencing or
inheritance mechanism added on top. Or that type annotation was a case of
something useful (hence, sch:properties.) Or that extending Schematron to
interactive editors might require other features or conventions (hence the
addition of warn, caution, info, note etc for @ROLE; but I was so pleased
to see Schematron QuickFix.) Or that there were other forms of logic
possible and useful (such as a Schematron with a QLB to an XML-aware
Prolog.)
Cheers
Rick
B.t.w., I don't like the details of Fuzzy Schematron thought-bubble,
either: there is no need for the validation SVRL to be filtered by the
probabilities or have their operation changed: the probabilities are
properties of a valid or invalid subject for a different process.
…On Mon, Aug 23, 2021 at 8:20 AM Tony Graham ***@***.***> wrote:
Tony wrote:
Unless and until you can get editors to recognise role="INFO
documentation" as something special, the Schematron mechanism will result
in an explosion of error messages, blue squiggly lines, and blue margin
markers, or similar
Sure, and I certainly appreciate that Schematron is sometimes used in
progressive validation, after the grammar.
Even if the Schematron is the only schema and the document is revalidated
as you type, current behaviour for Schematron messages is going to present
every INFO message anywhere in the document.
But why take a passive approach? Tom is making a specific request, sure;
but it is also something that shows up a limitation/opportunity in
Schematron, and it can be treated as useful feedback on gaps and
requirements.
@tomschr <https://github.com/tomschr> can work out which approach works
best in their case, but why reinvent the wheel? Why see everything through
the prism of Schematron? Why invent Fuzzy Schematron in response to a
question about doc comments in Relax-NG? Instead of putting comments in an
existing file and using an existing convention that shows them to the user,
you want to split the comments into a (probably) completely different file
and rely on machinery that doesn't yet exist?
The issue of what gets the job done for him today is useful; but the issue
of what underlies his request is more important for a standard, isn't it?
IMO, what's important for a standard is that it codify useful and
interoperable things.
There's many and varied ways for something to get to the point of being
shown to be useful and interoperable, of course, but I would resist calling
something a standard if neither of those were true. I've been in a
slow-moving exchange on xml-dev about the usefulness or otherwise of SGML's
LPDs. There was a brief moment when I was reading about them before I used
them when I thought they were useful and interoperable, but neither turned
out to be true IMO. Being in the standard didn't make it so.
There is no need for providing one to exlude the other: augmenting the
RELAX NG but leaving the gap in Schematron is a wasted opportunity.
Except that you previously side-stepped anything to do with the RNC.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#3 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AF65KKL5OE4OK2OFKWHVAYLT6FZ3PANCNFSM5CHFUOFA>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
|
Lets consider a QLB for XSLT 4.
People could propose the facilities, it could go onto the "Open
Documentation" (that is what I am calling it, not "Open Standard") site,
but with a note saying this is not part of the ISO standard (and is not
final, and might be proposed for an update to the standard, but even if it
were adopted into the ISO standard would presumably not be normative text
anyway.)
(We are about to switch over to the new Schematron.com website this week on
the new platform, by the way.)
Regards
Rick
…On Mon, Aug 23, 2021 at 8:34 AM Tony Graham ***@***.***> wrote:
*New Pattern:*
...
This is the kind of thing that I would like to see on the planned "open
standard" Schematron site, actually. (Then it is available,
and SC34 can decide whether to also adopt it or not.) To read about that,
see
*
https://schematron.com/2021/08/plan-for-alternative-open-standard-text-for-schematron/
That proposes "an alternative description of exactly the same technology
as ISO Schematron describes". It's not obvious how 'new pattern' and
'exactly the same technology' are meant to fit together.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#3 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AF65KKLAWZGA5UVCELJJPQLT6F3PVANCNFSM5CHFUOFA>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
There is an existing place for proposals: https://github.com/Schematron/schematron-enhancement-proposals/issues It already has 18 proposals, including some from you. It's pinned to the top of the page for the Schematron organisation here on GitHub: https://github.com/Schematron The existence of the enhancement proposals is highlighted every month in the 'Schematron List Guidelines' post on the Schematron mailing list. |
As before, I am referring to current behaviour.
Everyone is allowed to: https://github.com/Schematron/schematron-enhancement-proposals/issues I was questioning the connection between Fuzzy Schematron and a request for doc comments. Sometimes a request for doc comments is just a cigar, or something like that.
Who said that Schematron is not evolving? As before: https://github.com/Schematron/schematron-enhancement-proposals/issues
The monthly guidelines for the Schematron community's mailing list includes:
Hence the W3C XSL WG (or just its FO subgroup) didn't look beyond its charter requirement to use CSS properties with their current meaning (https://www.w3.org/Style/2000/xsl-charter.html), didn't treat the CSS2 'vertical-align' property (https://www.w3.org/TR/CSS2/visudet.html#propdef-vertical-align) as a shorthand for multiple separate properties (https://www.w3.org/TR/xsl11/#vertical-align), didn't separate out the special case for table cells as the 'relative-align' property (https://www.w3.org/TR/xsl11/#relative-align) and didn't think to make 'relative-align' also apply to list items. BTW, this discussion is reaching an audience of four other people. Comments beyond comments on doc comments would probably be better served by being on the community mailing list. |
|
Tony wrote:
Rick wrote
- second, that innovation only happens when people know innovation is
welcome and useful
The monthly guidelines for the Schematron community's mailing list
includes:
... Your active participation and feedback about these is very welcome
I was not making a reflection on the list, or SC34 WG8 or anyone. Apologies
if it came over like that.
The innovation I was talking about is innovation in implementation:
experimental features and figuring out how to make the seeds like "phases"
reach their potential. But how many new features have been experimentally
implemented by people* since ISO Schematron was first standardized*?
(Obviously, I am not talking about new QLBs or fixing schema and editorial
errors.) Apart from SchematronQuickfix, which just uses another namespace,
I think the answer is kinda zero: are there any compelling evolutions of
Schematron that have proved themselves in an implementation?
There are lots of good and bad possible explanations, of course. But might
it also be, in some part, that standardization, for all its good, lead to
the idea that Schematron was baked and done, and that innovation needed to
be sanctioned by a Pope and Council? In which case, how can we turn the
idea around? Without making people think us whinging?
Rick
…On Thu, Aug 26, 2021 at 8:46 PM Tony Graham ***@***.***> wrote:
Even if the Schematron is the only schema and the document is
revalidated as you type, current behaviour for Schematron messages
is going to present every INFO message anywhere in the document.
Why? You configure the application to know which phase (or patterns,
or roles) should be dealt with by a processor that picks what to
validate. If it is put into a phase, in particular, validation of
As before, I am referring to current behaviour.
that schema by an existing validator would not have any effect. And
if you use the <assert test="true()"...> form, the assertion would
never fail as part of validation.
Why see everything through the prism of Schematron? Why invent
Fuzzy Schematron
Aren't I allowed to? ;-)
Everyone is allowed to:
https://github.com/Schematron/schematron-enhancement-proposals/issues
I was questioning the connection between Fuzzy Schematron and a request
for doc comments. Sometimes a request for doc comments is just a cigar, or
something like that.
But three other things come to mind:
- first, that a standard that does not evolve risks dying;
Who said that Schematron is not evolving? As before:
https://github.com/Schematron/schematron-enhancement-proposals/issues
- second, that innovation only happens when people know innovation is
welcome and useful
The monthly guidelines for the Schematron community's mailing list
includes:
SCHEMATRON ENHANCEMENT PROPOSALS
Please do take a look at the recently updated Schematron
Enhancement Proposals (SEPs):https://github.com/Schematron/schematron-enhancement-proposals
and the issues raised there. Your active participation and
feedback about these is very welcome, either via this mailing
list or on GitHub, wherever you feel more comfortable
contributing. As ever, it helps a great deal to hear from users
what they find useful.
- third, no standards-making group, when presented with an issue and a
solution, does not look beyond the concrete to the conceptual, to see
if
there is some broader issue.
Hence the W3C XSL WG (or just its FO subgroup) didn't look beyond its
charter requirement to use CSS properties with their current meaning (
https://www.w3.org/Style/2000/xsl-charter.html), didn't treat the CSS2
'vertical-align' property (
https://www.w3.org/TR/CSS2/visudet.html#propdef-vertical-align) as a
shorthand for multiple separate properties (
https://www.w3.org/TR/xsl11/#vertical-align), didn't separate out the
special case for table cells as the 'relative-align' property (
https://www.w3.org/TR/xsl11/#relative-align) and didn't think to make
'relative-align' also apply to list items.
------------------------------
BTW, this discussion is reaching an audience of four other people.
Comments beyond comments on doc comments would probably be better served by
being on the community mailing list.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#3 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AF65KKKAPOFJKEPMXXVDFO3T6YLPDANCNFSM5CHFUOFA>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
Problem
The current RNC schema of Schematron does not contain any documentation related strings. It is not clear from looking at the schema what these elements and attributes really mean. You have to read the specification.
Suggested solution
It is quite easy to document elements and attribute. For example, this is an original snippet:
to add documentation, use this:
To make this fly, I'd recommend:
Benefits
IMHO, adding documentation inside the Schematron schema has these benefits:
The text was updated successfully, but these errors were encountered: