Appendix 2 is truncated

[jmdyck]

Appendix 2 ends with "MONAD?", so it's missing all of "N==?" to "XUNAME".

Does the missing material need to be transcribed, or has it just been inadvertently left out?

[taradinoc]

The part that's there was added in #41. I think it probably needs to be transcribed, unless @OrangeToucan has more that hasn't been pushed.

[taradinoc]

Now that I've actually re-read the whole thread: in https://github.com/taradinoc/mdl-docs/pull/41#issuecomment-354531077, I recommended automating it, since we'd been talking about a different markup language in #6. I was working on the Sphinx domain model in https://vaporware.atlassian.net/browse/ZILF-120, but haven't been back to it lately.

It's not an especially informative part of the manual, just a quick reference to all the SUBRs mentioned in the rest of the text (which we can now search), so I'm not in a hurry to type it up, but I'd accept a PR.

[jmdyck]

I recommended automating it

You mean generating the (missing) entries of Appendix 2 by extracting the information from 'declarations' in the body of the document? I'm doubtful that's possible.

• Distinguishing a body-decl from some example MDL code looks tricky.
• The body-decl doesn't have all the info that appears in Appendix 2.
• Not every SUBR has a body-decl.

[taradinoc]

You mean generating the (missing) entries of Appendix 2 by extracting the information from 'declarations' in the body of the document?

In the linked comment, I was talking about "transcribing them in some machine-readable format that a script can turn into Markdown (or, eventually, RST)", because this is on track to be the longest section by far, and I'd like to avoid having to reformat it all by hand.

Even if we don't move to Sphinx, the layout of Appendix 2 just doesn't translate very well to Markdown. We can't format the code block and the summary together as one paragraph, which makes it hard to see each function as a visual "unit". Horizontal bars between the functions might help.

But even the original Appendix 2 isn't especially readable:

[jmdyck]

I was talking about "transcribing them in some machine-readable format that a script can turn into Markdown (or, eventually, RST)", because this is on track to be the longest section by far, and I'd like to avoid having to reformat it all by hand.

Markdown is a machine-readable format. I wrote code to read my markdown file, and it found some transcription errors, and also some errors in the existing file. (It might even have found some errors in the original source, but it's hard for me to say.)

I agree that the rendered result isn't great, and you might well want to shift to a different source format, but it seems to me that markdown is a decent starting point for an automated reformat of Appendix 2. (I can't imagine why you'd need to reformat by hand.)

[taradinoc]

Clearly your Markdown-fu is stronger than mine. Thanks for the PR.