[dfns] Add HTML prose definition when possible #1444
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implements the logic discussed in https://github.com/w3c/respec/issues/4522 For each term defined in the specification being processed, the code now looks for some element flagged with a `data-defines="#term-id"` attribute. If such an element exists, a `prose` property gets added to the definition in the `dfns` extract with the HTML contents of that element. The code applies some clean up to the HTML markup it attaches to the `prose` property: - All asides that authoring tools may add here and there get dropped - Any element that is not a simple block or inline content element gets dropped - All attributes are dropped The clean up logic may need refinement over time once we gain experience with actual definitions. Open questions include: - Should we be stricter, e.g., only allowing `<p>`, `<br>`, and very common inline elements? - Should we keep `href` attributes (with an absolute URL) for `<a>` elements? - Should we keep `title` attributes for `<abbr>` elements? - Should we keep `class` attributes for `<pre>` elements to help with syntax highlighting? - Should we keep tables? Images? There is no good mechanism in Reffy to report potential issues encountered during extraction for the time being. In the meantime, warnings get logged when the code bumps into elements that seem surprising in the context of a term definition.
Per comment for `dir`, `href`, and `lang`: #1444 (comment) The `title` attribute seems useful to keep as well for potential tooltips and expansion of abbreviations.
dontcallmedom
approved these changes
Dec 18, 2023
tidoust
added a commit
that referenced
this pull request
Dec 20, 2023
dontcallmedom
added a commit
to dontcallmedom/respec
that referenced
this pull request
Dec 21, 2023
As discussed in speced#4522 See also w3c/reffy#1444
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Implements the logic discussed in https://github.com/w3c/respec/issues/4522
Ready for review but discussion is still ongoing, so code may still need to change. For instance, the
data-definesattribute may end up taking another name. Also happy to change the name of theproseproperty in the dfns extract.For each term defined in the specification being processed, the code now looks for some element flagged with a
data-defines="#term-id"attribute. If such an element exists, aproseproperty gets added to the definition in thedfnsextract with the HTML contents of that element.The code applies some clean up to the HTML markup it attaches to the
proseproperty:The clean up logic may need refinement over time once we gain experience with actual definitions. Open questions include:
<p>,<br>, and very common inline elements?hrefattributes (with an absolute URL) for<a>elements?titleattributes for<abbr>elements?classattributes for<pre>elements to help with syntax highlighting?There is no good mechanism in Reffy to report potential issues encountered during extraction for the time being. In the meantime, warnings get logged when the code bumps into elements that seem surprising in the context of a term definition.