Update GLFM docs for official specification vs internal extensions
What does this MR do and why?
Related: Tracking Issue: Implement GLFM scripts per the ... (#361241 - closed)
Updates documentation to distinguish between the GLFM official specification and GLFM internal extensions. This is a follow-up to plans outlined in these threads:
Summary of changes:
-
glfm_canonical_examples.txt
is being deprecated and replaced withglfm_official_specification_examples.md
andglfm_internal_extension_examples.md
. - The examples in
glfm_internal_extension_examples.md
will no longer allow canonical HTML to be included in the markdown examples - the HTML section will be blank (glfm_official_specification_examples.md
will still require canonical HTML in all examples). The reasoning is explained in detail in the doc changes, but the summary is that...:- There's no use for it, because none of the automated scripts or testing use it
- ...which means in addition to being useless, it's prone to becoming outdated or incorrect as the actual implementation changes
- It has already caused confusion in situations where we are forced to unnecessarily write it for examples where it may not make sense.
NOTE: The changes described in this documentation have not yet been implemented. The plan is to first get feedback on the direction described here, iterating on any changes in terminology/approach as necessary, then implement once we have a consensus.
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.
Edited by Chad Woolley
Merge request reports
Activity
Please register or sign in to reply