CIPs: Ensure header and templated section correctness

[Ryun1]

While working on #989
I have applied validations to existing CIPs
and found some existing inconsistencies

I may do follow up PRs with more fixes, while refining #989
but due to the amount of changes I think it is best to split across multiple PRs
so, starting with this one

(I will also do a follow up PR with CPS fixes)

Validation rules applied

• Required header fields: CIP, Title, Category, Status, Authors, Implementors, Discussions, Created, License
• Required sections: Abstract, Motivation: why is this CIP necessary?, Specification, Rationale: how does this CIP achieve its goals?, Path to Active, Copyright
• Path to Active must have: Acceptance Criteria, Implementation Plan (as H3 subsections)

Validation rule choices made

• Allowed optional use of solution-to in CIP headers
  • maybe we should just add this to the template and CIP-01?
• Enforced capitalisation consistency of templated sections

[rphair]

@Ryun1 this is great; you've caught many things intended for the scope of

• #389

in which I think I did some things more effectively in bulk, but also would have missed some things from repetitive motion fatigue.

Last time I also obviously missed a good opportunity to do greps across all CIPs, covering common elements of front matter & standard headers... as things progress here, I'll cook up & post something like that so we can double-check for completeness this time.

We've not yet enforced any capitalisation rules for document headers, and one or two things in CIP-0001 & resulting templates are actually incorrect. Use Cases and Path to Active as major titles are definitely correct as all-caps.

I think the correct spelling of our "long titles" for Motivation and Rationale is now ready to address... as the first word of a subtitle, the words How and Why should be capitalised: which means the uncapitalised versions quoted as errors here are right, and all the others are wrong. 😅

• I pointed this out during the first major update to CIP-0001 but was overruled & now we can certainly ensure that everybody is in agreement before deciding in which direction to standardise all such items (and then also update CIP 1, the templates & your new validation scripts)...

[Ryun1]

as the first word of a subtitle, the words How and Why should be capitalised: which means the uncapitalised versions quoted as errors here are right, and all the others are wrong.

I agree with this!
ill update my PR with this fix included

[perturbing]

Are there any tools to check for dead links? This might be a nice validation rule :)

[Ryun1]

Are there any tools to check for dead links? This might be a nice validation rule :)

100% we will add this too @perturbing

[rphair]

thanks again @Ryun1 - template updates look good & all text heading changes look fine on eyeball review. I'll clone this branch soon (likely tomorrow) to run some text filters locally and see if I can catch any wayward mistakes before approving & getting you a baseline to use in #989 ASAP.

[rphair]

OK @Ryun1 I would be ready to approve this after:

• the 2 CIPs with DOS-style line endings are normalised to UNIX line endings: since if using standard UNIX text filtering your new scripts would likely be thrown off as well;
• we settle whether to include CPS along with CIP in this PR — which I think would be timely, appropriate & useful — and fix the CPSs if so.

Here's how I've checked it so far (all anomalies have been fixed in the last round of commits above):

---

$ git fetch upstream pull/1125/head:pr-1125-check
$ git checkout pr-1125-check
$ pwd  
/home/rphair/Documents/design/build/CIPs

Check all H1's & H2's:

egrep '^#\s\|^##\s' \*/README.md

... which shows the bulk of the information but doesn't filter it enough to be useful. This shows the outliers:

egrep -n '^#\s|^##\s' CIP-*/README.md | egrep -v 'Abstract$|Motivation: Why is this CIP necessary\?$|Specification$|Rationale: How does this CIP achieve its goals\?|Path to Active$|Versioning$|References$|Appendix$|Appendices$|Acknowledgments$|Acknowledgements$|Copyright$'

• note 2 spellings of Acknowledgements are allowable so as not to force US or UK English; likewise authors should be able to title their Appendix singular or plural
• some of these are inline code blocks or quoted Markdown & therefore OK

CIP-0005/README.md:212:## Changelog
CIP-0008/README.md:96:# if signing with \>1 key
CIP-0021/README.md:206:## Restrictions for specific hardware devices
CIP-0035/README.md:18:# Changes to Plutus Core
CIP-0035/README.md:39:## Background
CIP-0054/README.md:237:## The Smart NFT toolchain
CIP-0057/README.md:281:## Example(s)
CIP-0069/README.md:109:## Backwards compatibility
CIP-0085/README.md:655:## Copyright 
CIP-0102/README.md:161:## Extending & Modifying this CIP
CIP-0120/README.md:215:# H1
CIP-0120/README.md:217:## H2
CIP-0120/README.md:442:## Open Questions
CIP-0135/README.md:333:## Change Log

These READMEs were committed with DOS line endings somehow & therefore all headings (though canonical) appear not to end normally: @Ryun1 I would recommend recommitting them in your branch after forcing UNIX mode in a text editor or with git settings:

• CIP-0146
• CIP-0152

I didn't know if CPSs are in scope for this PR but this shows some tune-ups that can be done, including standardising all-caps for Use Cases and Open Questions (plus removing redundant boldface on some section headers):

egrep -n '^#\s|^##\s' CPS-*/README.md | egrep -v 'Abstract$|Problem$|Use Cases$|Goals$|Open Questions$|References$|Acknowledgments$|Acknowledgements$|Copyright$'

[rphair]

Looks perfect now:

$ git pull upstream pull/1125/head
... 9 files changed, 1977 insertions(+), 1975 deletions(-)
$ egrep -n '^#\s|^##\s' CIP-*/README.md | egrep -v 'Abstract$|Motivation ...
CIP-0008/README.md:96:# if signing with >1 key
CIP-0120/README.md:215:# H1
CIP-0120/README.md:217:## H2
# ... i.e. only code examples

[rphair]

@Ryun1 also noting that we should remove, before merging this, the - from Solution-To: in CIPs (currently 4), the template, and CIP-0001 unless any objection to #1128 (comment). Alternatively we might confirm how the grammatically incorrect Solution-To: is somehow more useful or meaningful than Solution To.

Actually I recall now I voted for Solves: during the grand remodel 3+ years ago but nobody liked it. @Ryun1 @perturbing what do you think if it as a (more concise) keyword today?

[rphair]

@Ryun1 @perturbing - both these related update proposals outlined & readily confirmed at the CIP meeting today. 🎉

[rphair]

@Ryun1 merge conflict FYI, with:

• CIP-0137 | Add network magic table #1127