Stream: IG creation
Topic: Ctrl-F Searchable Section Headings
Carl Anderson (Feb 04 2021 at 21:54):
When reviewing ballot feedback, often times the ballot comments reference particular section numbers. It's frustrating that the rendered IG does not seem to include those section numbers in searchable text via Ctrl-F. For example, if I want to jump to section 1.4.1 - I expect I should be able to press Ctrl-F and type 1.4.1 to get there. This doesn't seem to work (possibly) because of some CSS magic. Would it be possible to make them searchable? I'm happy to file an issue if this hasn't come up before.
Lloyd McKenzie (Feb 04 2021 at 21:59):
We rely on CSS auto-magic to determine the trailing part of the section numbers (the part you'd most care about searching for). I don't know why browsers don't make it searchable - or if there's something else we could do with the Javascript that would make it searchable. We rely on Javascript because there's no easy way to inject the section numbers into markdown-authored content via a transformation process. If anyone has ideas on how we can/should do this better, feel free to propose.
Carl Anderson (Feb 04 2021 at 22:08):
Ug. Looks like CSS-generated values are pseudo-elements, and therefore not searchable.
https://stackoverflow.com/questions/13296789/is-it-possible-to-make-css-generated-content-searchable-by-a-browser
If we wanted the same section numbers and for them to be searchable, they would need to be real elements in the DOM (I think).
Lloyd McKenzie (Feb 04 2021 at 22:49):
Ok - would it be possible to generate 'real' elements with Javascript - given that we don't have a good way of injecting them in the source?
Carl Anderson (Feb 04 2021 at 22:55):
I think it's possible, but it changes the resulting documents. As it is now - if you select all in an IG, it does not include the section numbers. I believe if we added them to the document - it would.
Carl Anderson (Feb 04 2021 at 22:57):
Perhaps a compromise would be a TOC that included the section numbers in a searchable way. Then a Ctrl-F search would match that, and you could click through the TOC link to the desired section.
Grahame Grieve (Feb 04 2021 at 23:19):
I don't understand why section numbers are not searchable. I inject them as standard text elements
Eric Haas (Feb 04 2021 at 23:47):
They are css pseudo elements
Josh Mandel (Feb 04 2021 at 23:51):
In the FHIR Core they're real; in IGs they're fake pseudo.
Grahame Grieve (Feb 04 2021 at 23:51):
where's an example
Eric Haas (Feb 04 2021 at 23:53):
We have links so why do we need to add this?
Eric Haas (Feb 04 2021 at 23:53):
Cost benefit?
Grahame Grieve (Feb 04 2021 at 23:57):
because lots of classic standards people use section numbers to report issues rather than copying the links.
Josh Mandel (Feb 05 2021 at 01:55):
http://build.fhir.org/ig/dvci/vaccine-credential-ig/branches/main/ is an example (I think all IGs are an example). ctrl-f on that page in Chromium and type "1.1"; you get no hits. At least, I get no hits.
Grahame Grieve (Feb 05 2021 at 02:08):
I didn't realise the template had taken over the section numbering. @Lloyd McKenzie how does it work? How does the section numbering be unique across pages?
Lloyd McKenzie (Feb 05 2021 at 03:11):
The section number prefix for each page is in a data file that Jeckyl sticks into a variable accessible to the Javascript.
Grahame Grieve (Feb 05 2021 at 03:14):
sigh. well, can the javascript add the number in such way that it's accessible?
Lloyd McKenzie (Feb 05 2021 at 03:16):
That was my question. I suspect the answer is 'yes', but I'm far from a JS expert.
Grahame Grieve (Feb 05 2021 at 03:19):
who wrote the javascript?
Lloyd McKenzie (Feb 05 2021 at 03:59):
Me - with help from Stack Overflow :)
Grahame Grieve (Feb 05 2021 at 04:03):
where is it?
Lloyd McKenzie (Feb 05 2021 at 04:12):
CSS is here: https://github.com/HL7/ig-template-base/blob/master/content/assets/css/project.css, specifically the section labeled "Common content for section numbering"
The heading-prefix is set here: https://github.com/HL7/ig-template-base/blob/master/includes/fragment-pagebegin.html
Grahame Grieve (Feb 05 2021 at 04:34):
so I believe the rule is that content added by css tricks like this won't be part of the page and can't be selected or searched
Jose Costa Teixeira (Feb 05 2021 at 11:31):
I had the same issue because I needed it in the "give feedback about this section" script.
https://chat.fhir.org/#narrow/stream/179169-javascript/topic/help.20needed.20%28newbie%29/near/206130970
Jose Costa Teixeira (Feb 05 2021 at 11:32):
Since I'm not the only one suffering from that, can we add an issue to the base template to make sure these numbers are "real"?
John Moehrke (Feb 05 2021 at 11:46):
IHE would like to control the numbering even more tightly. For us, it would be better to turn it off, as we are (today) would just encode the header numbers we want into the header text. This because our header numbering is not unique within an implementation guide, it is unique within the Technical Framework that a domain publishes. This might change, but this is what we need now.
John Moehrke (Feb 05 2021 at 11:47):
that said, sub-numbering on a page is nice... we just want to tell you what number to start on that source page.
Jose Costa Teixeira (Feb 05 2021 at 12:25):
I don't think we want to turn it off in IHE
Jose Costa Teixeira (Feb 05 2021 at 12:25):
(in the long run, I mean)
Lloyd McKenzie (Feb 05 2021 at 15:08):
Sounds like you'd want to assert a prefix that would cover the whole specification?
Jose Costa Teixeira (Feb 05 2021 at 15:30):
I think (if we compile things in the usual IHE way) it could be an offset that would differ for each IG
Jose Costa Teixeira (Feb 05 2021 at 15:32):
so that IG #2 continues where IG 1# left off
Jose Costa Teixeira (Feb 05 2021 at 15:34):
John can confirm what is the immediate need, if any -
Jose Costa Teixeira (Feb 05 2021 at 15:35):
in the long run , I prefer to have each IG with its own numbering, and the Technical Framework as a super IG that compiles everything, and where numbering could be sequential again.
Lloyd McKenzie (Feb 05 2021 at 15:42):
An offset would seem to be problematic because if you update one of the earlier guides to have more sections, you'd end up with duplicate numbers?
Jose Costa Teixeira (Feb 05 2021 at 15:50):
Yes. Would be hard to manage lifecycles with that. Maybe I get it wrong
Max Masnick (Feb 05 2021 at 17:59):
This could definitely be fixed by JavaScript, but an even better solution would be doing this somehow with static HTML (not using CSS pseudo elements). From a web standards/accessibility perspective I don't think it's good practice to inject meaningful content into a page with JavaScript...for example, publisher.jar doesn't appear to execute JavaScript when checking for broken links -- maybe not directly relevant here, but it illustrates why it's just better to not _need_ JavaScript on a page that's primarily static HTML (unless it's really the only option).
Max Masnick (Feb 05 2021 at 18:02):
For Markdown content that's processed with Jekyll it looks like this kind of thing might be possible with a plugin: https://github.com/muratayusuke/jekyll-numbered-headings
I'm pretty familiar with Jekyll but not with how the build process generates HTML so I don't know how applicable this.
Grahame Grieve (Feb 05 2021 at 19:00):
the iG publisher can prefix headings with numbers. I'm not sure why the template doesn't leverage this capability
Lloyd McKenzie (Feb 05 2021 at 19:06):
How do we trigger it?
Eric Haas (Feb 06 2021 at 01:01):
The static site generators I've looked don't come with a section numbering capability out of the box and that tells me it is not a thing we should worry about. I'd rather get rid of section numbering than cling to them so that you are forced to use the links provided.
Lloyd McKenzie (Feb 06 2021 at 03:56):
Section numbering is hugely important for human-to-human communication. People don't speak in hyperlinks...
Lloyd McKenzie (Feb 06 2021 at 03:57):
While many of us spend too much of our life on chat.fhir.org, there are phone calls and maybe even someday in-person meetings again. We need to keep section numbers.
Lloyd McKenzie (Feb 06 2021 at 03:58):
I don't really care if the functionality is "out-of-the-box" if there's a reliable, safe plugin we can use. The bigger question is whether it's going to create extra installation work for developers - that I definitely want to avoid.
John Moehrke (Feb 08 2021 at 14:10):
For IHE, for now, The numbering would be radically different in the background pages, vs technical pages such as the profile pages and the pages that give a technical context to the profiles. This is ugly, I understand that. Which anyone that has looked at an IHE "Supplement" would agree is hard to understand the header numbering. The ultimate reason is that the normative specifications are integrated into Volumes, so the header numbering used in the supplement is based on that ultimate integration. The advantage this brings is that any portion of a published specification has a header number defined that will not change as the specification matures. And a new supplement can reference another specification by deterministic header numbers. Promoting re-use of content (profiles, documents, etc) and transactions (operations, messages, etc).
John Moehrke (Feb 08 2021 at 14:11):
I have a project today (updating MHD to use IG publisher) where I need to do this.. so willing to experiment if there is a theory.
John Moehrke (Feb 08 2021 at 14:12):
I don't want to turn off header numbering, but if that is the only way to work it in the short term, than I know that will work. If I can specify the starting header level and number per markdown and profile, that would be more easy.
Last updated: Apr 12 2022 at 19:14 UTC
