Editorial: add newlines to improve conversion to HTML

[annevk]

Hopefully helps with whatwg/whatwg.org#255.

[domenic]

Should not merge until we have an opportunity to verify this actually works. (And/or we might change the conversion script to fix this, since this should not be required.)

[annevk]

I think the newlines before lists might be required by Markdown? Not sure though.

[domenic]

Not in CommonMark, at least

[othermaciej]

What effect do these newlines have on the conversion?

[annevk]

I'm not sure, but I'd hope, e.g., the list in https://whatwg.org/ipr-policy#26-patent-licensing-obligation is actually a list rather than rendered fully inline. A lot of the others I did for some more internal consistency, though I noticed I forgot at least one near the end.

[annevk]

Here's the output diff, I think this is clearly something we should do now:

diff --git a/whatwg.org/ipr-policy b/whatwg.org/ipr-policy
index 4f1a97033..3544566f6 100644
--- a/whatwg.org/ipr-policy
+++ b/whatwg.org/ipr-policy
@@ -51,12 +51,8 @@
 <h5 id="223-the-following-are-expressly-excluded-from-and-shall-not-be-deemed-to-constitute-essential-patent-claims">2.2.3. The following are expressly excluded from and shall not be deemed to constitute Essential Patent Claims:<a class="self-link" href="#223-the-following-are-expressly-excluded-from-and-shall-not-be-deemed-to-constitute-essential-patent-claims"></a></h5>
 
 <ol>
-<li>
-<p>any claims other than as set forth in "<a href="ipr-policy#221-essential-contribution-claims">Essential Contribution Claims</a>" or "<a href="ipr-policy#222-essential-review-draft-claims">Essential Review Draft Claims</a>" even if contained in the same patent as <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a>; and</p>
-</li>
-<li>
-<p>claims which would be infringed only by:</p>
-<ol>
+<li>any claims other than as set forth in "<a href="ipr-policy#221-essential-contribution-claims">Essential Contribution Claims</a>" or "<a href="ipr-policy#222-essential-review-draft-claims">Essential Review Draft Claims</a>" even if contained in the same patent as <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a>; and</li>
+<li>claims which would be infringed only by:<ol>
 <li>portions of an implementation that are not specified in the <a href="ipr-policy#24-normative">Normative</a> portions of the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a>, or</li>
 <li>enabling technologies that may be necessary to make or use any product or portion thereof that complies with the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a> and are not themselves expressly set forth in the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a> (e.g., semiconductor manufacturing technology, compiler technology, object-oriented technology, basic operating system technology, and the like); or</li>
 <li>the implementation of technology developed elsewhere and merely incorporated by reference in the body of the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a>; and</li>
@@ -75,15 +71,17 @@
 <p>"Patent Exclusion Period" means the 45-<a href="ipr-policy#29-day">Day</a> period during which a <a href="workstream-policy#workstream-participant">Workstream Participant</a> may exclude patents from the royalty-free <a href="ipr-policy#26-patent-licensing-obligation">Patent-Licensing Obligations</a>, as more fully set forth in <a href="#55-patent-exclusions">Section 5.5. Patent Exclusions</a>.</p>
 <h4 id="26-patent-licensing-obligation">2.6. "Patent Licensing Obligation"<a class="self-link" href="#26-patent-licensing-obligation"></a></h4>
 
-<p>"Patent-Licensing Obligation" under <a href="ipr-policy">this Policy</a> (including both the "<a href="#52-contribution-licensing-obligations">Contribution Licensing Obligation</a>" and "<a href="#53-review-draft-licensing-obligations">Review Draft Licensing Obligations</a>" referred to in <a href="#5-patents">Article 5. Patents</a>) in this <a href="ipr-policy">IPR Policy</a>) means a non-assignable, non-sublicensable license to the licensor's <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a> to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a> that:
-1. are available to all, worldwide;
-2. extend to all <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a> owned or controlled by the licensor;
-3. may be limited to implementations of the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a>, and to what is required by the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a>;
-4. may be conditioned on a grant of a reciprocal royalty-free license to all <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a> owned or controlled by the licensee. A reciprocal license may be required to be available to all, and a reciprocal license may itself be conditioned on a further reciprocal license from all;
-5. may not be conditioned on payment of royalties, fees, or other consideration;
-6. may be suspended, as to a particular WHATWG <a href="workstream-policy#living-standard">Living Standard</a>, with respect to any licensee when licensor is sued by licensee for infringement of claims essential to implement that WHATWG <a href="workstream-policy#living-standard">Living Standard</a>;
-7. may not impose any further conditions or restrictions on the use of any technology, intellectual property rights, or other restrictions on behavior of the licensee, but may include reasonable, customary terms relating to operation or maintenance of the license relationship such as the following: choice of law and dispute resolution;
-8. shall not be considered accepted by an implementer who manifests an intent not to accept the terms of the above-referenced license as offered by the licensor.</p>
+<p>"Patent-Licensing Obligation" under <a href="ipr-policy">this Policy</a> (including both the "<a href="#52-contribution-licensing-obligations">Contribution Licensing Obligation</a>" and "<a href="#53-review-draft-licensing-obligations">Review Draft Licensing Obligations</a>" referred to in <a href="#5-patents">Article 5. Patents</a>) in this <a href="ipr-policy">IPR Policy</a>) means a non-assignable, non-sublicensable license to the licensor's <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a> to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a> that:</p>
+<ol>
+<li>are available to all, worldwide;</li>
+<li>extend to all <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a> owned or controlled by the licensor;</li>
+<li>may be limited to implementations of the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a>, and to what is required by the <a href="workstream-policy#living-standard">Living Standard</a> or <a href="workstream-policy#review-draft">Review Draft</a>;</li>
+<li>may be conditioned on a grant of a reciprocal royalty-free license to all <a href="ipr-policy#22-essential-patent-claims">Essential Patent Claims</a> owned or controlled by the licensee. A reciprocal license may be required to be available to all, and a reciprocal license may itself be conditioned on a further reciprocal license from all;</li>
+<li>may not be conditioned on payment of royalties, fees, or other consideration;</li>
+<li>may be suspended, as to a particular WHATWG <a href="workstream-policy#living-standard">Living Standard</a>, with respect to any licensee when licensor is sued by licensee for infringement of claims essential to implement that WHATWG <a href="workstream-policy#living-standard">Living Standard</a>;</li>
+<li>may not impose any further conditions or restrictions on the use of any technology, intellectual property rights, or other restrictions on behavior of the licensee, but may include reasonable, customary terms relating to operation or maintenance of the license relationship such as the following: choice of law and dispute resolution;</li>
+<li>shall not be considered accepted by an implementer who manifests an intent not to accept the terms of the above-referenced license as offered by the licensor.</li>
+</ol>
 <h4 id="27-patent-exclusion-notice">2.7. "Patent Exclusion Notice"<a class="self-link" href="#27-patent-exclusion-notice"></a></h4>
 
 <p>"Patent Exclusion Notice" means a communication that complies with the requirements of <a href="#553">Section 5.5.3.</a> below.</p>
@@ -91,11 +89,13 @@
 
 <h5 id="281">2.8.1.<a class="self-link" href="#281"></a></h5>
 
-<p>The license conforming to the requirements in <a href="ipr-policy">this Policy</a> shall be made available by the licensor as long as the <a href="workstream-policy#living-standard">Living Standard</a> has not been depublished by the WHATWG. The term of such license shall be for the life of the patents in question, subject to the limitations of <a href="#283">Subsection 2.8.3.</a>, below.
+<p>The license conforming to the requirements in <a href="ipr-policy">this Policy</a> shall be made available by the licensor as long as the <a href="workstream-policy#living-standard">Living Standard</a> has not been depublished by the WHATWG. The term of such license shall be for the life of the patents in question, subject to the limitations of <a href="#283">Subsection 2.8.3.</a>, below.</p>
 <h5 id="282">2.8.2.<a class="self-link" href="#282"></a></h5>
-Subject to the suspension right in <a href="ipr-policy#26-patent-licensing-obligation">Section 2.6. Patent Licensing Obligation</a>, upon the licensee's request, licenses granted must be retroactive to the effective dates of the obligations set forth in Sections <a href="#52-contribution-licensing-obligations">5.2. Contribution Licensing Obligations</a> and <a href="#53-review-draft-licensing-obligations">5.3. Review Draft Licensing Obligations</a>, as applicable.
+
+<p>Subject to the suspension right in <a href="ipr-policy#26-patent-licensing-obligation">Section 2.6. Patent Licensing Obligation</a>, upon the licensee's request, licenses granted must be retroactive to the effective dates of the obligations set forth in Sections <a href="#52-contribution-licensing-obligations">5.2. Contribution Licensing Obligations</a> and <a href="#53-review-draft-licensing-obligations">5.3. Review Draft Licensing Obligations</a>, as applicable.</p>
 <h5 id="283">2.8.3.<a class="self-link" href="#283"></a></h5>
-If the <a href="workstream-policy#living-standard">Living Standard</a> is depublished by the WHATWG, then no new licenses need be granted but any licenses granted before the <a href="workstream-policy#living-standard">Living Standard</a> was depublished shall remain in effect.</p>
+
+<p>If the <a href="workstream-policy#living-standard">Living Standard</a> is depublished by the WHATWG, then no new licenses need be granted but any licenses granted before the <a href="workstream-policy#living-standard">Living Standard</a> was depublished shall remain in effect.</p>
 <h4 id="29-day">2.9. Day<a class="self-link" href="#29-day"></a></h4>
 
 <p>"Day" means 24 hours, commencing upon execution of a specific act, and is calculated without reference to time zones. To avoid confusion, Universal Coordinated Time is used.</p>
@@ -143,28 +143,36 @@ If the <a href="workstream-policy#living-standard">Living Standard</a> is depubl
 
 <h5 id="551">5.5.1.<a class="self-link" href="#551"></a></h5>
 
-<p>A <a href="workstream-policy#workstream-participant">Workstream Participant</a> may exclude <a href="#22-essential-patent-claims">Essential Patent Claims</a> from the <a href="#53-review-draft-licensing-obligations">Review Draft Licensing Obligations</a> by providing a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a> to the <a href="workstream-policy#editor">Workstream</a> and the <a href="sg-agreement#steering-group">Steering Group</a> within the <a href="ipr-policy#25-patent-exclusion-period">Patent Exclusion Period</a>. (A <a href="workstream-policy#workstream-participant">Workstream Participant</a> may file a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a> and continue to participate in the <a href="workstream-policy#workstream">Workstream</a>.)
+<p>A <a href="workstream-policy#workstream-participant">Workstream Participant</a> may exclude <a href="#22-essential-patent-claims">Essential Patent Claims</a> from the <a href="#53-review-draft-licensing-obligations">Review Draft Licensing Obligations</a> by providing a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a> to the <a href="workstream-policy#editor">Workstream</a> and the <a href="sg-agreement#steering-group">Steering Group</a> within the <a href="ipr-policy#25-patent-exclusion-period">Patent Exclusion Period</a>. (A <a href="workstream-policy#workstream-participant">Workstream Participant</a> may file a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a> and continue to participate in the <a href="workstream-policy#workstream">Workstream</a>.)</p>
 <h5 id="552">5.5.2.<a class="self-link" href="#552"></a></h5>
-For <a href="workstream-policy#workstream-participant">Workstream Participants</a> that continue their participation through successive <a href="workstream-policy#review-draft">Review Drafts</a>, the scope of the patent-exclusion opportunity extends only material that could not have been the subject of an exclusion by that <a href="workstream-policy#workstream-participant">Workstream Participant</a> with respect to a preceding <a href="workstream-policy#review-draft">Review Draft</a> (i.e., material that is new or has been modified such that it creates the potential for infringement not present in any previous <a href="workstream-policy#review-draft">Review Draft</a> the <a href="workstream-policy#workstream-participant">Workstream Participant</a> could have excluded against).
+
+<p>For <a href="workstream-policy#workstream-participant">Workstream Participants</a> that continue their participation through successive <a href="workstream-policy#review-draft">Review Drafts</a>, the scope of the patent-exclusion opportunity extends only material that could not have been the subject of an exclusion by that <a href="workstream-policy#workstream-participant">Workstream Participant</a> with respect to a preceding <a href="workstream-policy#review-draft">Review Draft</a> (i.e., material that is new or has been modified such that it creates the potential for infringement not present in any previous <a href="workstream-policy#review-draft">Review Draft</a> the <a href="workstream-policy#workstream-participant">Workstream Participant</a> could have excluded against).</p>
 <h5 id="553">5.5.3.<a class="self-link" href="#553"></a></h5>
-To be effective, a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a> must (1) be delivered to the <a href="workstream-policy#editor">Workstream</a> and the designated <a href="sg-agreement#steering-group">Steering Group</a> contact within the 45-<a href="ipr-policy#29-day">Day</a> period from publication of the <a href="workstream-policy#review-draft">Review Draft</a>, (2) provide the patent or publication number (for published applications) or application number (for unpublished applications) of the patent to be excluded, and (3) identify the relevant sections of the <a href="workstream-policy#review-draft">Review Draft</a> that would infringe the excluded patent with sufficient specificity that the <a href="workstream-policy#editor">Editor</a> can tag those elements as being the subject of a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a>. It may also briefly summarize the patent claims.
+
+<p>To be effective, a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a> must (1) be delivered to the <a href="workstream-policy#editor">Workstream</a> and the designated <a href="sg-agreement#steering-group">Steering Group</a> contact within the 45-<a href="ipr-policy#29-day">Day</a> period from publication of the <a href="workstream-policy#review-draft">Review Draft</a>, (2) provide the patent or publication number (for published applications) or application number (for unpublished applications) of the patent to be excluded, and (3) identify the relevant sections of the <a href="workstream-policy#review-draft">Review Draft</a> that would infringe the excluded patent with sufficient specificity that the <a href="workstream-policy#editor">Editor</a> can tag those elements as being the subject of a <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notice</a>. It may also briefly summarize the patent claims.</p>
 <h5 id="554">5.5.4.<a class="self-link" href="#554"></a></h5>
-<a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notices</a> will be made available promptly by the <a href="sg-agreement#steering-group">Steering Group</a> or the <a href="workstream-policy#editor">Editor</a> to all <a href="workstream-policy#workstream-participant">Workstream Participants</a> for internal review only, and may be published by the <a href="sg-agreement#steering-group">Steering Group</a> for review by the general public after seven <a href="ipr-policy#29-day">Days</a>' notice to the excluding party.
+
+<p><a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notices</a> will be made available promptly by the <a href="sg-agreement#steering-group">Steering Group</a> or the <a href="workstream-policy#editor">Editor</a> to all <a href="workstream-policy#workstream-participant">Workstream Participants</a> for internal review only, and may be published by the <a href="sg-agreement#steering-group">Steering Group</a> for review by the general public after seven <a href="ipr-policy#29-day">Days</a>' notice to the excluding party.</p>
 <h5 id="555">5.5.5.<a class="self-link" href="#555"></a></h5>
-<a href="#23-excluded-claim">Excluded Claims</a> may be addressed by technical workaround, posting of the exclusion notice, or other means the <a href="sg-agreement#steering-group">Steering Group</a> deems appropriate (including the retention of counsel or advisors to prepare a private advisory memo). The <a href="sg-agreement#steering-group">Steering Group</a> may take these actions directly, appoint a group of advisors to make a recommendation, or delegate the decision. Decisions that affect the <a href="workstream-policy#workstream">Workstream</a> will be published.
+
+<p><a href="#23-excluded-claim">Excluded Claims</a> may be addressed by technical workaround, posting of the exclusion notice, or other means the <a href="sg-agreement#steering-group">Steering Group</a> deems appropriate (including the retention of counsel or advisors to prepare a private advisory memo). The <a href="sg-agreement#steering-group">Steering Group</a> may take these actions directly, appoint a group of advisors to make a recommendation, or delegate the decision. Decisions that affect the <a href="workstream-policy#workstream">Workstream</a> will be published.</p>
 <h5 id="556">5.5.6.<a class="self-link" href="#556"></a></h5>
-The <a href="sg-agreement#steering-group">Steering Group</a> will establish a location that lists all <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notices</a>. The location will be available even if there are currently no <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notices</a>. This location must include the text: "The WHATWG takes no position on the essentiality of any patent claim or the validity of any exclusion notice."
+
+<p>The <a href="sg-agreement#steering-group">Steering Group</a> will establish a location that lists all <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notices</a>. The location will be available even if there are currently no <a href="ipr-policy#27-patent-exclusion-notice">Patent Exclusion Notices</a>. This location must include the text: "The WHATWG takes no position on the essentiality of any patent claim or the validity of any exclusion notice."</p>
 <h5 id="557">5.5.7.<a class="self-link" href="#557"></a></h5>
-Except as set forth above regarding new <a href="workstream-policy#workstream-participant">Workstream Participants</a>, <a href="workstream-policy#review-draft">Review Drafts</a> published prior to <a href="workstream-policy#workstream">Workstream</a> participation are not subject to the exclusion opportunity (nor, by extension to the commitment obligations); once incurred, however, <a href="ipr-policy#26-patent-licensing-obligation">Patent-Licensing Obligations</a> are cumulative and may not be withdrawn.</p>
+
+<p>Except as set forth above regarding new <a href="workstream-policy#workstream-participant">Workstream Participants</a>, <a href="workstream-policy#review-draft">Review Drafts</a> published prior to <a href="workstream-policy#workstream">Workstream</a> participation are not subject to the exclusion opportunity (nor, by extension to the commitment obligations); once incurred, however, <a href="ipr-policy#26-patent-licensing-obligation">Patent-Licensing Obligations</a> are cumulative and may not be withdrawn.</p>
 <h4 id="56-patent-disclosures">5.6. Patent disclosures<a class="self-link" href="#56-patent-disclosures"></a></h4>
 
 <h5 id="561-disclosures-regarding-contributions">5.6.1. Disclosures regarding contributions<a class="self-link" href="#561-disclosures-regarding-contributions"></a></h5>
 
-<p>When making a <a href="ipr-policy#21-contribution">Contribution</a> or as soon as feasible thereafter, the individuals who submit the <a href="ipr-policy#21-contribution">Contribution</a> (i.e., either an <a href="ipr-policy#contributor">Individual</a><a href="ipr-policy#contributor">contributor</a> or the representatives of an <a href="https://participate.whatwg.org/agreement#entity">Entity</a>) must identify any patent that they (1) are personally aware of and (2) believe would be infringed by use or implementation of the <a href="ipr-policy#21-contribution">Contribution</a>, unless the <a href="ipr-policy#contributor">Contributor</a> is making the claims subject to the <a href="ipr-policy#26-patent-licensing-obligation">Patent-Licensing Obligations</a>. (For the avoidance of doubt: No patent search is required.)
+<p>When making a <a href="ipr-policy#21-contribution">Contribution</a> or as soon as feasible thereafter, the individuals who submit the <a href="ipr-policy#21-contribution">Contribution</a> (i.e., either an <a href="ipr-policy#contributor">Individual</a><a href="ipr-policy#contributor">contributor</a> or the representatives of an <a href="https://participate.whatwg.org/agreement#entity">Entity</a>) must identify any patent that they (1) are personally aware of and (2) believe would be infringed by use or implementation of the <a href="ipr-policy#21-contribution">Contribution</a>, unless the <a href="ipr-policy#contributor">Contributor</a> is making the claims subject to the <a href="ipr-policy#26-patent-licensing-obligation">Patent-Licensing Obligations</a>. (For the avoidance of doubt: No patent search is required.)</p>
 <h5 id="562-disclosures-regarding-excluded-claims">5.6.2. Disclosures regarding excluded claims<a class="self-link" href="#562-disclosures-regarding-excluded-claims"></a></h5>
-Patent claims excluded in accordance with the provisions for "<a href="#55-patent-exclusions">Patent Exclusions</a>" above must include the information set forth in <a href="#553">Section 5.5.3.</a>
+
+<p>Patent claims excluded in accordance with the provisions for "<a href="#55-patent-exclusions">Patent Exclusions</a>" above must include the information set forth in <a href="#553">Section 5.5.3.</a></p>
 <h5 id="563-voluntary-disclosures">5.6.3. Voluntary disclosures<a class="self-link" href="#563-voluntary-disclosures"></a></h5>
-Any person may, at their sole option, identify patent claims (including third-party patents) that they believe are Essential Claims with respect to a particular <a href="workstream-policy#living-standard">Living Standard</a>.</p>
+
+<p>Any person may, at their sole option, identify patent claims (including third-party patents) that they believe are Essential Claims with respect to a particular <a href="workstream-policy#living-standard">Living Standard</a>.</p>
 <h3 id="6-trademarks">6. Trademarks<a class="self-link" href="#6-trademarks"></a></h3>
 
 <p>WHATWG Standards may be identified as "the WHATWG [Standard]" so that forks can be distinguished.</p>

[domenic]

In principle I would rather switch to Commonmark so that this is not required, but you're the one actually doing the work, which is more important than my principles :).

[annevk]

Even with Commonmark if the input is

<h3>...</h3>
test

The second line will not end up wrapped in a <p>.

[domenic]

Right, but if it's

### test
test

then it will.

[annevk]

Sure, but that means the problem is mostly with our conversion script, not the flavor of Markdown.

[domenic]

Yeah, I guess what I meant was "switch our conversion script to a Markdown processor that obeys CommonMark semantics". (Which, apparently, might not be the commonmark pip package :(.)