search

masak / alma

ALgoloid with MAcros -- a language with Algol-family syntax where macros take center stage
Artistic License 2.0
139 stars 15 forks source link

Make a script that generates examples/README.md #516

Open masak opened 5 years ago

masak commented 5 years ago

After #508, I realize I want more. The test currently just checks the links and checks that all the scripts are listed, but we could generate the whole README.md from individual .007 script files. Extracting the descriptions from top-level comments in the scripts themselves, and the top-level comment in the README.md from \<mumble>.

Then we can check that generated result against the actual script file on disk.

Let's make this a Perl 6 script first, close this issue, and then try to turn it into a .007 script. (That we can put in examples/! How meta.) The .007 script will require the ability to open files, which is probably a good thing. Also with (#156), in the fullness of time.

vendethiel commented 5 years ago

A Literal Programming reader macro? :)

masak commented 5 years ago

Maybe nothing quite so fancy, but... relatedly, I have been thinking about extracting comments (a) from the top of a script/module, (b) above classes and type declarations, (c) above functions/methods, and producing an API document from it, à la JavaDoc HTML output or similar.

I think comments-above make more sense than Python's "first string" convention. Some thought can be put into whether the comments should "attach" to the Qtree somehow, so that we don't have to (yuck) reparse the document to do this.

If the stars align right, this issue could then just be a special case of producing API documentation for an examples "module".

masak commented 5 years ago

Although I love Markdown (and will use it this time for the README.md), I don't think I want those API comments to be in Markdown. I see Markdown as fundamentally flawed — it's not a simple format, with predictable rules. The CommonMark effort really only hammers this home for me. To make it worse (and partly because it's hard to parse), there are oodles of dialects.

Not sure what I prefer instead. reStructuredText? org-mode? POD? Perl 6 Pod? Or just a very unassuming subset of Markdown (making the dialects issue worse) with, um, lists, paragraphs, code blocks, headings, bold/italics/code.