search

KhronosGroup / Vulkan-Site

Vulkan Documentation Project framework for integrated documentation site with spec, proposals, guide, and more
Other
25 stars 2 forks source link

Going through all instances of X #55

Open marty-johnson59 opened 12 months ago

marty-johnson59 commented 12 months ago

Moving this issue over from the archived Antora repo (https://gitlab.khronos.org/vulkan/antora/-/issues/5 from @ShabbyX). Note: there are some comments on the archived repo on this issue..

The all-in-one-page spec is horribly slow to load, but it does give one ability that the chunked spec (or the antora version) doesn't. You can go through all instances of some token over the whole spec. With GL, extensions were easy to inspect in one aspect at least; you had the text of the whole extension all together somewhere. Someone implementing / using the extension could get all the details that are needed from that. With Vulkan, that's nearly impossible without grepping through the source. The ifdefs (which are the only mark of what text an extension affects) disappear from the output, so you can't really tell from the built spec where exactly an extension touches. That makes it easy to miss things. That said, at least going through the whole spec and looking at matches of someTokenFromExtension would get you 95% of the way. I'm not sure what a good way would be to do that in a chunked build, but something like this could work:

someTokenFromExtension ◀ Match 12 / 67 ▶

Where you can enter someTokenFromExtension in the search box (that's the ASCII art box), and get a chance to flip through all the matches one by one (with the left/right triangle buttons) (or jump to a match (by editing the match number, the other ASCII art box))

oddhack commented 12 months ago

I usually suggest people go to the extension reference page (e.g. the extension-specific portion of the appendix pulled out as a separate page). That's generally the first thing that turns up in a web search on an extension name. From there the API summary points you to everything defined by that extension. I realize that's not the ask, but it is an alternative, as is just searching in the single-page spec, which we will continue to publish for at least some considerable time to come.

Getting Lunr to actually index and show every match, in order, might be difficult. It is built around prioritizing results, AFAICT.

oddhack commented 9 months ago

Marking this deferred. The combination of the existing single-page HTML spec and the complexity of changing how antora-lunr finds and presents search results in a priority order make it a lot of work for a relatively limited use case.

oddhack commented 9 months ago

Fixed link to internal gitlab site.