Markdown to HTML issues for OSLC-OP Specs

[jamsden]

• [x] Level 1 headings are followed by a horizontal rule that may not be acceptable to OASIS (it is)
• [x] Need to have some means of indicating conformance text, possibly ... is sufficient
• [x] Need a way to add example text that formats properly for OASIS, possibly can be added between example text or embedded in:

  This is 
  a multi-line
  example

• [ ] Probably should add more variables in the template.html for the respecConfig variables that are going to be regularly updated
• [x] Need some means of denoting normative and non-normative content

[berezovskyi]

Level 1 headings are followed by a horizontal rule that may not be acceptable to OASIS

https://oslc-op.github.io/oslc-specs/specs/core/oslc-core.html#motivation has those hr's!

Otherwise:

1. Removing the --section-divs from the command would use bare h1 for level one headings, instead of also using <section>. ReSpec hr's each section. You will lose nice TOC if you do this!
2. Replace the hr {} CSS rule in the header with this:

     @media only screen {
       hr {
         display: none;
       }
     }

[berezovskyi]

Need a way to add example text that formats properly for OASIS, possibly can be added between example text or embedded in

Add this bit of CSS in the HEAD:

      body#respecDocument pre,
      body#respecDocument code {
        color: black;
        font-family: ui-monospace, Menlo, Monaco, "Cascadia Mono", "Segoe UI Mono", "Roboto Mono", "Oxygen Mono",
          "Ubuntu Monospace", "Source Code Pro", "Fira Mono", "Droid Sans Mono", "Courier New", monospace;
        font-weight: 400;
      }

This will reset a red bold typewriter font to the normal black best mono font that is installed by default on mac, win, linux. Better yet, this one:

      body#respecDocument pre,
      body#respecDocument code {
        color: black;
        font-family: ui-monospace, Menlo, Monaco, "Cascadia Mono", "Segoe UI Mono", "Roboto Mono", "Oxygen Mono",
          "Ubuntu Monospace", "Source Code Pro", "Fira Mono", "Droid Sans Mono", "Courier New", monospace;
        font-weight: 400;
      }

      @media only screen {
        body#respecDocument pre {
          background: hsl(84, 7%, 95%);
          padding: 10px 20px 10px 20px;
          /* margin: 0 20px; */
          border-radius: 5px;
        }
      }

It will give you this look:

[berezovskyi]

Need to have some means of indicating conformance text, possibly ... is sufficient

Use the following config:

        conformanceLabelPrefix: "OLP",
        // noConformanceStyling: 1,
        // noConformanceTable: 1,
        // conformanceClauseStrength: 1,

Insert an empty conformance section like this:

    $body$
    <section id="conformance"></section>
    <section class="appendix">

Mark up text with a span:

Let's start with some normative text. <span class="conformance">OSLC Services **MUST** support at least one RDF resource serialization format, and should support as many serialization formats as possible through content negotiation.</span>

Result:

plus

[berezovskyi]

Need some means of denoting normative and non-normative content

All content is normative in a spec by default. Add an informative CSS class to the section to change it, e.g.

# OSLC Link Discovery service {.informative}

to get