Markdown updates for 3.1.1

[lornajane]

Replay of the steps from #3932 to update the markdown formatting and links for 3.1.1

(mysterious python script needed a few additions, included in a comment)

[lornajane]

Script to update anchors and rewrite all our links:

from sys import argv
from pathlib import Path
import re

# this script tries to inflect the old links, some are just missing and we need to use the title's version instead
updates = {}
updates["revision-history"] = "appendix-a-revision-history"
updates["data-type-conversion"] = "appendix-b-data-type-conversion"
updates["using-r-f-c6570-implementations"] = "appendix-c-using-rfc6570-implementations"
updates["serializing-headers-and-cookies"] = "appendix-d-serializing-headers-and-cookies"
updates["percent-encoding-and-form-media-types"] = "appendix-e-percent-encoding-and-form-media-types"
updates["document-structure"] = "openapi-description-structure"
updates["oas-object"] = "openapi-object"
updates["components-security-schemes"] = "security-scheme-object"
updates["schema-composition"] = "composition-and-inheritance-polymorphism"
updates["http-codes"] = "http-status-codes"
updates["oas-document"] = "openapi-description"
updates["rich-text"] = "rich-text-formatting"
updates["relative-references"] = "relative-references-in-urls"
updates["relative-references"] = "relative-references-in-urls"
updates["runtime-expression"] = "runtime-expressions"
updates["runtime-expression-examples"] = "examples"
updates["relative-references"] = "relative-references-in-urls"

updates["relative-references-u-r-i"] = "relative-references-in-api-description-uris" 
updates["relative-references-u-r-l"] = "relative-references-in-api-urls" 
updates["binary-data"] = "working-with-binary-data"
updates["base-vocabulary"] = "oas-base-vocabulary"



def kebab_it(c):
    if c.lower() != c: 
        return f'-{c.lower()}'
    return c

if __name__ == '__main__':
    text = Path(argv[1]).read_text()

    names = {}
    removals = {}
    for match in re.finditer(r'\n(.*)<a name="([^"]*)"', text):
        name = match.group(2)
        names[name] = ''.join([kebab_it(c) for c in name])

        # was it a heading? file it for removal
        if len(match.group(1)) and match.group(1)[0] == "#":
            removals[name] = True

    for current, replacement in names.items():
        if replacement in updates:
            replacement = updates[replacement]
        text = text.replace(f'(#{current})', f'(#{replacement})')

        # only remove if removal is indicated, otherwise update
        if current in removals:
            text = text.replace(f'<a name="{current}"></a>', '')
        else:
            text = text.replace(f'<a name="{current}"></a>', f'<a name="{replacement}"></a>')
            

    print(text)

[mikekistler]

Looks good. 👍