search

xproc / 3.0-steps

Repository for change requests to the standard step library and for official extension steps
10 stars 7 forks source link

Restructuring the step summaries #592

Closed ndw closed 2 months ago

ndw commented 2 months ago

I was tinkering with a step last night and got a bee in my bonnet about the style of the step summaries. My first thought was that adding some syntax highlighting would improve things. And I guess maybe it did.

Then this morning, I got distracted by the idea that maybe the whole thing could be improved and made more readable.

So here it is. It's certainly different and...I think...it's an improvement.

One observation: the links from the names of ports and options in the summary to their descriptions only work if the descriptions are formatted as a variable list. The fact that we haven't done that in a lot of places is interesting.

This relates to @xatapult 's thoughts about refactoring the spec entirely in some future version. But in this case there's no change in the spec, just a change in the presentation.

ndw commented 2 months ago

It's an annoying "security feature" of the PR builds that stylesheet changes aren't reflected in them. See this copy to preview the style changes.

ndw commented 2 months ago

I've added the implementation defined/dependent features to the summary and done a better brute-force job of linking from the names of ports and options to their descriptions.