Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Attempt to clarify p:error #624

Merged
merged 2 commits into from
Sep 8, 2024
Merged

Attempt to clarify p:error #624

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
25936eb
Attempt to clarify p:error
ndw Sep 6, 2024
59dae55
Don't make it implementation defined
ndw Sep 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 21 additions & 15 deletions steps/src/main/xml/steps/error.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,33 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="c.error">
<title>p:error</title>

<para>The <code>p:error</code> step generates a <glossterm role="unwrapped">dynamic error</glossterm> using the input provided
to the step.</para>
<para>The <code>p:error</code> step generates a
<glossterm role="unwrapped">dynamic error</glossterm> using the input provided to the
step.</para>

<p:declare-step type="p:error">
<p:input port="source" sequence="true" content-types="text xml"/>
<p:output port="result" sequence="true" content-types="any"/>
<p:option name="code" required="true" as="xs:QName"/>
</p:declare-step>

<para>This step uses the document provided on its input as the content
of the error raised. An instance of the
<tag>c:errors</tag> element will be produced on the error output port, as is
always the case for <glossterm baseform="dynamic error" role="unwrapped">dynamic errors</glossterm>.
The error generated can be caught by a <tag>p:try</tag> just like any
other dynamic error.</para>
<para>The <tag>p:error</tag> step always fails. It generates a single error with the
error code specified in the
<option>code</option> option. It also produces a <tag>c:errors</tag> document that
will be visible on the error port inside a <tag>p:catch</tag>.
(The error vocabulary is described in <biblioref linkend="xproc31"/>.)
</para>

<para>For authoring convenience, the <tag>p:error</tag> step is
declared with a single, primary output port. With respect to connections,
this port behaves like
any other output port even though nothing can ever
appear on it since the step always fails.</para>
<para>This step <rfc2119>should</rfc2119> include the content of the document
that appears on the <port>source</port> port in the error. If more than one
document appears on the <port>source</port> port of the <tag>p:error</tag> step, all
of the documents <rfc2119>must</rfc2119> be added to a single <tag>c:error</tag>
element.</para>

<para>For authoring convenience, the <tag>p:error</tag> step is declared with a
single, primary output port. With respect to connections, this port behaves like
any other output port even though nothing can ever appear on it since the step
always fails.</para>

<para>For example, given the following invocation:</para>
<programlisting language="xml">&lt;p:error xmlns:my="http://www.example.org/error"
Expand All @@ -34,8 +40,8 @@ appear on it since the step always fails.</para>
&lt;/p:with-input&gt;
&lt;/p:error&gt;</programlisting>

<para>The error vocabulary element (and document) generated on the
error output port would be:</para>
<para>The errors document generated on the error output port might be:</para>

<programlisting language="xml">&lt;c:errors xmlns:c="http://www.w3.org/ns/xproc-step"
xmlns:p="http://www.w3.org/ns/xproc"
xmlns:my="http://www.example.org/error"&gt;
Expand Down