Page MenuHomePhabricator

Better documentation for terminology and parameters in wikilambda-(renderer|parser)-(unexpected-result|unknown)-error
Closed, ResolvedPublicBUG REPORT

Description

These four messages have two closely-related issues:

  1. wikilambda-renderer-unexpected-result-error
  2. wikilambda-renderer-unknown-error
  3. wikilambda-parser-unexpected-result-error
  4. wikilambda-parser-unknown-error

Issue 1: the $1 parameter is not documented in qqq.

Issue 2: The terms "Display function" and "Reading function" must be documented in qqq or in the glossary.

Event Timeline

I've now done (1) on-wiki on TWN. Sorry for that miss when I did code review, it was a last-minute change.

For (2), I do not know how to best re-explain it beyond what was already in the qqq. Note that the 'glossary' is unofficial (and rather toxic to try to read, let alone edit); I don't think adding yet more stuff there is helping anyone. We're going to be launching these to the community soon with the weekly Update and documentation on-wiki, which is probably the better venue?

In short form for now, before the proper announcement and documentation:

A "display function" or renderer is a Wikifunctions Function that converts a Type into a string that users can understand, e.g. a Number '123456' -> '123,456' in International English, '1,23,456' in Indian English, '123.456' in French, etc., or a Date '2024','03','12' -> '2024-03-12', or similar.

A "reading function" or parser is a Wikifunctions Function that convert user text input from a string into a given Type, e.g. "123457" -> the Number '123456', or "2024-03-12" -> the Date '2024','03',12'.

Is that sufficient?

I've now done (1) on-wiki on TWN. Sorry for that miss when I did code review, it was a last-minute change.

Thanks :)

For (2), I do not know how to best re-explain it beyond what was already in the qqq.

From what you write further in this task, I understand that a "display function" is, more or less, a synonym of "renderer", and a "reading function" is a synonym of "parser". Is that correct? If so, then it's enough. "Renderer" and "parser" are already in the Glossary, and I just didn't know that these are synonyms.

Note that the 'glossary' is unofficial (and rather toxic to try to read, let alone edit);

Hard to edit indeed, because unfortunately we never developed proper glossary management software, but we really should. However, it's pretty OK to read, and it has been very useful for localizing the WikiLambda extension. (And I'm not sure why do you say it's "unofficial", given that it was created by the project's founder and heavily edited by the staff technical writer. There should be a good Wikifunctions / WikiLambda / Abstract Wikipedia glossary, because it's a complex set of technologies with its own rich terminology; should it be "official" or not is not really important.)

A "display function" or renderer is a Wikifunctions Function that converts a Type into a string that users can understand, e.g. a Number '123456' -> '123,456' in International English, '1,23,456' in Indian English, '123.456' in French, etc., or a Date '2024','03','12' -> '2024-03-12', or similar.

A "reading function" or parser is a Wikifunctions Function that convert user text input from a string into a given Type, e.g. "123457" -> the Number '123456', or "2024-03-12" -> the Date '2024','03',12'.

Is that sufficient?

Yes, thanks!

"Renderer" and "parser" are already in the Glossary, and I just didn't know that these are synonyms.

Note the term "renderer" is currently used in a way completely different than originally proposed - see T359786: Rename Z4K5 from renderer to linearizer, or rename "renderer" to something else