Markdown query: Isn't the pegdown dialect of Markdown doomed?

[Roger Newson]

Many thanks to StataCorp for giving us Stata Version 15.

I have one immediate query about the new Markdown utilities (see help markdown). In this on-line help, it is stated that Stata's Markdown utilities use the pegdown dialect of Markdown, described at

https://github.com/sirthias/pegdown

However, when I visit this, I find a "Deprecation Note" to the effect that the pegdown dialect of Markdown is no longer supported, and that its users should migrate to Vladimir Schneider's flexmark java, described at

https://github.com/vsch/flexmark-java

So, is that also the official recommendation of StataCorp? And, if not, then what is?

Best wishes

Roger

[Hua Peng (StataCorp)]

pegdown as a markdown dialect is very much alive and fine. On the other hand, the original pegdown processing library (https://github.com/sirthias/pegdown) is deprecated.

"Stata uses Flexmark's Pegdown emulation as its default Markdown document processing engine...", see -help markdown-.

[Roger Newson]

Many thanks for reassuring and unconfusing us. That makes sense.

[Hua Peng (StataCorp)]

You are very welcome. It is likely we add support for different dialects of Markdown in future.

[wbuchanan]

Hua Peng (StataCorp) are you using Antlr or something similar to parse the syntax? If there were Antlr definitions for the Stata and Mata languages available it could make it possible to build out something analogous to javadoc for Stata. Then it would extend beyond just reporting and could make it easier for users to develop helpfiles without having to learn smcl.

[Richard Williams]

Hua Peng (StataCorp) are you using Antlr or something similar to parse the syntax? If there were Antlr definitions for the Stata and Mata languages available it could make it possible to build out something analogous to javadoc for Stata. Then it would extend beyond just reporting and could make it easier for users to develop helpfiles without having to learn smcl.

I have no idea what you just said, but that part about making it easier to develop help files without having to use smcl definitely appeals to me. I hate writing help files.

[wbuchanan]

Richard Williams Antlr is a domain specific language used to generate parsers. Basically it allows you to define lexical (think reserved words) rules and grammatical (options all use parentheses around parameter values) rules and then spits out a set of object classes that allow you to parse things based on those rules. Javadocs is a standard way to document code in Java and the big rule is that it starts with /** and ends with */. Parameters for the methods are all labeled with @param and followed by the parameter name a space and then information about the parameter. The output is what you see if you look at the Java API but with a parser the output could be an SMCL file or a markdown file, etc...