Updated step library presentation

Hi folks,

In the run-up to producing XProc 3.1 specifications, I found myself fussing with the way step summaries are presented. Initially, I thought that the formatting of the declarations could be improved with a bit of syntax highlighting.

It was an improvement, but it was still pretty hard to read and it bothered me that for some declarations, there either had to be awkward line breaks or the content was too wide to fit on the page.

So I tried something more radical. You can see the results in the current editoral draft:

   https://spec.xproc.org/master/head/steps/

Comments welcome.

The steps don’t all have absolutely uniform markup for how ports and options are described. That’s unfortunate, but I think fixing it would be (a) a big job, and (b) introduce a real possibility of accidental semantic changes. Something to leave for 4.0, I think.

As a consequence, the links from the summary to the place in the description where the item is discussed are a little bit heuristic. I think they’re usually good enough to justify including the links, but it’s possible that some are wrong.

Please open issues for any bad (or missing) links that you notice.

                                        Be seeing you,
                                          norm

--
Norm Tovey-Walsh <ndw@nwalsh.com>
https://norm.tovey-walsh.com/

> I maintain there is much more wonder in science than in pseudoscience. And in addition, to whatever measure this term has any meaning, science has the additional virtue, and it is not an inconsiderable one, of being true.--Carl Sagan

Received on Thursday, 1 August 2024 09:48:23 UTC