Permalink
Browse files

Merge pull request #48 from eriksiegel/reorganize-text-steps

Reorganize text steps
  • Loading branch information...
eriksiegel committed Feb 11, 2019
2 parents 0ff55f4 + 061cfeb commit 2ce8ee1d92cb23070aa74220c412d14e25ec985d
@@ -1,221 +1,100 @@
<?xml version="1.0" encoding="UTF-8"?>
<specification xmlns="http://docbook.org/ns/docbook"
xmlns:cs="http://www.w3.org/XML/XProc/2006/04/components#"
xmlns:e="http://www.w3.org/1999/XSL/Spec/ElementSyntax"
xmlns:p="http://www.w3.org/ns/xproc"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id='step-text'
class="ed" role="step"
version="5.0-extension w3c-xproc">
<info>
<title>XProc 3.0: text steps</title>
<!-- defaults to date formatted <pubdate>2014-12-18</pubdate> -->
<copyright><year>2018</year><holder>@@FIXME:</holder></copyright>

<bibliorelation type="isformatof" xlink:href="specification.xml">XML</bibliorelation>
<authorgroup>
<author>
<personname>Norman Walsh</personname>
</author>
<author>
<personname>Achim Berndzen</personname>
</author>
<author>
<personname>Gerrit Imsieke</personname>
</author>
<author>
<personname>Erik Siegel</personname>
</author>
</authorgroup>

<abstract>
<para>This specification describes the <code>p:text-head</code>,
<code>p:text-join</code>, and
<code>p:text-tail</code> steps
for
<citetitle>XProc 3.0: An XML Pipeline Language</citetitle>.</para>
</abstract>

<legalnotice role="status">

<para><emphasis>This section describes the status of this document at
the time of its publication. Other documents may supersede this
document.</emphasis></para>

<para>This document is derived from
<link xlink:href="https://www.w3.org/TR/2010/REC-xproc-20100511/">XProc:
An XML Pipeline Language</link> published by the W3C.</para>
</legalnotice>
</info>

<section xml:id="introduction">
<title>Introduction</title>

<para>This specification describes the
<code>p:text-head</code>,
<code>p:text-join</code>, and
<code>p:text-tail</code> XProc steps.
A machine-readable description of
these steps may be found in
<link xlink:href="steps.xpl">steps.xpl</link>.
</para>

<para>Familarity with the
general nature of <biblioref linkend="xproc30"/>
steps is assumed; for background details, see
<biblioref linkend="xproc30-steps"/>.</para>
</section>

<section xml:id="c.text-head">
<title>p:text-head</title>

<para>The <code>p:text-head</code> step returns lines from the beginning of a text file.</para>

<p:declare-step type="p:text-head">
<p:output port="result" primary="true" content-types="text/plain"/>
<p:option name="href" required="true" as="xs:anyURI"/>
<p:option name="count" required="true" as="xs:integer"/>
</p:declare-step>

<para>The <tag>p:text-head</tag> step returns lines of the file named in the <option>href</option> option:</para>
<itemizedlist>
<listitem>
<para>If the <option>count</option> option is positive, the <tag>p:text-head</tag> step returns the first
<option>count</option> lines</para>
</listitem>
<listitem>
<para>If the <option>count</option> option is zero, the <tag>p:text-head</tag> step returns all lines</para>
</listitem>
<listitem>
<para>If the <option>count</option> option is negative, the <tag>p:text-head</tag> step returns all lines except
the first <option>count</option> lines</para>
</listitem>
</itemizedlist>

<para><error code="D0064">It is a <glossterm>dynamic error</glossterm> if the <option>href</option> option value is
not a valid <type>xs:anyURI</type>.</error> If the <option>href</option> option is relative, it is made absolute
against the base URI of the element on which it is specified (<tag>p:with-option</tag> or <tag>p:text-head</tag> in
the case of a syntactic shortcut value).</para>

<para>The step returns a <tag>c:result</tag> element containing one <tag>c:line</tag> child element for each line.
Lines are identified as described in <link xlink:href="https://www.w3.org/TR/xml/#sec-line-ends">XML, 2.11
End-of-Line Handling</link></para>

<simplesect>
<title>Document properties</title>
<para feature="load-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>

<section xml:id="c.text-join">
<title>p:text-join</title>

<para>The <code>p:text-join</code> step concatenates two or more text
files.</para>

<p:declare-step type="p:text-join">
<p:output port="result" primary="true" sequence="true" content-types="text/plain"/>
<p:option name="href" required="true" as="xs:anyURI"/>
</p:declare-step>

<para>FIXME: T.B.D.</para>

<simplesect>
<title>Document properties</title>
<para feature="load-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>

<section xml:id="c.text-tail">
<title>p:text-tail</title>

<para>The <code>p:text-tail</code> step returns lines from the end of a text file.</para>

<p:declare-step type="p:text-tail">
<p:output port="result" primary="true" content-types="text/plain"/>
<p:option name="href" required="true" as="xs:anyURI"/>
<p:option name="count" required="true" as="xs:integer"/>
</p:declare-step>

<para>The <tag>p:text-tail</tag> step returns lines of the file named in the <option>href</option> option:</para>
<itemizedlist>
<listitem>
<para>If the <option>count</option> option is positive, the <tag>p:text-tail</tag> step returns the last
<option>count</option> lines</para>
</listitem>
<listitem>
<para>If the <option>count</option> option is zero, the <tag>p:text-tail</tag> step returns all lines</para>
</listitem>
<listitem>
<para>If the <option>count</option> option is negative, the <tag>p:text-tail</tag> step returns all lines except
the last <option>count</option> lines</para>
</listitem>
</itemizedlist>

<para><error code="D0064">It is a <glossterm>dynamic error</glossterm> if the <option>href</option> option value is
not a valid <type>xs:anyURI</type>.</error> If the <option>href</option> option is relative, it is made absolute
against the base URI of the element on which it is specified (<tag>p:with-option</tag> or <tag>p:text-tail</tag> in
the case of a syntactic shortcut value).</para>

<para>The step returns a <tag>c:result</tag> element containing one <tag>c:line</tag> child element for each line.
Lines are identified as described in <link xlink:href="https://www.w3.org/TR/xml/#sec-line-ends">XML, 2.11
End-of-Line Handling</link></para>

<simplesect>
<title>Document properties</title>
<para feature="load-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>

<section xmlns="http://docbook.org/ns/docbook" xml:id="errors">
<title>Step Errors</title>

<para>This step can raise
<glossterm baseform="dynamic-error">dynamic errors</glossterm>.
</para>

<para><termdef xml:id="dt-dynamic-error">A <firstterm>dynamic
error</firstterm> is one which occurs while a pipeline is being
evaluated.</termdef> Examples of dynamic errors include references to
URIs that cannot be resolved, steps which fail, and pipelines that
exhaust the capacity of an implementation (such as memory or disk
space). For a more complete discussion of dynamic errors, see
<xspecref spec="xproc" xref="dynamic-errors"/>.
</para>

<para>If a step fails due to a dynamic error, failure propagates
upwards until either a <tag>p:try</tag> is encountered or the entire
pipeline fails. In other words, outside of a <tag>p:try</tag>, step
failure causes the entire pipeline to fail.</para>

<para>The following errors can be raised by this step:</para>

<?step-error-list level="none"?>

</section>

<xi:include href="conformance.xml"/>

<appendix xml:id="references">
<title>References</title>
<bibliolist>
<bibliomixed xml:id="xproc30"/>
<bibliomixed xml:id="xproc30-steps"/>
</bibliolist>
</appendix>

<!-- This glossary will automatically be elided if there are no
<specification xmlns="http://docbook.org/ns/docbook" xmlns:cs="http://www.w3.org/XML/XProc/2006/04/components#"
xmlns:e="http://www.w3.org/1999/XSL/Spec/ElementSyntax" xmlns:p="http://www.w3.org/ns/xproc"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="step-text" class="ed"
role="step" version="5.0-extension w3c-xproc">
<info>
<title>XProc 3.0: text steps</title>
<!-- defaults to date formatted <pubdate>2014-12-18</pubdate> -->
<copyright>
<year>2019</year>
<holder>@@FIXME:</holder>
</copyright>

<bibliorelation type="isformatof" xlink:href="specification.xml">XML</bibliorelation>
<authorgroup>
<author>
<personname>Norman Walsh</personname>
</author>
<author>
<personname>Achim Berndzen</personname>
</author>
<author>
<personname>Gerrit Imsieke</personname>
</author>
<author>
<personname>Erik Siegel</personname>
</author>
</authorgroup>

<abstract>
<para>This specification describes the optional text related steps for <citetitle>XProc 3.0: An XML Pipeline Language</citetitle>.</para>
</abstract>

<legalnotice role="status">

<para><emphasis>This section describes the status of this document at the time of its publication. Other documents
may supersede this document.</emphasis></para>

<para>This document is derived from <link xlink:href="https://www.w3.org/TR/2010/REC-xproc-20100511/">XProc: An
XML Pipeline Language</link> published by the W3C.</para>
</legalnotice>
</info>

<section xml:id="introduction">
<title>Introduction</title>

<para>This specification describes the optional text related XProc steps. A machine-readable description of these steps may be found in <link
xlink:href="steps.xpl">steps.xpl</link>. </para>

<para>Familarity with the general nature of <biblioref linkend="xproc30"/> steps is assumed; for background details,
see <biblioref linkend="xproc30-steps"/>.</para>
</section>

<!-- Include step descriptions: -->
<xi:include href="steps/markdown-to-html.xml"/>

<section xmlns="http://docbook.org/ns/docbook" xml:id="errors">
<title>Step Errors</title>

<para>These steps can raise <glossterm baseform="dynamic-error">dynamic errors</glossterm>. </para>

<para><termdef xml:id="dt-dynamic-error">A <firstterm>dynamic error</firstterm> is one which occurs while a pipeline
is being evaluated.</termdef> Examples of dynamic errors include references to URIs that cannot be resolved,
steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For
a more complete discussion of dynamic errors, see <xspecref spec="xproc" xref="dynamic-errors"/>. </para>

<para>If a step fails due to a dynamic error, failure propagates upwards until either a <tag>p:try</tag> is
encountered or the entire pipeline fails. In other words, outside of a <tag>p:try</tag>, step failure causes the
entire pipeline to fail.</para>

<para>The following errors can be raised by this step:</para>

<?step-error-list level="none"?>

</section>

<xi:include href="conformance.xml"/>

<appendix xml:id="references">
<title>References</title>
<bibliolist>
<bibliomixed xml:id="xproc30"/>
<bibliomixed xml:id="xproc30-steps"/>
</bibliolist>
</appendix>

<!-- This glossary will automatically be elided if there are no
terms marked up as 'firstterm's in this specification. -->
<xi:include href="../../../build/glossary.xml">
<xi:fallback>
<glossary xml:id="glossary">
<title>Glossary</title>
<para>Glossary needs to be generated</para>
</glossary>
</xi:fallback>
</xi:include>

<xi:include href="ancillary.xml"/>
<xi:include href="../../../build/glossary.xml">
<xi:fallback>
<glossary xml:id="glossary">
<title>Glossary</title>
<para>Glossary needs to be generated</para>
</glossary>
</xi:fallback>
</xi:include>

<xi:include href="ancillary.xml"/>

</specification>
@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="c.markdown-to-html" xmlns:p="http://www.w3.org/ns/xproc" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://docbook.org/ns/docbook">
<title>p:markdown-to-html</title>

<para>The <code>p:markdown-to-html</code> step returns lines from the beginning of a text document.</para>

<p:declare-step type="p:markdown-to-html">
<p:input port="source" primary="true" sequence="false" content-types="text/*"/>
<p:output port="result" primary="true" sequence="false" content-types="application/xhtml+xml"/>
<p:option name="parameters" required="false" as="map(xs:QName, item()*)"/>
</p:declare-step>

<para>The <tag>p:markdown-to-html</tag> step expects on its <port>source</port> port a text document in Markdown
syntax (TBD: REF TO MARKDOWN SPEC?) and converts this into XHTML. The result is returned on its <port>result</port>
port.</para>

<para>TBD</para>

<simplesect>
<title>Document properties</title>
<para feature="load-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>
@@ -189,6 +189,12 @@ linkend="rfc2119"/>.</para>
<xi:include href="steps/store.xml"/>
<xi:include href="steps/string-replace.xml"/>
<xi:include href="steps/tee.xml"/>
<xi:include href="steps/text-count.xml"/>
<xi:include href="steps/text-head.xml"/>
<xi:include href="steps/text-join.xml"/>
<xi:include href="steps/text-replace.xml"/>
<xi:include href="steps/text-sort.xml"/>
<xi:include href="steps/text-tail.xml"/>
<xi:include href="steps/unescape-markup.xml"/>
<xi:include href="steps/unwrap.xml"/>
<xi:include href="steps/uuid.xml"/>
@@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="c.text-count" xmlns:p="http://www.w3.org/ns/xproc" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://docbook.org/ns/docbook">
<title>p:text-count</title>

<para>The <code>p:text-count</code> step counts the number of lines in a text document and returns a single XML
document containing that number.</para>

<p:declare-step type="p:text-count">
<p:input port="source" primary="true" sequence="false" content-types="text/*"/>
<p:output port="result" primary="true" sequence="false" content-types="application/xml"/>
</p:declare-step>

<para>The <tag>p:text-count</tag> step counts the number of lines in the text document appearing on its
<port>source</port> port. It returns on its <port>result</port> port an XML document containing a single
<tag>c:result</tag> element whose contents is the string representing this count.</para>

<para>Lines are identified as described in <link xlink:href="https://www.w3.org/TR/xml/#sec-line-ends">XML, 2.11
End-of-Line Handling</link>.</para>

<simplesect>
<title>Document properties</title>
<para feature="count-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>
Oops, something went wrong.

0 comments on commit 2ce8ee1

Please sign in to comment.