Add DeclarationReference rules for use with DiaGrammar.

[greggirwin]

Per comments here: https://github.com/microsoft/tsdoc/commit/c4bedf9c36cc2b3ec803612185ed107f0c3ce461#commitcomment-45973734

[ghost]

All CLA requirements met.

[octogonz]

@greggirwin thanks for contributing this!

Could you provide some details:

• What is the benefit of the .rule file (as compared to the .grammarkdown file, for example)?
• Is the .rule file an input for a particular tool? (How do we invoke that tool?)
• How should it be kept up to date? (Is there documentation somewhere for the file format?)

[greggirwin]

• What is the benefit of the .rule file (as compared to the .grammarkdown file, for example)?

We don't have a %.grammarkdown metagrammar for our tool (yet), so we can't use it directly for diagram generation. We can auto translate ABNF, YACC, McKeeman, and others, but didn't know about %.grammarkdown until we found your TSDoc work for it.

• Is the .rule file an input for a particular tool? (How do we invoke that tool?)

Yes, it's a commercial tool. https://www.redlake-tech.com/products/diagrammar-for-windows/

The free version just watermarks the diagram, with no other limitations. For FOSS projects, we can render a final diagram for them, so they can use the free version, or offer discounted licenses.

• How should it be kept up to date? (Is there documentation somewhere for the file format?)

DiaGrammar's default grammar is the Red Language parse dialect (https://github.com/red/docs/blob/master/en/parse.adoc). If you use DiaGrammar itself, maintenance should be pretty easy on your end, plus you can tweak the look, or you can hit us up when you make changes and we'll try to make time to sync it up for you.

Then it's just a matter of where/how you want the diagram(s).

[greggirwin]

I can't guarantee we'll do a %.grammarkdown metagrammar anytime soon, but since it looks like an extended McKeeman form, there's at least a precedent for the model.

[octogonz]

I can't guarantee we'll do a %.grammarkdown metagrammar anytime soon, but since it looks like an extended McKeeman form, there's at least a precedent for the model.

The Grammarkdown project is maintained by @rbuckton. Its spec is here: https://github.com/rbuckton/grammarkdown

[rbuckton]

@greggirwin grammarkdown is a package I wrote a number of years ago while working on TypeScript, to make it easier to navigate the ECMAScript grammar. Its syntax is roughly based off of markdown, and it's currently used by ecmarkup, which is the tooling used by TC39 to author and generate the specification for ECMA-262 (nee. ECMAScript, JavaScript). grammarkdown has a language service for VS Code, and a JavaScript/TypeScript API that can be used to write a custom transformer to convert it into other formats, which currently include HTML, ECMArkup (an HTML dialect with some custom elements), and Markdown.

I primarily wrote grammarkdown to be a document authoring tool, so its missing some things that traditional grammar formats like ABNF or YACC support (so it can't exactly be used to generate a lexer/parser). I'm welcome to contributions if someone wants to write an emitter for a format that Red/Diagrammar supports.

[greggirwin]

Thanks @rbuckton. Good info. Rather than contributing to the JS code, we'd probably write a metagrammar for it, for DiaGrammar. That's in our wheelhouse and where we'd add the most value. With that, we can translate the rules and not only generate diagrams but write interpreters, use it to test files, etc..

We haven't documented the metagrammar dev process for DiaGrammar yet, but metagrammars are basically just a special kind of grammar, on disk like any other, so users can develop their own. If you wanted to build one at some point before we get to it, we'd certainly help answer questions.