[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

Re: Please stop writing specifications that cannot beparsed/pr

• From: Norm Tovey-Walsh <ndw@nwalsh.com>
• To: xml-dev@lists.xml.org
• Date: Sun, 04 Jun 2023 15:16:38 +0100

Dimitre Novatchev <dnovatchev@gmail.com> writes:
> To this day I have been often wondering where to find the XML Schema
> for this type of document. Or is it a secret?

For the QT4 specifications, the schema is here:

  https://raw.githubusercontent.com/qt4cg/qtspecs/master/schema/xsl-query.dtd

But it seems unlikely that you didn’t know that, so I probably don’t
understand the question.

> For me, using such "hi-tech" language in order to specify what you
> want to say and be understood, has always seemed an unwanted and
> unnecessary obstacle in the specification-creation process -- one that
> stifles the author and digresses him elsewhere -- not where the focus
> of the main topic is.
>
> I envy GitHub authors who only have to use MD, and can easily produce
> stunning documents.

<aside>
I have never seen a “stunning” MD document. I’ve seen a fair number of
nice enough ones, but nothing that comes close to capturing anything
like the richness necessary to leverage the document for more than
making it pretty on the screen or on paper.
</aside>

If you’re willing to invent arbitrary amounts of ad hoc syntax, and edit
that syntax in a text editor with no understanding of the syntax (or
write a customized editor, I suppose), it’s probably possible to design
a Markdown-style syntax that would capture the structure of, for
example, the QT specifications, but *BOY* it would not be pretty. (If
you think I’m mistaken, I invite you to propose a MD style grammar that
will capture the information necessary to generate them. You get zero
credit for 80% of the job. The first 80% is easy. It’s a zero-sum
challenge, succeed or fail, there is no try.)

We get actual value from having the XML structures we’re designing
marked up semantically, and the function signatures marked up, and the
examples marked up. We use them to generate tests, test coverage,
downstream grammars, and other artifacts. The specifications are much
more than the prose you read in your browser.

The actual markup we use is a bit ugly. It was designed in the
mid-1990’s when DTDs were the only thing available and the XML community
still thought a thousand schema flowers would bloom. And then it was
customized in various ways by various users over a couple of decades for
QT.

If we were starting over, we’d use something off the shelf. Like JATS or
BITS or DocBook. Or maybe we’d just use HTML5 with class attributes and
some extension elements and validate the whole thing with some
combination of RELAX NG and Schematron. I don’t know.

We could convert to one of those, but it would be a full-time job for at
least several months and then we’d have to retrain all the editors, and
when we were all done, we’d have made no progress on the languages we’re
designing. And it probably wouldn’t be *objectively* simpler, it would
just be differently complicated. Probably a little more disciplined, but
I wouldn’t swear that the discipline would be obvious to someone looking
in from the outside.

Would I like to do that? Some days. The XProc specifications are in a
lightly customized flavor of DocBook. I think they’re easier to read and
easier to understand, but I would.

I’d also like to write a new XML specification that incorporates XML,
XML Namespaces, XML Base, XLink, and XInclude, into a single, cohesive
document. Is that ever going to be the best use of my time? Seems
unlikely.

So we muddle along with the system we have, because we have higher
priority goals than simplifying the markup we use to make
specifications.

If you don’t get value out of markup in your work, don’t use it. Write
in any one of the dozens of Markdown flavors that works best for you.
Write in plain text. Write in Word, if you want.

If you want to contribute to QT, write the prose in Markdown and then
bribe one of the other editors to convert it into specification XML, if
you want. The markup is *so* much the *very easiest* part of writing
specifications, you might be surprised how far a good bottle of rye
whiskey will get you :-)

> If someone needs so much strict structure, please use ChatGPT or iXML
> -- but please, behind the scenes, where these do belong.

<aside> 
ChatGPT is a supremely good bullshit generator powered by plagiarism on
a staggering scale. It has no place in any serious intellectual effort.
At best, you’re giving your (or someone else’s) intellectual property to
rapacious commerical organizations with no interest in your well-being.
At worst, you’re going to get back lies that are indistinguishable from
the truth.
</aside>

                                        Be seeing you,
                                          norm

--
Norm Tovey-Walsh <ndw@nwalsh.com>
https://norm.tovey-walsh.com/

> Design and programming are human activities; forget that and all is
> lost.--B. Stroustrup

Attachment: signature.asc
Description: PGP signature

• Follow-Ups:
  • Re: Please stop writing specifications that cannot beparsed/processed by software
    • From: Michael Kay <mike@saxonica.com>
  • Re: Please stop writing specifications that cannot beparsed/processed by software
    • From: Shlomi Fish <shlomif@shlomifish.org>

• References:
  • Re: Please stop writing specifications that cannot beparsed/processed by software
    • From: Dimitre Novatchev <dnovatchev@gmail.com>