Making records and options more consistent

Hello,

In meeting 70, MK observed[1] that we currently describe the options map passed to some functions (parse-csv in this case) using a tabular structure but that we should use records. I took an action to investigate.

Currently, we have records, for example the uri-structure-record[2], and option descriptions, for example in, parse CSV[3].

Record markup isn’t a good substitute for the existing options markup because it doesn’t support default values or value descriptions. (In fact, it doesn’t support descriptions at all, those are provided separately for records in prose that follows the definition of the record.)

But options markup is (almost) a superset of record markup, so it is possible to generate record structures from the option descriptions.
(The missing detail is the ability to distinguish between required and optional fields, but that could be added.)

I’ve mocked this up. In the mockup, I’ve preceded every description of an options map with a generated record format. For example, before the options map described in parse-csv[4]. I’ve also replaced the current definition of the uri-structure-record with options markup[5] (this part has to be done by hand, so I’ve only done it for the uri-structure-record). This makes the presentation of the following description of the record consistent with the options markup.

We’d have to work out a bit of markup for managing when and where the formatted record was generated, but that’s probably doable. Is this something we want to pursue?

                                        Be seeing you,
                                          norm

[1] https://qt4cg.org/meeting/minutes/2024/03-19.html#pr-1066
[2] https://qt4cg.org/specifications/xpath-functions-40/Overview.html#uri-structure-record
[3] https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-parse-csv
[4] https://qt4cgtest.nwalsh.com/branch/action-qt4cg-70-01/xpath-functions-40/Overview.html#func-parse-csv
[5] https://qt4cgtest.nwalsh.com/branch/action-qt4cg-70-01/xpath-functions-40/Overview.html#uri-structure-record

--
Norm Tovey-Walsh
Saxonica