Refactor markdown guidelines to improve space and presentation.

[SirWumpus]

#208 (comment)

@lcn2 you ask from me to "have a go" at optimising Markdown Guidelines. I think I've managed to achieve that (from 11 pages to 8, almost 7). I kept the link anchors this time, though I restructured a little so that I could view in browser; most browser/viewer plugins don't like <div>, most other tags are fine.

Most of the savings came from merging examples together and making the examples explain themselves for the most part. Also made use of Unicode check-mark and cross for good and bad respectively. Unfortunately you can't colour them green and red within code blocks, which would have been nicer.

Hope you think its an improvement. Let me know.

[lcn2]

On board train 🚊 out of Canada 🇨🇦 .. will review when "landside"

[xexyl]

UPDATE

If you wish to view my rushed comment at stupid o'clock that turned out to not be constructive then either look at edit history or the replies. The page is already too long and it is not helpful to have the comment here anyway.

[xexyl]

UPDATE

If you wish to view my rushed comment at stupid o'clock that turned out to not be constructive then either look at edit history or the replies. The page is already too long and it is not helpful to have the comment here anyway.

[xexyl]

UPDATE

If you wish to view my rushed comment at stupid o'clock that turned out to not be constructive then either look at edit history or the replies. The page is already too long and it is not helpful to have the comment here anyway.

[xexyl]

UPDATE

If you wish to view my rushed comment at stupid o'clock that turned out to not be constructive then either look at edit history or the replies. The page is already too long and it is not helpful to have the comment here anyway.

[xexyl]

UPDATE

If you wish to view my rushed comment at stupid o'clock that turned out to not be constructive then either look at edit history or the replies. The page is already too long and it is not helpful to have the comment here anyway.

[SirWumpus]

Sorry to be a pain but I see MANY issues here again. I did not look through the whole document either.

* `upto` is not a word. It is two words: up to.

Into goto upto beyond! - as never said by Buzz Lightyear. That can be fix.

* the lines are super long which although does not matter for html it does matter for markdown

I prefer viewing in an editor with line wrapping one. One physical line per paragraph. But that can be fix too.

* the ticks instead of the <== no thank you was directly discussed before: it's important to actually HAVE the no thank you. Also I wasn't even sure at first what you were trying to convey whereas <== no thank you is very clear.

Not sure how teachers grade papers these days, but ✔ and ✕ is very clear to me. I seen used in other tutorials; there used to be a Window widget/icon library that would use ✔ OK and ✕ Cancel to strong effect.

Its this IMO which makes it more clear and less wordy. Skip this one and might as well stay with what you got.

* see below for formatting issues

Can always be addressed.

* you said to use `\` instead of `<br>` - that is not correct because it'll cause, as you kept in, pandoc to create deprecated `<br />`.

Where? I took the examples and most of the text as-as. As currently seen...

Versus mine version...

What is the issue here?

* you have some html tags in all caps which is at best inconsistent

Found only one.

* ironically you kept in something you directly did in rules, the do not use `---` to create horizontal lines or sections

I thought you wanted to keep that. Happy to remove it.

The formatting issues:

<div id="del"></div>
<div id="strike"></div>
## Replace `<strike>` or `<s>`

Placing the empty <div id="anchor"></div> still works as an anchor AND doesn't mess up reading the Markdown in some viewers and as plain text.

Frankly I'd prefer using <span id="anchor"></span>, which works equally well and does not mess with browser based markdown viewers. (Right now to work on the document I have to use a regex to flip from <div> to \<div> everywhere in order to render it as I worked. Of course I remove that before submitting the PR.

Still annoying. Markdown philosophy is about reading as plain text or formatted HTML. When you have more HTML in convoluted places through out the document, you render the markdown version near useless and should just have written it straight in HTML. Or get a better (fixed) converter rather than work around pandoc failings.

Another one:

✕ ␉We   don't␉mind␉tabs␉in␉general, 

Here I am trying to emphasise where the TABs are using U+2409 ␉. How can you put tabs in a markdown document that is trying to explain why tabs are bad. I choose this with thought, not on a whim.

You have in a line:

✕ ```

.. which is incorrect. The three ` must be at the beginning of the line. That will cause a html generation error.

When you want to quote ``` within a fence pair you make the outer fence "bigger" as in ```` with a matching one on close. So the above example is trying show within the example a markdown block that is wrong and one that is correct the cross and ticks on the invalid and valid lines. Its not a formatting error. Its correct markdown and not my fault if pandoc fails to handle it correctly - it should be treating the inner ``` fence as part of the code block, not as formatting.

Another problem is this:

✕ <br/>
✕ <hr/>
✕ <img src="1984-anonymous-tattoo.jpg"
    alt="image of a tattoo of the 1984 anonymous C code"
    width=600 height=401 />

✔ <br>
✔ <hr>
✔ <img src="1984-anonymous-tattoo.jpg"
   alt="image of a tattoo of the 1984 anonymous C code"
   width=600 height=401>

No. Why. It is perfectly clear what is wrong and what is correct.

No. The problem is not that. The problem is when a parentheses is inside the [], and as for the () round the [] you invented that. That was not there before and it's not a problem.

Actually it was in the original Markdown Guidelines

In all the examples the ✕ and ✔ are in what I would call the margin, not part of the examples. I do not think this would confuse people.

I'll upload in short while a version with some spelling corrections and you long lines addressed. Then @lcn2 can consider that.

[xexyl]

Hey @SirWumpus - I only have a minute so I'll make this quick.

I just wanted to say I'm sorry about the comments if they came across as negative. I fear they did. Maybe it's just me doubting myself (I hope that) but I know that I can sometimes come across a bit too blunt even when I don't mean it. You're doing a GREAT JOB: I just wanted to point out the issues I saw. I could probably have worded it a bit better but I was also trying to get the comment in before it was merged - to save everyone time.

I hope it didn't come across badly but if it did I'm very sorry indeed. I was thinking about this when I was cleaning and now I have other things I have to do.

I haven't looked at your messages. Can do that another time if necessary. Best wishes and again I'm sorry if it came across badly! I think I personally would have taken my words badly but I hope you didn't. If you did though I hope this is better.

[xexyl]

And I see your comment does need a reply. I might have been too quick with it. Apologies! I must leave now but I'll give your comment the time it deserves. I do have some concerns yes but a lot of those are minor. The only serious one I think is the swap of the using <br> or \ at EOL: very easy to do.

Keep up the fantastic work and have a great rest of your day!

I'll try replying tomorrow. Best wishes! I replied to your question about how to generate the html files too. I hope that helps at least.

And you're also right - some of what I thought might be a problem either I misread OR pandoc did the right thing.

[xexyl]

Just replying to a few things. I then really must go. I'll give it a proper reply later. It seems like I might have been hallucinating or something - for some - and for others referring to discussions Landon and I had.

And clearly I was a pain. But in ways I did not mean to be. I should have waited until I was more awake.

* the lines are super long which although does not matter for html it does matter for markdown

I prefer viewing in an editor with line wrapping one. One physical line per paragraph. But that can be fix too.

Do you do that in vim? If so how?

* the ticks instead of the <== no thank you was directly discussed before: it's important to actually HAVE the no thank you. Also I wasn't even sure at first what you were trying to convey whereas <== no thank you is very clear.

Not sure how teachers grade papers these days, but ✔ and ✕ is very clear to me. I seen used in other tutorials; there used to be a Window widget/icon library that would use ✔ OK and ✕ Cancel to strong effect.

Its this IMO which makes it more clear and less wordy. Skip this one and might as well stay with what you got.

Well .. I tried something other than that too but Landon disagreed.

* see below for formatting issues

Can always be addressed.

Of course. I hope my comments can be too. By which I mean my tone.

* you said to use `\` instead of `<br>` - that is not correct because it'll cause, as you kept in, pandoc to create deprecated `<br />`.

I thought you swapped it? Was I hallucinating?

* you have some html tags in all caps which is at best inconsistent

Found only one.

It happens. Some of the things I have done ...

* ironically you kept in something you directly did in rules, the do not use `---` to create horizontal lines or sections

I thought you wanted to keep that. Happy to remove it.

I think there was a misunderstanding here. I am not sure now what I was getting at though. We want to not have it yes. But I meant (maybe) that you kept the guideline in but the rules do not have it. And that's easy to fix. Or not. Really only a matter of preference and consistency.

The formatting issues:

<div id="del"></div>
<div id="strike"></div>
## Replace `<strike>` or `<s>`

Placing the empty <div id="anchor"></div> still works as an anchor AND doesn't mess up reading the Markdown in some viewers and as plain text.

That's true .. we had to do that in GitHub too: just a matter of consistency.

Frankly I'd prefer using <span id="anchor"></span>, which works equally well and does not mess with browser based markdown viewers. (Right now to work on the document I have to use a regex to flip from <div> to \<div> everywhere in order to render it as I worked. Of course I remove that before submitting the PR.

Still annoying. Markdown philosophy is about reading as plain text or formatted HTML. When you have more HTML in convoluted places through out the document, you render the markdown version near useless and should just have written it straight in HTML. Or get a better (fixed) converter rather than work around pandoc failings.

I didn't choose that parser I am afraid but yes you'd like to believe the parser would not do that.

Another one:

✕ ␉We   don't␉mind␉tabs␉in␉general, 

Here I am trying to emphasise where the TABs are using U+2409 ␉. How can you put tabs in a markdown document that is trying to explain why tabs are bad. I choose this with thought, not on a whim.

I know that. I hope it wasn't taken personally. I think it might not be needed. You're right it's not really visible - how can it be shown. I guess we could have \t but that also doesn't work so well. I just wanted to point out that not everyone will understand the ht part (and some people like me can barely read it - though that's less of an issue for me).

Maybe it doesn't have to be shown? Not sure?

You have in a line:
✕ ```
.. which is incorrect. The three ` must be at the beginning of the line. That will cause a html generation error.

When you want to quote `` ``` `` within a fence pair you make the outer fence "bigger" as in `` ```` `` with a matching one on close. So the above example is trying show within the example a markdown block that is wrong and one that is correct the cross and ticks on the invalid and valid lines. Its not a formatting error. Its correct markdown and not my fault if `pandoc` fails to handle it correctly - it should be treating the inner `` ``` `` fence as part of the code block, not as formatting.

Well I looked at rendered html after the fact and it seemed okay. It looked wrong but clearly I was seeing things that were not there. Apologies!

No. The problem is not that. The problem is when a parentheses is inside the [], and as for the () round the [] you invented that. That was not there before and it's not a problem.

Actually it was in the original Markdown Guidelines

In all the examples the `✕ ` and `✔ ` are in what I would call the margin, not part of the examples. I do not think this would confuse people.

That's weird. I might have been hallucinating then! As for the issue though with x versus tick marks - it was more of the way it was how it was put in only one block.

That and the <== no thank you I believe was more explicit. I remember actually changing it to something just like you did (just not with Unicode symbols) and Landon didn't want it.

Maybe I replied to everything? I'm not sure. Please let me know and I'll give it a proper reply tomorrow.

I really need to go now. Just wanted to address some of it - feel badly about it. In the future I'll wait until I can be more focused and take a proper look.

Ultimately I think there are minor issues. It seems like I might have seen some things wrong and that's definitely my fault and not yours.

Did I cover everything? Well I'll take a look again tomorrow anyway. But I must go now.

Thanks and apologies!

[SirWumpus]

Just replying to a few things. I then really must go.

I swear you really can't resist even when in a hurry. Must be my charming turns of phrase 🎭, my little dog 🐕, or my pictures of home made pizza and bread 🍕🍞.

🤣

[SirWumpus]

I prefer viewing in an editor with line wrapping one. One physical line per paragraph. But that can be fix too.

Do you do that in vim? If so how?

I use TextPad on Windows to access files on the NetBSD VM via Samba. I also use eh (or vi).
Two possible ways, tell TextPad to line break at 72 chars when saving (not also best) or do it by hand, which I did do since it wasn't long.

I thought you swapped it? Was I hallucinating?

I think so, cause I didn't change the nature of the examples, unless they're wrong - which they didn't appear to be.

I might have been hallucinating then!

I knew it! You are an AI !

[xexyl]

Okay I have a bit more time for a better reply.

Sorry to be a pain but I see MANY issues here again. I did not look through the whole document either.

* `upto` is not a word. It is two words: up to.

Into goto upto beyond! - as never said by Buzz Lightyear. That can be fix.

Of course. Not a big deal. My eyes (or brain) just zoom in on those things. Not that some things don't slip through at times (as your comment reveals I also sometimes see things that aren't there although that's quite rare .. I hope 😀).

* the lines are super long which although does not matter for html it does matter for markdown

I prefer viewing in an editor with line wrapping one. One physical line per paragraph. But that can be fix too.

As I asked in the other comment - is it vi(m)? If so how do you get it to auto-wrap without having to join the lines (in viewing - I know how to do it when typing)? Still - it might be good to do it for others.

* the ticks instead of the <== no thank you was directly discussed before: it's important to actually HAVE the no thank you. Also I wasn't even sure at first what you were trying to convey whereas <== no thank you is very clear.

Not sure how teachers grade papers these days, but ✔ and ✕ is very clear to me. I seen used in other tutorials; there used to be a Window widget/icon library that would use ✔ OK and ✕ Cancel to strong effect.

Its this IMO which makes it more clear and less wordy. Skip this one and might as well stay with what you got.

Well as noted Landon at least at one point wanted the <== no thank you. But also as noted it was that it omitted the '.. instead use:' part which makes it a bit more obvious. Those who will ignore it will ignore it either way but separating it is useful I think (on my behalf it makes it more clear - whether or not you use the x or ticks).

* see below for formatting issues

Can always be addressed.

Yes of course.

* you said to use `\` instead of `<br>` - that is not correct because it'll cause, as you kept in, pandoc to create deprecated `<br />`.

Where? I took the examples and most of the text as-as. As currently seen...

Versus mine version...

What is the issue here?

Ahhh ... I think I see the source of the problem. One is in a code block - it's okay - but out of a code block one must do <br>.

* you have some html tags in all caps which is at best inconsistent

Found only one.

And easy to fix of course. Just wanted to point it out.

* ironically you kept in something you directly did in rules, the do not use `---` to create horizontal lines or sections

I thought you wanted to keep that. Happy to remove it.

I hope I already explained this one?

The formatting issues:

<div id="del"></div>
<div id="strike"></div>
## Replace `<strike>` or `<s>`

Placing the empty <div id="anchor"></div> still works as an anchor AND doesn't mess up reading the Markdown in some viewers and as plain text.

Well as above it's true. It MIGHT have been specific to pandoc but it appears to work just as well. But maybe for consistency it should be one way or the other. Given that other documents have the # part in between it might be better to keep it that way. But since I'm being the pedant I'm happy to fix that - if that's decided how it should be.

Frankly I'd prefer using <span id="anchor"></span>, which works equally well and does not mess with browser based markdown viewers. (Right now to work on the document I have to use a regex to flip from <div> to \<div> everywhere in order to render it as I worked. Of course I remove that before submitting the PR.

I have no idea on this one. I just know that the rest of the website relies on the div. It might be in place of certain <a> details.

Still annoying. Markdown philosophy is about reading as plain text or formatted HTML. When you have more HTML in convoluted places through out the document, you render the markdown version near useless and should just have written it straight in HTML. Or get a better (fixed) converter rather than work around pandoc failings.

On my behalf I never use markdown except for something like the IOCCC - or something on GitHub. I just do manual html. I don't like html generators usually.

Another one:

✕ ␉We   don't␉mind␉tabs␉in␉general, 

Here I am trying to emphasise where the TABs are using U+2409 ␉. How can you put tabs in a markdown document that is trying to explain why tabs are bad. I choose this with thought, not on a whim.

Well I already replied to this. It's just hard to see and not everyone will know what ht is. I don't have a good answer for this one. You're right though - it's not really possible to see otherwise. Perhaps in place of the literal tab and also the unicode symbol it could be <tab> (the actual text <tab>)? That would make it clearer and it would not be a problem for newcomers and it would not be problems for people who are blind (or mostly blind like me). Okay so blind people without a screenreader will still have a problem but ...

You have in a line:
✕ ```
.. which is incorrect. The three ` must be at the beginning of the line. That will cause a html generation error.

When you want to quote `` ``` `` within a fence pair you make the outer fence "bigger" as in `` ```` `` with a matching one on close. So the above example is trying show within the example a markdown block that is wrong and one that is correct the cross and ticks on the invalid and valid lines. It's not a formatting error. Its correct markdown and not my fault if `pandoc` fails to handle it correctly - it should be treating the inner `` ``` `` fence as part of the code block, not as formatting.

As it turns out pandoc did the right thing (or so it seems). What I was getting at though (I think - certainly in one case I was) is that the three ``` should be at the first column.

Another problem is this:

✕ <br/>
✕ <hr/>
✕ <img src="1984-anonymous-tattoo.jpg"
    alt="image of a tattoo of the 1984 anonymous C code"
    width=600 height=401 />

✔ <br>
✔ <hr>
✔ <img src="1984-anonymous-tattoo.jpg"
   alt="image of a tattoo of the 1984 anonymous C code"
   width=600 height=401>

No. Why. It is perfectly clear what is wrong and what is correct.

I already mentioned this - it's the all together. That and what Landon previously had said.

But I actually thought of an argument against it. I don't know though - this is from ignorance on my part: would a screenreader actually be able to read that? How do they deal with unicode symbols anyway? I do know in the past some people who are blind have won (at least one).

No. The problem is not that. The problem is when a parentheses is inside the [], and as for the () round the [] you invented that. That was not there before and it's not a problem.

Actually it was in the original Markdown Guidelines

I'm still baffled because I checked another copy. Weird.

In all the examples the ✕ and ✔ are in what I would call the margin, not part of the examples. I do not think this would confuse people.

I'll upload in short while a version with some spelling corrections and you long lines addressed. Then @lcn2 can consider that.

I see you replied in good fun - that's good. I hope that this comment also helps out and clarifies things too. I have a bit more time so I'll try and reply to your recent comments too.

[xexyl]

Just replying to a few things. I then really must go.

I swear you really can't resist even when in a hurry. Must be my charming turns of phrase 🎭, my little dog 🐕, or my pictures of home made pizza and bread 🍕🍞.

Well ... yeah I wrote more than I meant to. But I felt badly about my OP. Maybe there was no need to. It seems like that there was no need to. But when doing some housecleaning (and also earlier) it dawned on me that it could have come across as not so nice. I don't like that so I felt I should take more time even though I had other things to do. I'm good now although I won't be doing much more for the day. Will be off to eat soon I should think. Might do more here (at computer) for a bit after that but that remains to be seen.

But yeah .. it might be about those other things you suggest too. Who can tell? I cannot!

[xexyl]

I prefer viewing in an editor with line wrapping one. One physical line per paragraph. But that can be fix too.

Do you do that in vim? If so how?

I use TextPad on Windows to access files on the NetBSD VM via Samba. I also use eh (or vi). Two possible ways, tell TextPad to line break at 72 chars when saving (not also best) or do it by hand, which I did do since it wasn't long.

Oh that explains it. Okay. I tell vim to line break at 80 and I have many times had to join lines that were too long. But it makes sense if you use that - I could see how that would have happened.

I thought you swapped it? Was I hallucinating?

I think so, cause I didn't change the nature of the examples, unless they're wrong - which they didn't appear to be.

I think I misread it. I also forgot that there were two spots. It's okay in code blocks for instance but not otherwise.

I might have been hallucinating then!

I knew it! You are an AI !

Ah yes .. well ... I have an image I made for you on this. Will try and locate it quickly. I need to eat soon.

[xexyl]

I might have been hallucinating then!

I knew it! You are an AI !

Ah yes .. well ... I have an image I made for you on this. Will try and locate it quickly. I need to eat soon.

[SirWumpus]

As I asked in the other comment - is it vi(m)? If so how do you get it to auto-wrap without having to join the lines (in viewing - I know how to do it when typing)? Still - it might be good to do it for others.

Not sure I understand the question properly, so I might be on parallel one:

When I use vi aka nvi (BSDs version by Keith Bostic) by design vi wraps the physical line according the to screen width. Also look at :set wrapmargin which can adjust the right-hand-side. vim might have non-standard options to enable/disable the default behaviour so lines run off to the RHS and you need to h-scroll or other options to twiddle stuff. I never use vim so can't answer about it.

In TextPad I can just toggle between line wrap and single line view (ALT+Q w) as needed, though for markdown I tend to leave line wrap on.

Also its possible to use fmt(1) to re-wrap text blocks or files. In ex for example

:'a,.!fmt -w68

or vi !}fmt -w68. it could be applied to a whole document BUT I think it assumes regular text file, not HMTL or Markdown which I bet would pose some wild change due to possible confusion (I should try it one day- maybe I'm working too hard when one command would do.)

Markdown treats single lines as paragraphs and will wrap those. While newline, trailing double-space, or <br> generate a <br>

[SirWumpus]

Well ... yeah I wrote more than I meant to. But I felt badly about my OP.

It was NOT what I wanted to hear/read at 5h30 in the morning before walking the dog - a stream of complaints in my email, rather than questions about my reasoning. I was miffed and may have been snarky in reply. I'll leave it at that.

[xexyl]

Well ... yeah I wrote more than I meant to. But I felt badly about my OP.

It was NOT what I wanted to hear/read at 5h30 in the morning before walking the dog - a stream of complaints in my email, rather than questions about my reasoning. I was miffed and may have been snarky in reply. I'll leave it at that.

If I'm honest I've felt bad about it throughout the day. Quite a lot actually.

But you handled it fine. Even if you hadn't it would be understandable. I'm sorry it came across as complaints. It was not meant to be - but that's precisely why I came back about it .. I knew it couldn't have come across well. Not intentional but that doesn't matter. What matters is how it must have felt.

You did fine (the edits). I should have waited a bit of time first so I could do it better. I'll not forget that.

Apologies again. It was all from concern but in a rush I neglected to ask. I regretted it almost as soon as I posted it but it was too late then - I knew you would have seen it.

Have a good night and enjoy your puppy!

[xexyl]

First - thanks.

As I asked in the other comment - is it vi(m)? If so how do you get it to auto-wrap without having to join the lines (in viewing - I know how to do it when typing)? Still - it might be good to do it for others.

Not sure I understand the question properly, so I might be on parallel one:

Well what I meant is not relevant as you weren't using vi (and I remember nvi from years ago). I was wondering if there was a way in vi(m) to get it to just wrap the text at a certain width .. in viewing without actually typing.

When I use vi aka nvi (BSDs version by Keith Bostic) by design vi wraps the physical line according the to screen width. Also look at :set wrapmargin which can adjust the right-hand-side. vim might have non-standard options to enable/disable the default behaviour so lines run off to the RHS and you need to h-scroll or other options to twiddle stuff. I never use vim so can't answer about it.

Ah .. I use textwidth which means that the other won't be used. But that's for typing. If I join lines and then type at the end it will format the paragraph based on the textwidth setting.

In TextPad I can just toggle between line wrap and single line view (ALT+Q w) as needed, though for markdown I tend to leave line wrap on.

Yes that makes sense. In macOS TextEdit wraps too. I can see how it happened. What I cannot quite comprehend is my reply to that. It was not meant to be a complaint but I can also see how it would be hard to not be viewed as a complaint.

Also its possible to use fmt(1) to re-wrap text blocks or files. In ex for example

:'a,.!fmt -w68

or vi !}fmt -w68. it could be applied to a whole document BUT I think it assumes regular text file, not HMTL or Markdown which I bet would pose some wild change due to possible confusion (I should try it one day- maybe I'm working too hard when one command would do.)

It probably does. Another way is (in vim) to go into visual mode and then hit =. But that can depend on the document type too I think.

Markdown treats single lines as paragraphs and will wrap those. While newline, trailing double-space, or <br> generate a <br>

Yes. Of course. Markdown can be picky in ways that I personally don't enjoy. Having to put an extra line or adding spaces or tabs at the end of lines (that as you correctly point out are impossible to see without a search for those characters) just to get the right format is not something I particularly enjoy.

Thanks for the reply. Best wishes and keep up the good work .. sorry about earlier.

[xexyl]

Now as for the tab visual - quickly before I go again.

Do you think having <tab> would be sufficient? It would be obvious what is meant. It would be easier to see and it would not assume that everyone knows the terminology (ht, vt etc.). As it stands (or stood) one could certainly not tell.

Another option would be to write a quick note about it though it might still be nicer to have something like <tab> (since some terminal emulators/editors and also some browsers do not like all unicode symbols).

[SirWumpus]

Do you think having would be sufficient? It would be obvious what is meant. It would be easier to see and it would not assume that everyone knows the terminology (ht, vt etc.). As it stands (or stood) one could certainly not tell.

Well in the text I show the tab glyph/symbol.

use any ASCII TAB (␉) anywhere

So it should be understood that when they see it in the text example its means TAB. Using <TAB> has spacing concerns I think and is less pleasing in my mind.

[SirWumpus]

elf$ find . -name '*.md' | xargs grep 'markdown.html#'
elf$

The above shows that the markdown.html document currently is only referenced by document, no sections / anchors yet. So playing with titles and <div>s etc.

@xexyl I'd like to propose an experiment this morning that might make future Markown viewing and development easier.

• The mark-guide defines one, two, even three section names, plus the section title. If we consider the section title can change, then lets pick just one (1, une, uno, ein) alternative anchor since there are currently no anchor reference in use.

• I mentioned be <span id="section_name"></span> is better for browser markdown viewer plugins, probably because they're acceptable inline elements, whereas <div> mucks about. This is the main thrust to replace the use of <div> with <span>. I think with the HTML version, ANY id=name can be used for <a href="#name">... so the need for <div> is "force of habit". If <span> or some other acceptable inline tag can be used I'd be really happy.

• If we use <span>, its placement is more flexible, eg. above the section title is good, but leave a small margin at the top when jump to, text not flush with top of screen. Place it after the section but before the text, eg. ## <span id="corgi_toys"></span> Corgi Die Cast Metal Toys avoids the slight top margin, though a little messier to read, though the viewer is fine.

So have a think, maybe a play, while I go walk the dog.

[xexyl]

Do you think having would be sufficient? It would be obvious what is meant. It would be easier to see and it would not assume that everyone knows the terminology (ht, vt etc.). As it stands (or stood) one could certainly not tell.

Well in the text I show the tab glyph/symbol.

use any ASCII TAB (␉) anywhere

So it should be understood that when they see it in the text example its means TAB. Using <TAB> has spacing concerns I think and is less pleasing in my mind.

Hmm ... the problem I see is it's small, the unicode symbol, and it also kind of looks messed up in both html and in a text editor. It's true that if you (and it's good you did that) specifically note it it's less of an issue but the other parts might still matter and what if someone misses it?

I don't know. Only other thing: what would a screenreader do with a unicode symbol? (That might be an argument for not using the tick marks too .. but on that I have a thought that might be perfect, using your idea still, but with a slight mod .. will get to that soon).

Of course unicode symbols are used elsewhere too and we probably want to draw a line somewhere.

------

^ the line is above :-)

Still one thing at a time - this one the tab issue. The way I see it we have three options:

0. .Your unicode symbol.
1. <tab>.
2. Or extra spaces (like we had).

Now 0 you prefer and I prefer either 1 or 2. My problems with 0 are the size and how it kind of messes up the look of the text. Of course I helped come up with the guidelines so that probably is less of an issue for me but still it might apply to others?

As for 2 it might be implied. I can see how <tab> might be ugly but (and this is a personal preference) I think the unicode symbol is worse (in look) especially with how it messes up the adjacent text.

I know you mentioned me in another comment. I'll address that first and then I'll see if I can bring up the X and tick marks for 'bad' and 'good'.

[SirWumpus]

2. Or extra spaces (like we had).

(Minor) Problem as I see it is that extra spaces, some wise ass is going to copy/paste the text and look for tabs or that we've simulated spacing out the correct tab stop. - silly i know, but multiples spaces are still spaces and do not illustrate the point. I'd concede the unicode U+2409 ␉ for <tab> grudgingly.

Let me see what Windows's screen reader does. Frankly what little I know of screen readers I've never heard one vocalise whitespace.

[xexyl]

Okay first of all: a good comment (actually all your comments are good).

Second of all: as for the <span> that might be something that @lcn2 has to decide on. I did not come up with the use of <div>. In fact my websites don't use it .. it uses the old <a>. I'm too lazy (and don't care enough, perhaps because I'm lazy and also I hate web design) to change it - though it's not many I must admit.

On my behalf (and I'll reply to your thoughts below) if <span> works (as in both compliant and also pandoc 'does the right thing') then I certainly do not mind. If it works and it works in a way I believe t hen it would also (I think) be able to do a mass replace in the other documents (all markdown documents) and then we could regenerate the html files. That comes with some risk but my tool does a good job with it and git diff helps a lot.

Again I think Landon will have to decide this one but I personally do not mind either way.

elf$ find . -name '*.md' | xargs grep 'markdown.html#'
elf$

The above shows that the markdown.html document currently is only referenced by document, no sections / anchors yet. So playing with titles and <div>s etc.

That's true.

@xexyl I'd like to propose an experiment this morning that might make future Markown viewing and development easier.

If I am honest I'm not sure how it would make development easier but I would also guess it wouldn't make it any harder either - so if it works then that's great. I am not doubting you: I just don't know about pandoc and various other things (as above web design is something I rather dislike).

• The mark-guide defines one, two, even three section names, plus the section title. If we consider the section title can change, then lets pick just one (1, une, uno, ein) alternative anchor since there are currently no anchor reference in use.

Okay so by section names what do you mean exactly? I just want to be on the same page. I see many <div> and also many # (and multiple #s) but I'm not sure what you mean by section name versus section title: perhaps a html terminology thing?

Fun reference to I guess Spanish and German (is the other one French?) I might add. But as for section titles having only one I think it might depend on what you mean. If you mean the anchors then I think more than one for some (or all?) is worth having to help people out. But if you mean (for example) ## Replace ... then I'd agree.

The only reason I'd think more than one anchor might be useful (not always and not necessarily required) is for usability - some things might be easier for others to remember.

Incidentally the question of whether a table of contents might be useful in this document is something that popped into my head. The rules too (maybe?) but maybe not (it's long). The guidelines would be harder to do I think though - but I also don't know exactly what Landon has in mind - just some general ideas from some of the videos he posted.

• I mentioned be <span id="section_name"></span> is better for browser markdown viewer plugins, probably because they're acceptable inline elements, whereas <div> mucks about. This is the main thrust to replace the use of <div> with <span>. I think with the HTML version, ANY id=name can be used for <a href="#name">... so the need for <div> is "force of habit". If <span> or some other acceptable inline tag can be used I'd be really happy.

Here is my ignorance showing again: I have heard of inline elements but I don't remember what they are. If as you say <span> can be used in place of <a name="#name"> and <a href="#name> (that's what you mean, right?) works then I personally don't see the problem. But maybe @lcn2 has some thoughts on that?

Okay that doggie is adorable! Is it your puppy? If so would you tell me how you made the text (only if you have time and don't have something else you'd rather do of course). I use GIMP but I have never played with that kind of text. Perhaps just a certain font? Anyway if it's your doggie it's adorable (I mean not as adorable as mine but you'd have to say the same thing about yours).

• If we use <span>, its placement is more flexible, eg. above the section title is good, but leave a small margin at the top when jump to, text not flush with top of screen. Place it after the section but before the text, eg. ## <span id="corgi_toys"></span> Corgi Die Cast Metal Toys avoids the slight top margin, though a little messier to read, though the viewer is fine.

Please elaborate what you mean by the first sentence (especially the e.g. part)? How do you mean it leaves a small margin at the top when jumps to - and the text not flush with top of [the] screen?

Well you explain how to avoid it so I guess if I can (see below) I can test it out. Not sure about that right now and it might not matter much as I'm already fine with this if Landon is.

So have a think, maybe a play, while I go walk the dog.

Does my comment help? Incidentally if Landon does agree with this I would be happy (I think ... it depends) to make the change, once the things are stable. Anyway on my behalf I'm perfectly okay with this.

I might even be able to play with it briefly. I could just make a quick change and then test on my server after generating the file. It might help Landon out too. But perhaps it wouldn't. I'm not sure if I have the energy (yes it's sad I know) but anyway I am personally quite fine with this. As long as the other documents are updated too (whether right away or over time I don't know - see below).

There is one postfix with the mass replacing though. It would depend on placement. Would this not work then?

<span id="foo">
# Foo
</span>

?

If not then it would take more work to do the replacement.

[xexyl]

Now as far as the ❌and ☑️ (or whatever one you used).

Notwithstanding the screenreader concern and one other thing (see below) the trouble I had (that I was much too blunt about, though not intentionally so - again sorry and I hope this reply is helpful) is that it appeared (but again I was maybe reading things wrong) that you had it in the same block. Before it had two blocks: the bad example and the good example ('instead use ...' or some such).

I do recall actually changing in one case a <== no thank you to (it might have been C) a comment but Landon wanted it to be incorrect deliberately. Now that might imply that the tick mark should not be there and instead just the X in the bad (first) section.

I'll take a couple screenshots (in vim) that show your current edit (well the one I fetched yesterday before your additional commit) and then what I am thinking of. I'll then explain the rationale. Actually .. three images. I'll explain each.

The first one is what you have. It's good but I think it can be improved upon a bit. I'll explain.

Now the second one (and third one for this detail) uses the red X instead of the smaller white X. This is to make it clearer. The smaller x is harder to see (at least for some of us) and the red stands out better (I think) .. except to those who are colour blind perhaps :-)

(It is thought I am partially colour blind but that might not be strictly true - in any case I can see red).

The other part of the second screenshot is a subtle one but before I get to it I'll show the third as it's related.

Okay the last one is still using your idea (instead of the <== no thank you), just like the others, but it's worded like it was before your initial go at it.

Can you see the difference? If not it's in the title. One uses 'do NOT' and the other does not. This is subtle but it is known that the human brain often (in some cases always, depending on the person and maybe circumstances) ignore the negatives: 'not', 'no', 'don't' etc.

They just see the 'DO' part. And we all have seen how this can be manipulated too.

I am not saying the wording is quite right but that's the idea. Of course your idea of replace might have merit too. Though I like the please (I believe and try - and usually succeed - to say both please and thank you, even for things that most people think are insignificant) there I must admit and the capitalised USE (or in the other one NOT) makes it stand out a bit better.

An important point on the ones I proposed that I did not mention (I think?) is that the 'instead use' has valid html (though .. technically so does the other one but it's marked) and that's why it does not have the tick mark. It could also be, though perhaps not often done, be used in a yank paste (in fact for the <img> tag I do exactly that). Not that I couldn't just move the cursor over but anyway the idea is the second one, the correct one, has only the valid parts whereas the first (the one to not use) has the X (or the old way the <== no thank you).

I'd love to have your thoughts - and @lcn2's thoughts too. But I do know the idea was to separate the too. Also (and I just remembered this) having the two lines without a blank line also makes it a bit harder to distinguish. That goes more so with the small x and small tick mark (but like I said the valid one does not need a tick mark or so I think).

--

As for testing what you have here - not sure if I can do that or not. I mean I can but not sure if I'll get to it. Nonetheless when I looked at generated output the things that stood out to me were the ticks/x and more so the ht unicode char. Those were the real issues. As for the long lines (if you didn't fix it) I'm more than happy to do that when you're done as I'm the one being a pain there. It might even be a pedantic thing on my part. You're right that markdown doesn't care about that but it's a bit easier to read for longer lines. The correct text width is up to debate of course. 72 (didn't you say you used that?) is perfectly fine and I use 80 generally.

I believe the 'correct' value for git commit is closer to 72 if not 72 (and for the first line 51 iirc). But there will always be some inconsistencies so as long as it doesn't go on that long (of course for code blocks it might be required or desired - this is merely for paragraphs) so that it wraps. Presumably nobody is going to read the markdown on a phone though I guess I would not be surprised if someone did it anyway. But there is only so much we can do.

Anyway - those are my thoughts. Let me know what you think. @lcn2 too please when you get a chance.

Keep up the good work @SirWumpus! When you both have finished the rules document I'll change the -- back to the ## but making sure to update the links too (which means another <div> or if it goes as you wish with <span> then with <span>).

Enjoy your day!

[SirWumpus]

If I am honest I'm not sure how it would make development easier but I would also guess it wouldn't make it any harder either

Well two development points:

• I use TextPad, which has this button "View in browser" so I can send the current doc for preview, edit, resend (or reload in browser to avoid extra Tabs). With other tools you'd probably have to drag-n-drop the .md file on the browser (mention long ago in a comment far far away I use Firefox/LibreWolf with the Markdown Viewer Add-on by Simov, there is a Chrome version; very comprehensive IMO). It also auto generates a table of contents.

• When it renders Markdown with <div> the entire document becomes incomprehensible; no resemblence o anything like what the document should look like. My temp. solution as to backslash escape open-close <div> tags, though now I replace by <span>. With escape <div> I see them in the viewer, but the remainder is readable; with <span> its hidden as an empty HTML element.

You probably don't write you Markdown and proof it in this way, which is fair enough (but you could, nudge nudge). Everyone has a their own workflow.

Okay so by section names what do you mean exactly? I just want to be on the same page. I see many <div> and also many # (and multiple #s) but I'm not sure what you mean by section name versus section title: perhaps a html terminology thing?

<span id="section_name"></span>
### The section title

more than one anchor might be useful (not always and not necessarily required) is for usability - some things might be easier for others to remember.

But they're internal names and don't have to be easy, just relevant. Plus you have multiple anchors that are never used in the first place. Just stick to one please.

There is one postfix with the mass replacing though. It would depend on placement. Would this not work then?
c> ```

Foo

```

No. <span> is an HTML inline text element. The section title # Foo will generate a block element causing undefined results. The <div> wrapping of section title works in HTML, but sucks in the Markdown viewer.

If not then it would take more work to do the replacement.

I would NOT make it an objective to apply this across the board in an edit sweep to satisfy some OCD. I'd apply going forward only as we touch documents for future contests, so for the start mark-guide, rules, and guidelines, and faq - they're all on the block to be touched before IOCCC29.

[SirWumpus]

Now as far as the ❌and ☑️ (or whatever one you used).

How you get the nice red ✕ (I had to use a span-style) The tick mark is U+2714 ✔ (or &#10004;&#65039; ✔️) and U+2715 ✕ (or yours above U+274c ❌). Some fonts/versions get colour.

Before it had two blocks: the bad example and the good example

That was correct. I intentionally merged the two blocks. With the tick/check marks in the example margin, the intervening text between blocks is redundant, it was just more unnecessary boiler plate IMO. I see no reason to have separate blocks, unless in place of tick/check marks in the margins we go with this which I don't like so much but probably would address you screen reader concern...

✕ Wrong (problematic)
```
*this it italic*
```
✔ Correct (preferred)
```
_this is italic too_
```

Or when actually rendered...

❌ Wrong (problematic)

*this it italic*

✔ Correct (preferred)

_this is italic too_

The above makes the document longer of course, but visually better than the original. Just a matter of deciding which new version. I like one block inline, I'm guessing you prefer the latter.

(I'm having trouble keeping up with your comments. I'll get there.)

[SirWumpus]

From my OP

#234 (comment)

Also made use of Unicode check-mark and cross for good and bad respectively. Unfortunately you can't colour them green and red within code blocks, which would have been nicer.

You can type in the red X version ❌ (emoji : x:) and green tick ✔️ (emoji : heavy_check_mark:), but they don't have colour when rendered in code blocks. Outside of the code block you get the styling.

---

Please do NOT vs Do not vs Replace

First Please do NOT is soft, optional, a request in tone. Second Do not or your Do NOT (don't like in titles) is more assertive, a requirement, demanding in tone. Third Replace is simply a statement of fact, more neutral tone.

---

Line wrap width 72 columns, allows for some margin to exceed it by a character of two where suitable for balance without reaching 80 columns. If you have 80 columns as the hard wrap, then I can see more jagged RHS.

Also 72 allows for a tab indent when you quote a block of text in plain text or email. I never use HTML email (evil marketing influence). (Why can we have Markdown for email formatting?)

[xexyl]

If I am honest I'm not sure how it would make development easier but I would also guess it wouldn't make it any harder either

Well two development points:

• I use TextPad, which has this button "View in browser" so I can send the current doc for preview, edit, resend (or reload in browser to avoid extra Tabs). With other tools you'd probably have to drag-n-drop the .md file on the browser (mention long ago in a comment far far away I use Firefox/LibreWolf with the Markdown Viewer Add-on by Simov, there is a Chrome version; very comprehensive IMO). It also auto generates a table of contents.
• When it renders Markdown with <div> the entire document becomes incomprehensible; no resemblence o anything like what the document should look like. My temp. solution as to backslash escape open-close <div> tags, though now I replace by <span>. With escape <div> I see them in the viewer, but the remainder is readable; with <span> it's hidden as an empty HTML element.

That's unfortunate indeed.

You probably don't write you Markdown and proof it in this way, which is fair enough (but you could, nudge nudge). Everyone has a their own workflow.

Those are Windows only though so I wouldn't be able to even if I wanted to.

But the other problem is based on how the website scripts work - which as you know it uses pandoc. I then scp it to the server and open it on the local version.

Okay so by section names what do you mean exactly? I just want to be on the same page. I see many <div> and also many # (and multiple #s) but I'm not sure what you mean by section name versus section title: perhaps a html terminology thing?

<span id="section_name"></span>
### The section title

Ah. I see.

more than one anchor might be useful (not always and not necessarily required) is for usability - some things might be easier for others to remember.

But they're internal names and don't have to be easy, just relevant. Plus you have multiple anchors that are never used in the first place. Just stick to one please.

Well I can see the argument for just one but it shouldn't matter I would think? Unless it causes a display issue. But that is not even really for me to decide - the use of span or div or anything else.

There is one postfix with the mass replacing though. It would depend on placement. Would this not work then?
c> ```

Foo

No. <span> is an HTML inline text element. The section title # Foo will generate a block element causing undefined results. The <div> wrapping of section title works in HTML, but sucks in the Markdown viewer.

Hmm ... but then we render it to html so that does not really matter much - at least not for the website. And as for # Foo creating undefined results - doesn't that depend on the renderer?

I can't help with the markdown viewer problem. I would suggest you ask @lcn2 about that one. My suspicion is it won't be supported but that's not something is up to me.

If not then it would take more work to do the replacement.

I would NOT make it an objective to apply this across the board in an edit sweep to satisfy some OCD. I'd apply going forward only as we touch documents for future contests, so for the start mark-guide, rules, and guidelines, and faq - they're all on the block to be touched before IOCCC29.

Yes - well the question is will it be done at all. The rest could be worried about another time. But we'll see what Landon says when he's available, I guess.

[xexyl]

From my OP

#234 (comment)

Also made use of Unicode check-mark and cross for good and bad respectively. Unfortunately you can't colour them green and red within code blocks, which would have been nicer.

Let me see ....

pandoc disagrees there. See:

renders as:

You can type in the red X version ❌ (emoji : x:) and green tick ✔️ (emoji : heavy_check_mark:), but they don't have colour when rendered in code blocks. Outside of the code block you get the styling.

See above screenshots.

Please do NOT vs Do not vs Replace

First Please do NOT is soft, optional, a request in tone. Second Do not or your Do NOT (don't like in titles) is more assertive, a requirement, demanding in tone. Third Replace is simply a statement of fact, more neutral tone.

That is true. However it's not a hard rule. It's a request. But I was actually suggesting to NOT use 'NOT' precisely because people tend to not see 'not', 'don't', 'no' etc.

Whether to use Please USE or USE or just Use is another matter. But I would personally see that more as an instruction than Replace. Which is to say I think it would depend on the person what has more force - just like some people do not miss 'not', 'no', 'don't, ...

And as I said I'm not opposed to replace. I was using both to highlight the problem of saying 'do not'.

Line wrap width 72 columns, allows for some margin to exceed it by a character of two where suitable for balance without reaching 80 columns. If you have 80 columns as the hard wrap, then I can see more jagged RHS.

I've thought of changing it before. Unfortunately it doesn't always work well. It also makes my files even longer (at least in line count). As you know I write WAY TOO much.

Also 72 allows for a tab indent when you quote a block of text in plain text or email. I never use HTML email (evil marketing influence). (Why can we have Markdown for email formatting?)

I don't use html in email either - not intentionally anyway (if my client does that that's another matter entirely). But you can tab indent with 80 too.

.. and of course in some cases, depending on the word, it'll be under 80, as it depends on the words (or text). That would be the same regardless of the width - though doing it at 1 or 2 is amusing (at least it is for me - just as a quick experiment).

Anyway as long as it fits on most screens (not sure on phones of course) it should be fine. 72, 80, most people have a wide enough screen for those. But different people will also use a different max width. I would dread trying to standardise it throughout all the markdown files.

[xexyl]

As for ht:

... but that's being scaled by GitHub in browser. In the web browser it is tiny and hard to tell. But that was what I was getting at earlier.

[SirWumpus]

Cette histoire de <div> - ca me gens! Je deviens fou!

(Excuse, been watching French TV)

Testing, building, and my <span></span> for some reason get wrapped in "pee" <p> causing unnecessary spacing. Put the <span> inline ## <span id="corgi_toys"></span> Corgi Die Cast Metal Toys appears to work spacing wise, but GitHub markdown prefixes the id= I suppose to create a name-space. <div> gives me headaches.

As for ❌ and ✔️ in the code body, gets no colour when render as straight markdown, but in full HTML its fine, except the ❌ (heavy multiplication) appears thicker than the heavy tick (grr fonts!). But at least the colour is present.

I need to twiddle more, its like the Dark Ages between IE6 and Netscape, but for Markdown. Short of playing with the CSS which everyone wants me to avoid (happy too except for those scroll bars).

@lcn2 Any I'll have some small change either this evening or tomorrow morning, so don't go merging just yet.

[xexyl]

Cette histoire de <div> - ca me gens! Je deviens fou!

(Excuse, been watching French TV)

Quite all right.

Testing, building, and my <span></span> for some reason get wrapped in "pee" <p> causing unnecessary spacing. Put the <span> inline ## <span id="corgi_toys"></span> Corgi Die Cast Metal Toys appears to work spacing wise, but GitHub markdown prefixes the id= I suppose to create a name-space. <div> gives me headaches.

I think we have to in this case not worry about GitHub's rendering since that's not the target for the website. As for the pee issue I am afraid I can't help.

As for ❌ and ✔️ in the code body, gets no colour when render as straight markdown, but in full HTML its fine, except the ❌ (heavy multiplication) appears thicker than the heavy tick (grr fonts!). But at least the colour is present.

The nice thing with the colour is it's more obvious and it also it appears to be bigger and easier to see even without that. The tick marks probably don't need to be there as it's for showing the 'proper' way (even if for you <div> is not proper).

I need to twiddle more, it's like the Dark Ages between IE6 and Netscape, but for Markdown. Short of playing with the CSS which everyone wants me to avoid (happy too except for those scroll bars).

That sounds horrifying. And unfortunately yes CSS seems to be a pain. IE6 should be called the Deplorable Word, to make a Narnia reference. CSS is not much better maybe. Netscape brings back some memories.

@lcn2 Any I'll have some small change either this evening or tomorrow morning, so don't go merging just yet.

I'm curious to see what you have in mind as well.

[SirWumpus]

I think we have to in this case not worry about GitHub's rendering since that's not the target for the website.

I'm only frustrated by GitHub in my ability to quickly view things I had hoped correctly expressed internally. But alas Markdown is an "open file format", so everyone has their own take on what syntax to support and how its is expressed in HTML/CSS. I'm amazed at how complex it is, mind you, websites everywhere have gone nuts with frameworks and complex HTML (not counting Javascript).

Its frustrating and annoying. IOCCC has settled on a conversion tool they are happy with and accept its oddities. I'll have to just bite the bullet and install it, just so I'm in sync. Else I'll be comparing Granny Smith with McIntosh - both apples but different profiles.

As for the pee issue I am afraid I can't help.

I don't need hand holding.

The nice thing with the colour is it's more obvious and it also it appears to be bigger and easier to see even without that.

I agree with the that, the colour is nice (if you ignore colour blindness issues).

The tick marks probably don't need to be there as it's for showing the 'proper' way (even if for you

is not proper).

I believe the ticks should be there in one style or another...

#234 (comment)

That was correct. I intentionally merged the two blocks. With the tick/check marks in the example margin, the intervening text between blocks is redundant, it was just more unnecessary boiler plate IMO. I see no reason to have separate blocks, unless in place of tick/check marks in the margins we go with this which I don't like so much but probably would address you screen reader concern...

One space saving block with inline cross/tick. I prefer this

❌ *this is italic*
✔️ _this is italic_

Or separate block like. IMO better than the original version, but not my favourite.

❌ Wrong (problematic)

*this it italic*

✔️ Correct (preferred)

_this is italic too_

I'm curious to see what you have in mind as well.

Nothing major. But it will this morning some time.

[xexyl]

I think we have to in this case not worry about GitHub's rendering since that's not the target for the website.

I'm only frustrated by GitHub in my ability to quickly view things I had hoped correctly expressed internally. But alas Markdown is an "open file format", so everyone has their own take on what syntax to support and how its is expressed in HTML/CSS. I'm amazed at how complex it is, mind you, websites everywhere have gone nuts with frameworks and complex HTML (not counting Javascript).

Yes it is amazing how many different versions/implementations of it. And yes many websites (maybe most?) have some kind of framework or content generator of some sort. I prefer basic websites. Unless maybe it's meant to be a website for images but even then I don't want anything too fancy. Don't get me started on ads and whining about ad blocks. Though it's amusing - due to my DNSBL (local view) I often see 'advertisement' and it's just a blank 'image'. But nobody is responsible for a company's failed business model.

It's frustrating and annoying. IOCCC has settled on a conversion tool they are happy with and accept its oddities. I'll have to just bite the bullet and install it, just so I'm in sync. Else I'll be comparing Granny Smith with McIntosh - both apples but different profiles.

That seems ... odd. But yes I think you will have to do that.

As for the pee issue I am afraid I can't help.

I don't need hand holding.

Okay that's awful. Funny but awful. Not what I expected! Made me laugh out loud though and that's always great.

The nice thing with the colour is it's more obvious and it also it appears to be bigger and easier to see even without that.

I agree with the that, the colour is nice (if you ignore colour blindness issues).

... which is why I brought it up - but there is nothing that can be done about that.

The tick marks probably don't need to be there as it's for showing the 'proper' way (even if for you is not proper).

I believe the ticks should be there in one style or another...

Well the idea Landon had originally is that one is incorrect so have incorrect markdown/html (or an indication it's incorrect) and then the correct one has nothing wrong so no indication: though it's true that BOTH would be valid technically so there's that too.

I can see it both ways but I do know that some people (or at least I do!) yank paste some of it (in my case it's specifically the <img> one .. though there might be a few others now I think on it such as the <hr> related ones).

But of course the cursor is a brilliant invention so it would not be that big of a deal. I don't know. What do you think @lcn2 (whether or not it's what your original idea was I personally don't think it's a big deal, fwiw)?

#234 (comment)

That was correct. I intentionally merged the two blocks. With the tick/check marks in the example margin, the intervening text between blocks is redundant, it was just more unnecessary boiler plate IMO. I see no reason to have separate blocks, unless in place of tick/check marks in the margins we go with this which I don't like so much but probably would address you screen reader concern...

One space saving block with inline cross/tick. I prefer this

The thing is with the single block is yes it might be in a way 'redundant' but it's more clear due to the visual distinction. Maybe not to all but IF it must be in a single block then it should be broken up by some lines - maybe one or two or three but probably just one or two (at most two?) is sufficient.

The two sections is a nice visual distinction though. Of course with the big red X it's easier to tell now - as long as we have a bigger tick mark too (and preferably one that's not grey if possible). Let's see...

✅

I think that would be much more clear. Plus it would be consistent with many places where red is 'no' or 'stop' or 'pause' and green is 'go' or 'start' or 'resume'. (Okay so the pause and resume are less so but you know what I mean). The size difference and the more distinct colour is nice.

BUT on the other hand ... maybe it would not look good against the white background for some. I can see that for me. In fact I can see it for me even on a dark background (like what I'm looking at typing this). But even so...

✔️ is not easy to see (worse on a dark screen - and what if a person overrides the style?) and ☑️ is not much better (it might even be worse on white especially as the grey background is barely there and the tick is white itself).

But if we didn't have the tick mark none of that would be a problem.

I guess we should wait to see what Landon thinks - perhaps we even need to experiment with both (maybe side by side in a generated file)? I can do that and maybe you and Landon could too so we could figure out what we might prefer (and what others might prefer though that's nigh impossible to tell). Even so the tick marks should not strictly be necessary and might be a distraction. That latter way is how I view it.

❌ *this is italic*
✔️ _this is italic_

Or separate block like. IMO better than the original version, but not my favourite.

❌ Wrong (problematic)

*this it italic*

See above for why the two blocks. As for italic...

✔️ Correct (preferred)

_this is italic too_

The reason for the underscore is it could be problematic otherwise with some parsers (no idea about pandoc here) but not only that it can be harder to distinguish - in particular when using both bold and italic.

Consider this:

***this is bold italic***

or:

**_this is bold italic_**

or:

_**this is also bold italic**_

It would also possibly (not necessarily) prevent mistakes in formatting. Of course as noted somewhere it might be there are some cases in some markdown files that do not have this format - including possibly before the guideline was thought up (I'm the one who did it btw so if you have any issues with it you're free to blame me). Still it's a nice distinction and it helps out in a number of ways.

And as for the tick mark - well see above.

I'm curious to see what you have in mind as well.

Nothing major. But it will this morning some time.

Sounds good.

[xexyl]

Just edited my initial comments. Anyone who wishes to see comments that did not turn out so nice due to rushing at stupid o'clock is welcome to look at the edit history or the replies. Not that it should matter to you two except that Landon had marked one with eyeballs to look at later.

But the comments were not constructive and were in error but to not cause confusion with the replies I kept the comments in anyway - just edited out the unfortunate remarks. And besides that (as far as editing out) some of the details were fixed and some are being discussed in a constructive way as I meant all along.

[SirWumpus]

SIDEBAR: I installed pandoc and tried to generate the HTML, BUT sort -V does not exist.

elf$ gmake markdown
=-=-=-=-= IOCCC begin gmake markdown =-=-=-=-=
You want to markdown?
bin/gen-top-html.sh markdown
sort: unknown option -- V
usage: sort [-bdfHilmnrSsu] [-k kstart[,kend]] [-o output] [-R char] [-T dir]
             [-t char] [file ...]
   or: sort -C|-c [-bdfilnru] [-k kstart[,kend]] [-o output] [-R char]
             [-t char] [file]
bin/pandoc-wrapper.sh: ERROR: pandoc: /usr/pkg/bin/pandoc version: 3.7.0.2 <= minimum allowed: 3.1.12.2
bin/pandoc-wrapper.sh: Warning: pandoc version must be >= 3.1.12.2
bin/pandoc-wrapper.sh: Warning: install a more up to date pandoc and/or use -p pandoc_tool to refer an up to date pandoc
bin/md2html.sh: ERROR: pandoc wrapper tool: bin/pandoc-wrapper.sh  -- .tmp.md2html.sh.STRIPPED_MD.1010.tmp - failed, error code: 5
bin/gen-top-html.sh: ERROR: md2html.sh: bin/md2html.sh -U https://www.ioccc.org/markdown.html -v 0 -t bin/gen-top-html.sh -D ./ -m markdown.md -- markdown.md markdown.html failed, error: 100
bin/gen-top-html.sh: Warning: EXIT_CODE set to: 1
bin/gen-top-html.sh: Warning: about to exit 1
gmake: *** [Makefile:704: markdown] Error 1


elf$ pkgin list | grep pandoc
...
pandoc-3.7.0.2       Conversion between documentation formats
pandoc-cli-3.7.0.2nb1 Conversion between documentation formats
elf$

[SirWumpus]

Pushed minor update.

[xexyl]

SIDEBAR: I installed pandoc and tried to generate the HTML, BUT sort -V does not exist.

elf$ gmake markdown
=-=-=-=-= IOCCC begin gmake markdown =-=-=-=-=
You want to markdown?
bin/gen-top-html.sh markdown
sort: unknown option -- V
usage: sort [-bdfHilmnrSsu] [-k kstart[,kend]] [-o output] [-R char] [-T dir]
             [-t char] [file ...]
   or: sort -C|-c [-bdfilnru] [-k kstart[,kend]] [-o output] [-R char]
             [-t char] [file]
bin/pandoc-wrapper.sh: ERROR: pandoc: /usr/pkg/bin/pandoc version: 3.7.0.2 <= minimum allowed: 3.1.12.2
bin/pandoc-wrapper.sh: Warning: pandoc version must be >= 3.1.12.2
bin/pandoc-wrapper.sh: Warning: install a more up to date pandoc and/or use -p pandoc_tool to refer an up to date pandoc
bin/md2html.sh: ERROR: pandoc wrapper tool: bin/pandoc-wrapper.sh  -- .tmp.md2html.sh.STRIPPED_MD.1010.tmp - failed, error code: 5
bin/gen-top-html.sh: ERROR: md2html.sh: bin/md2html.sh -U https://www.ioccc.org/markdown.html -v 0 -t bin/gen-top-html.sh -D ./ -m markdown.md -- markdown.md markdown.html failed, error: 100
bin/gen-top-html.sh: Warning: EXIT_CODE set to: 1
bin/gen-top-html.sh: Warning: about to exit 1
gmake: *** [Makefile:704: markdown] Error 1


elf$ pkgin list | grep pandoc
...
pandoc-3.7.0.2       Conversion between documentation formats
pandoc-cli-3.7.0.2nb1 Conversion between documentation formats
elf$

Hmmm ... that might be a flaw in the logic of verge(1). What do you think @lcn2?

If so one of us might have to fix it - but perhaps not until after this coming IOCCC?

[xexyl]

Or perhaps it's the scripts ... that would be unfortunate (though better than the verge code - just might require editing more files).

Check this @lcn2:

$ verge 3.7.0.2 3.1.12.2
$ echo $?
0

That indicates the first version is indeed >= the second.

But then the error message is silly ... it should be < than the minimum.

And yet ... how do we manage then?

$ pandoc --version
pandoc 3.8.2.1
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /Users/cody/.local/share/pandoc
Copyright (C) 2006-2025 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

Let's see the results of those two:

$ verge 3.8.2.1 3.1.12.2
$ echo $?
0

???

[SirWumpus]

OK. I've generated a markdown.html to view. I generated PDF to for you lot. Formatting wise I think it looks good. Now upto @lcn2 to review.
markdown-pr234.pdf

Update 0

Its seven A4 pages down from 11.

[lcn2]

Excellent work @SirWumpus thank you 🙏

[lcn2]

Hmmm ... that might be a flaw in the logic of verge(1). What do you think @lcn2?

If so one of us might have to fix it - but perhaps not until after this coming IOCCC?

No thank you.

Or perhaps it's the scripts ... that would be unfortunate (though better than the verge code - just might require editing more files).

Check this @lcn2:

$ verge 3.7.0.2 3.1.12.2
$ echo $?
0

That indicates the first version is indeed >= the second.

But then the error message is silly ... it should be < than the minimum.

And yet ... how do we manage then?

$ pandoc --version
pandoc 3.8.2.1
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /Users/cody/.local/share/pandoc
Copyright (C) 2006-2025 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

Let's see the results of those two:

$ verge 3.8.2.1 3.1.12.2
$ echo $?
0

???

Please review the verge(8) man page.

UPDATE 0

Although the verge(8) man page is in MUCH need for improvement.

UPDATE 1

The verge(8) man page has been improved in jparse PR 50.