[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: Shlomi Fish <shlomif@shlomifish.org>
• To: Norm Tovey-Walsh <ndw@nwalsh.com>
• Date: Sun, 4 Jun 2023 18:30:26 +0300

hi all,

On Sun, 04 Jun 2023 15:16:38 +0100
Norm Tovey-Walsh <ndw@nwalsh.com> wrote:

> 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.
> 

re "markdowns":

[[
Why the Markdown Dialects Should be Avoided as much as Possible [ #markdowns ]

There are too many Markdown dialects (e.g: GitHub's, reddit's, Stack
Exchange's) each one with its own army and navy (= fragmentation and
incompatibilities). Moreover, they can only be converted to XHTML.
]]

asciidoctor is less fragmented. nevertheless , mediawiki syntax  is very bad
too.

> 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  



-- 

Shlomi Fish       https://www.shlomifish.org/
https://youtu.be/KxGRhd_iWuE - Never Give Up!!

SMG: It was 1997-1998ish, Buffy started airing. So one day a group of
yeshivah pupils arrived to the studios saying they have some numereological
insights from the Jewish bible, about what will happen in Sunnydale next.
    — https://www.shlomifish.org/humour/Summerschool-at-the-NSA/

Please reply to list if it's a mailing list post - https://shlom.in/reply .

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