Re: Please stop writing specifications that cannot be parsed/processed by software

Norm Tovey-Walsh <[email protected]> Sat, 27 May 2023 10:53:48 +0100
Newsgroups	gmane.text.xml.devel
Message-ID	<[email protected]>
> This is really interesting. Michael, would you expand on this please?

FWIW, the XProc specification also does this. The XProc standard step
library is generated from the fragments in the prose specification. The
XProc “p:xslt” step specification begins:

<section xmlns="http://docbook.org/ns/docbook" 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="c.xslt">
  <title>p:xslt</title>
  <para>The <tag>p:xslt</tag> step invokes an XSLT stylesheet.</para>
  <p:declare-step type="p:xslt">
    <p:input port="source" content-types="any" sequence="true" primary="true"/>
    <p:input port="stylesheet" content-types="xml"/>
    <p:output port="result" primary="true" sequence="true" content-types="any"/>
    <p:output port="secondary" sequence="true" content-types="any"/>
    <p:option name="parameters" as="map(xs:QName,item()*)?"/>
    <p:option name="static-parameters" as="map(xs:QName,item()*)?"/>
    <p:option name="global-context-item" as="item()?"/>
    <p:option name="populate-default-collection" as="xs:boolean?" select="true()" />
    <p:option name="initial-mode" as="xs:QName?"/>
    <p:option name="template-name" as="xs:QName?"/>
    <p:option name="output-base-uri" as="xs:anyURI?"/>
    <p:option name="version" as="xs:string?"/>
  </p:declare-step>
  <para>If <option>output-base-uri</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:xslt</tag> in the case
    of a syntactic shortcut value).</para>
  …

That “p:declare-step” declaration embedded in the documentation *is* the
p:declare-step for the p:xslt step. It’s pulled out and formatted into
library.xpl by a stylesheet during the build process.

I consider this standard-operating-procedure if you’re documenting
something that you’re also defining. Either generate the library files
from the documentation or generate the documentation markup from the
library files. Never do both, independently.

DocBook: The Definitive Guide is an example that goes the other way. The
RELAX NG grammar is definitive and the syntax summaries in the guide are
generated from that schema. I think TEI uses a variety of literate
programming tools to go the other way, generating RELAX NG grammars from
the documentation.

If I was starting over, I think I’d try to do that with DocBook as well,
but historically the documentation and the schema (originally an SGML
DTD) were seperate. Making the DocBook documentation literate *and*
generating *exactly the same schema* was impractical (or perceived to be
impractical anyway) at the time when we could have done it that way.

                                        Be seeing you,
                                          norm

--
Norm Tovey-Walsh <[email protected]>
https://norm.tovey-walsh.com/

> Quotation, n: The act of repeating erroneously the words of
> another.--Ambrose Bierce
signature.asc (application/pgp-signature, 227 B)