Markdownlint

[paulo-ferraz-oliveira]

@garazdawi, here's a rationale on the chosen configuration options:

• "MD003": ease mixing of setext and atx style
• "MD007": because it appears it's what most EPPs use
• "MD013": it's hard to get a correct number, here; at the same time code blocks can go over 100 easily
• "MD022": because of the header
• "MD024": there are some repetitions, but in different sections, this is Ok
• "MD026": this is the default without !
• "MD029": this allows writing lists as 1, 2, 3 instead of 1, 1, 1
• "MD033": because of EEP 1 (the exception to the rule)
• "MD036": it only came up in one EEP and doesn't seem very important to enforce
• "MD041": because of EEP 1's proposal of a header

[paulo-ferraz-oliveira]

Best viewed with "Hide whitespace changes" 😉

[paulo-ferraz-oliveira]

The action is not running yet, because it hasn't been merged to master.

[paulo-ferraz-oliveira]

This is probably also best viewed commit by commit, for less context switching.

[paulo-ferraz-oliveira]

If this gets accepted, I won't mind "fixing" the open pull requests that are getting updated. This is a "for the future" thing, if you will.

[paulo-ferraz-oliveira]

@garazdawi, I didn't think this would move forward actually (had no high hopes), but glad something can. So, the goal is to compare the before and after HTML and make sure it's the same?

[paulo-ferraz-oliveira]

I'm not sure why the HTML entities change with just white space changes, but I didn't dig deep into build.pl.

[paulo-ferraz-oliveira]

I am, however, making sure the HTML differences, in the now-generated files, aren't relevant, one by one.

[paulo-ferraz-oliveira]

I'm going to commit a new bunch of white space changes (basically), some for consistency within the document itself, some for fixing issues with the previous changes.

[paulo-ferraz-oliveira]

EEP 7, EEP 9 and EEP 43 contain a lot of errors.

A lot of non-valid HTML? Unreadable? I mean, I did find some "errors" but not "a lot", so I might not be looking in the correct place/at what you're looking at.

Also, I did pass my eyes over all .md and then the generated .html and nothing seemed very wrong, but I will re-generate and try to figure out if there's more stuff to change.

[paulo-ferraz-oliveira]

Here's a brief summary of the recent changes:

• some <blockquote> changes
• some <br> fixes
• some <p> fixes
• 007
  • ` in a code element
  • a two line code element move to one (was wrong)
• 008
  • a non-code element was made into one
• 009
  • several code elements fixed
• 011
  • mostly arranging white spaces/lines
• 012
  • some code fixes
• 026
  • some code fixes
• 029
  • small code fix
• 040
  • (previous) code turned text
• 041
  • some code fixes
• 049
  • small code fix

[garazdawi]

A lot of non-valid HTML? Unreadable? I mean, I did find some "errors" but not "a lot", so I might not be looking in the correct place/at what you're looking at.

No, not invalid HTML. Places where the removal/addition of whitespace changed the content. What I mostly saw was code examples that became incorrectly indented after the fixes, which it seems like you have caught in your review.

My definition of "a lot" was "more than I can feel like going through on a Friday evening", which to be honest was not really all that many :)

Would you mind rebasing on top of latest master? I'll take a look through your changes once that is done and see if I can find any other places that look odd.

[paulo-ferraz-oliveira]

I'll keep this on my TO-DO list (might be done in the next 5 min.s or the next 5 days, not sure when I'll have time - or how long it'll take 😄).

[paulo-ferraz-oliveira]

First bit is done. That was easier then I though. I'm now going over all merges to master to make sure I didn't skip anything wrongly.

Notes:

• 0007.md: changed High-level API to [#high-level-api](High-level API) (inner link)
• 0009.md: some changes to make code look code on .md (maybe HTML needs to be closely looked at)

Some other (hopefully) small changes were done. I'm going to look at the .mds on GitHub now.

[paulo-ferraz-oliveira]

I'm moving away from draft. The new relevant commit is 200c4e5. I tried to make sure all changes look good in HTML and Markdown, but it's not easy to appease both at the same time 😢. For HTML, I did the minimum required to make it look readable. This introduced some whitespace in the .mds' visual output, but it might be Ok.

[garazdawi]

• 0007.md: changed High-level API to [#high-level-api](High-level API) (inner link)

Markdown.pl does not support inner links, so this will turn into a dead anchor in the final HTML... which is not what we want I think.

[paulo-ferraz-oliveira]

It looks a lot better now. I added two commits that fixes two issues that I found.

I saw, thanks.

[paulo-ferraz-oliveira]

I think this may be ready to merge. I'll run another pass through everything tomorrow and see if I catch anything. Also, just so that you are aware, my plan is for us to move from using Markdown.pl to https://commonmark.org/ as the specification for how EEPs are rendered.

That's good, I hope. As long as it's more modern. If you tell me the plan, though, I may try to tackle it. Is it Perl? Or do you have something different in mind?

[paulo-ferraz-oliveira]

Markdown.pl does not support inner links, so this will turn into a dead anchor in the final HTML... which is not what we want I think.

Yeah, sorry, I didn't catch ALL of it, it's a lot of stuff. In any case, yeah, what looks good in .md might not in .html` (is there a real interest in maintaining the HTML version? I'm convinced that some of what's already in the repo. was never reviewed as HTML 😄).

[paulo-ferraz-oliveira]

• 0007.md: changed High-level API to [#high-level-api](High-level API) (inner link)

Markdown.pl does not support inner links, so this will turn into a dead anchor in the final HTML... which is not what we want I think.

I'll revert this change.

[garazdawi]

That's good, I hope. As long as it's more modern. If you tell me the plan, though, I may try to tackle it. Is it Perl? Or do you have something different in mind?

I haven't really gotten as far as having a plan yet :) just a goal!

The commonmark reference implementation is in C if I recall correctly, but there are implementations of it in python and js.

Yeah, sorry, I didn't catch ALL of it, it's a lot of stuff. In any case, yeah, what looks good in .md might not in .html` (is there a real interest in maintaining the HTML version? I'm convinced that some of what's already in the repo. was never reviewed as HTML smile)

When you say "what looks good in .md", you probably really mean "what looks good in github flavored markdown".

The ./build.pl version is the way that the EEP spec defines that the markdown should be rendered. So the way that github renders the markdown is (right now) not as important as how the ./build.pl HTML looks like. If we move to commonmark the difference will be smaller, but there will still be a difference https://github.github.com/gfm/#what-is-github-flavored-markdown-

[paulo-ferraz-oliveira]

When you say "what looks good in .md", you probably really mean "what looks good in github flavored markdown".

I do. I supposed I thought (probably wrongly) that the target was this, since this is where EEPs are being stored. But it is HTML 👍

[paulo-ferraz-oliveira]

I've reverted all the whitespace changes that might be relevant. I'll point out those that might not, though, since some of them might've been there by mistake to start with (I'm not sure of the original author's motivation).

[garazdawi]

I've reverted all the whitespace changes that might be relevant. I'll point out those that might not, though, since some of them might've been there by mistake to start with (I'm not sure of the original author's motivation).

When viewing your revert using the github GUI it does a very good job at highlighting the places where trailing whitespace can be removed, while not showing anything for where they are significant.

[garazdawi]

I'll take a last look at this tomorrow and then should be ready to merge.

[paulo-ferraz-oliveira]

I'm happy with the changes. Thanks for going through this so thoroughly.

[garazdawi]

All done! Thanks!