Closed Malvoz closed 4 years ago
@prushforth I've updated the initial comment to try to clarify the implications.
OK, let's go with this. I've not used ReSpec, but it seems that it's the way to go and there are lots of resources to help me get up to speed.
This PR change perhaps does not utilize ReSpec to it's full potential, however there are some immediate benefits, making the spec easier to maintain:
<section>
elements.There are some implications on how we should markup things so I'll give a little breakdown:
Definitions and linking:
Definitions are established using
<dfn>
, these can be concepts, e.g.<dfn>Map Markup Language</dfn>
or elements/attributes:the <dfn>map</dfn> element
. Each<dfn>
will have a unique ID generated for referencing, unless explicitly specified.When you click on a definition, a list will popup to display where that definition has been referenced in the document. This can help with finding incorrect references for example:
I think pretty much every time a definition is mentioned it should be linked to (beneficial for users who'd like to learn more about the thing). This needs more work.
All definitions will be added to an index at the bottom of the document. (In the future, we could export definitions so that other specs can reference them.)
Normative/non-normative sections:
Using ReSpec, most sections are inherently normative, unless the following classes are used:
informative
example
note
ednote
When we reference specs e.g.
[[HTML]]
, they'll either be added to the list of "Normative references" or "Informative references", depending on if they're within a normative or non-normative section.@prushforth we talked about this in https://github.com/Maps4HTML/MapML/issues/19#issuecomment-672255149 where I mentioned I had a branch with a ReSpec implementation, that branch was mostly experimental and a learning process for me. This however has commits with useful links/info, and doesn't change any content at all (except for deleting sections that ReSpec will now generate).