[HN Gopher] My Contribution to Markdown
___________________________________________________________________
My Contribution to Markdown
Author : zdw
Score : 82 points
Date : 2022-09-02 16:37 UTC (6 hours ago)
(HTM) web link (leancrew.com)
(TXT) w3m dump (leancrew.com)
| NelsonMinar wrote:
| That little asterix on "without any changes" is doing a lot of
| work.
|
| > The code block has to be indented, of course, or--in many
| implementations, but not Gruber's--surrounded by fences.
|
| Indenting is always a nuisance and can present more complicated
| problems for Python or other whitespace-significant languages.
|
| CommonMark and most Markdown flavors support 3 backticks or 3
| tildes as a fence. Then everything inside is literally unaltered
| code. Not sure what you do if your code sample itself has the
| fence in it.
| isitmadeofglass wrote:
| A contribution typically implies actual work, not just having
| talked to the person who made the actual contribution.
| redditor98654 wrote:
| A product manager that comes up with feature ideas is doing
| actual work, would you not agree? Even if they themselves do
| not implement anything.
| just-ok wrote:
| What? No. Writing a well-spec'd feature request with clear
| outcome and behavior expectations is work. Just asking,
| "Wouldn't it be cool if ____?" is not actual work.
| redditor98654 wrote:
| If the feature is simple enough, it is possible to
| illustrate it in a few sentences. I am just speculating at
| this point, but if the discussion went like "hey, I think
| in Markdown, if the users enters a code-block, we should
| treat everything literally and not escape anything. This
| way users can just copy-paste code and expect it to render
| exactly like the raw text".
|
| This is clearly spec'd and has clear expectations on how it
| should behave. No implementation details of course which
| you wouldn't expect from a product manager in most cases as
| well.
| julianlam wrote:
| Not according to GitHub, which -- unless I'm mistaken -- treats
| opened issues as contributions.
| soperj wrote:
| Noticing a bug and filing a report on it is actual work.
| brycewray wrote:
| > Anyway, it was during a digression--actually a digression
| within a digression-- that Gruber talks about code blocks in
| Markdown and how one of his favorite features is that you don't
| have to escape anything in a code block. You can paste source
| code directly into your Markdown document without any changes,
| and it will appear as expected in the rendered HTML.
|
| True enough as far as it goes but, if you use that Markdown in
| some static site generators (SSGs), you may still have to massage
| it a bit so the SSG output won't be borked. For a couple of
| examples:
|
| - In Eleventy and Jekyll (and maybe others), you often have to
| wrap code blocks in `{% raw %}` and `{% endraw %}`.
|
| - In Hugo, if you're including anything that Go initially
| "thinks" is real code rather than just a reproduction thereof,
| you must put comment characters around it: `{{< this >}}` isn't
| OK, but `{{</* this */>}}` is (and will display in Hugo as the
| desired `{{< this >}}`).
| groby_b wrote:
| If the SSGs are broken, that's hardly markdown's fault.
| brycewray wrote:
| Just sayin'. :-)
| n4jm4 wrote:
| I supported an effort to standardize Markdown into an actual
| common syntax, instead of the nasty variation we see between
| GitHub, Reddit, Stack Overflow, Atlassian, etc. etc. This became
| CommonMark, which everyone ignores.
| polygamous_bat wrote:
| I am sorry. However, XKCD did warn us about this:
| https://xkcd.com/927/
| [deleted]
| avgcorrection wrote:
| > 14 competing standards
|
| MarkDown didn't have any standards to begin with, just
| different implementations for different platforms. Tired 927
| refuted.
| bosswipe wrote:
| If Gruber had gotten behind that initiative it probably
| would've worked but he was weirdly antagonistic to it.
| remram wrote:
| I do wish we could have _both modes_ in Markdown, similar to how
| bash has <<END and <<'END'
|
| Sometimes I want to highlight a part of the code...
| behnamoh wrote:
| > But I was there first, you're welcome.
|
| With these things, I always think "but if he hadn't done it,
| someone else would". Therefore, what matters is the thing that
| got done; the person doing it isn't special (nor should they feel
| so).
| abnry wrote:
| You forgot these sentences right before it:
|
| > Undoubtedly, as Markdown became more popular, someone else
| would have pointed out this problem. Gruber himself would have
| been annoyed by it if he ever needed to write a code block with
| backslashes in it.
|
| People are overreacting to a tongue-in-cheek post. I doubt the
| author takes himself too seriously with all of this.
| nescioquid wrote:
| What was the purpose of the post? The author wrote a tedious
| story about listening to a podcast episode in which markdown
| codeblocks are mentioned and "That's my doing".
|
| But the rest comes off like mock humility because there
| really wasn't any information of relevance to anyone but the
| author.
|
| Had the article been about the importance of user engagement
| in open source projects and then used his personal experience
| to underscore the point, then the article is really about
| raising awareness and might be something of utility to a
| reader. This article, however, just reads like me, me, me.
| Veen wrote:
| It wasn't a personal letter addressed to you so naturally
| it fails to account for your ignorance. He's writing for
| long-time readers of his blog who already understand the
| context, his style, his relationship with Gruber and
| Markdown, and so on. Perhaps, given that you haven't got a
| clue about any of that and don't seem to know what irony
| is, you should reconsider whether your rude comment is
| justified.
| nescioquid wrote:
| Well I did find the irony of your reply delicious; sure,
| I'll just leave it to you to decide what is justified and
| what is rude.
| abnry wrote:
| Yeah, it is self centered, but it is fun.
| swyx wrote:
| im too late to contribute anything to core markdown, but my claim
| to fame is making a list of "mistakes in markdown" that Gruber
| endorsed recently:
|
| - list: https://twitter.com/swyx/status/1240719259505963010
| (previously on HN https://news.ycombinator.com/item?id=22776108 )
|
| - gruber: https://twitter.com/gruber/status/1240888155307495426
| thangalin wrote:
| Another item missing from Markdown is a standard syntax for
| cross-references and citations:
|
| https://talk.commonmark.org/t/cross-references-and-citations...
|
| Is the tweeted list a little outdated now?
|
| > no id's in headers
|
| A natural ID is derived by changing the header to lowercase and
| replacing spaces with hyphens, such as:
|
| https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
|
| > no syntax for adding classes
|
| Pandoc introduced ::: annotation blocks that produce div tags
| with classes. I discuss this length:
|
| https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...
|
| My editor, KeenWrite[0], also supports annotation syntax:
|
| https://user-images.githubusercontent.com/2131950/161400266-...
|
| > any number will do in ordered lists
|
| Isn't that either a presentation issue or a feature? I prefer
| numbering lists with a sequence of 1., 1., 1., 1., to let the
| computer automatically increment the number. Makes
| adding/removing items easier. Being able to arbitrarily change
| the numbering seems weird, though potentially useful.
|
| > code blocks (4 spaces) over code fences (```)
|
| Not sure why this is a design mistake. When reading technical
| documentation, indented stands out more. IMO, it improves
| readability for short snippets (where syntax highlighting
| doesn't matter).
|
| > can't nest Markdown in HTML in Markdown
|
| Depends on the Markdown flavour, doesn't it?
|
| [0]: https://github.com/DaveJarvis/keenwrite#download
| swyx wrote:
| yes, i was commenting on the base markdown spec by Gruber
| (since that is the subset that all the supersets have to fit)
| trauco wrote:
| All the humming and hawing about how the author of the post is
| taking credit for someone else's work, etc, is a good example of
| the problem of reading one-off things on the internet and
| commenting on them here without understanding the context or the
| voice of the author.
|
| As a long-term reader of that blog, it is obvious to me this is a
| little historical anecdote, mostly tongue-in-cheek, from a
| particular mac-centric community to which both the author and
| Gruber belong to. He's not being grandiose or trying to take
| credit.
|
| Sometimes a story is just a story.
| [deleted]
| AceJohnny2 wrote:
| Someone recently put it very insightfully, that it was
| impossible to post things candidly on the Internet because your
| in-group shared background/assumptions aren't shared by randos
| on the internet that will come across your post and
| misinterpret it.
|
| (I'm pretty sure this was linked on HN, but it's too vague for
| me to search/find it)
| capableweb wrote:
| Sounds just like what the author could expect from a discussion
| in a community which is not the same community they usually
| find themselves in ("a particular mac-centric community",
| whichever that refers to).
|
| Strangers on the internet will come across your little random
| story if it's public, and rather than blaming first-time
| readers for not understanding the context nor the voice of the
| author, maybe the author could adjust the article to provide
| the context or make the voice stronger/more obvious?
|
| Honestly, I'm fine with not understanding everything from
| communities I don't generally hang-around, it's bound to happen
| at one point or another.
| trauco wrote:
| > Strangers on the internet will come across your little
| random story if it's public, and rather than blaming first-
| time readers for not understanding the context nor the voice
| of the author, maybe the author could adjust the article to
| provide the context or make the voice stronger/more obvious?
|
| I'm not "blaming" anyone. I'm just pointing out that the
| commenters here are missing the point of the story because
| they don't understand the context, and that this is a fairly
| common phenomenon.
|
| I think it's fine to tailor your writing to a community of
| like-minded readers rather than a first-time reader from here
| that is unlikely to come back.
|
| > Honestly, I'm fine with not understanding everything from
| communities I don't generally hang-around, it's bound to
| happen at one point or another.
|
| Me too, of course. It just makes a discussion without that
| context, i.e., what's happening here, detached from what the
| author meant with the post.
| lapcat wrote:
| > Sounds just like what the author could expect from a
| discussion in a community which is not the same community
| they usually find themselves in ("a particular mac-centric
| community", whichever that refers to).
|
| The author of the blog post did not submit the article to
| Hacker News.
|
| Anyway, I wish that HN commenters would apply the same HN
| guidelines to article authors that they do to each other.
| It's all too easy to rip on someone who isn't here to explain
| or defend themselves.
| https://news.ycombinator.com/newsguidelines.html
| throwthere wrote:
| I think you're meant to read this post as if the entire thing is
| surrounded by "sarcasm" tags.
| ninepoints wrote:
| This is akin to filing a bug report, and then taking
| responsibility for the fix committed by someone else.
| dewey wrote:
| > Undoubtedly, as Markdown became more popular, someone else
| would have pointed out this problem. Gruber himself would have
| been annoyed by it if he ever needed to write a code block with
| backslashes in it. But I was there first. And you're welcome.
|
| I don't see how he's taking responsibility for fixing the bug.
| To me it just sounds like he's sharing an anecdote and this is
| not entirely serious.
| tshaddox wrote:
| I personally read it as a tongue-in-cheek boast where the
| author's intent was to clearly indicate that their contribution
| was minimal and they just happened to be the first person to
| point something out to the developers of the library.
| hisnameisjimmy wrote:
| Agree completely. This is just a fun little anecdote.
| jancsika wrote:
| Don't know about responsibility, but there are cases where I'd
| certainly take the credit. For example:
|
| 1. Finding the bug was difficult, while fixing the bug was
| trivial
|
| 2. My own proposed patches seem to sit for years, while
| emailing bug reports directly to the committer results in them
| committing fixes within days.
| actuallyalys wrote:
| I help maintain some open source projects, and I totally
| disagree. Filing bugs (or thoughtful feature requests) is
| absolutely a contribution, and I wish more users would do so.
|
| Edit: In fairness, I think some of the ways the author
| describes it are grandiose ("my extremely important
| contribution"), but I interpreted them as hyperbole.
| capableweb wrote:
| I think this is the part that itches me:
|
| > . You can paste source code directly into your Markdown
| document without any changes, and it will appear as expected
| in the rendered HTML. That's my doing.
|
| It makes it sound like the author of this blogpost actually
| did the change, while in reality they suggested the change.
| Of course it's good to suggest something, and even nicer when
| whoever you suggest it to implements it. But I'd never claim
| "that's my doing" after suggesting any features/fixes.
|
| A bit like writing an email to Apple suggesting something,
| then they do that thing and I wrote a blogpost saying "That's
| my doing, I was there first. And you're welcome.". It just
| doesn't taste well.
| actuallyalys wrote:
| I interpreted that as not being serious, but I can see why
| that part rubbed people the wrong way.
| btown wrote:
| If a candidate were to say "that's my doing" when
| describing the outcome of a prior _team_ project, and
| language barriers weren't a mitigating factor, I would
| consider that a significant red flag for ego. Not a crime,
| and a reasonable exaggeration in many circumstances. But I
| wouldn't want someone communicating that way in a
| professional capacity on an engineering team.
| indymike wrote:
| > If a candidate were to say "that's my doing" when
| describing the outcome of a prior team project,
|
| "I made that" is the ultimate statement of pride in work.
| Taking that away is a really awful anti-pattern in
| management. Let your people be proud of their
| contribution, and equally proud of the product of the
| team. The work of a team is the sum of the contribution
| of all members.
|
| > a reasonable exaggeration in many circumstances
|
| I find people who take credit for the work of the team to
| be a lot worse than people who take pride in their
| contribution to the team.
| filmgirlcw wrote:
| Well it's a good thing drdrang was just posting a missive
| on his blog and not in a job interview with you. But I
| guess if he does ever interview with you, you'll remember
| his tongue-in-cheek missive and be dismissive, even if if
| never comes up in conversation.
|
| That'll show 'em! Never write tongue-in-cheek blogs or
| else random weirdos who will never meet you will write
| you off as a candidate for an engineering team that
| doesn't exist and that you don't want to join in the
| first place.
| koheripbal wrote:
| A well described and thought out bug report can make fixes
| trivial and are worth their weight in gold.
|
| Obviously the "it doesn't work" bug reports are worthless.
| svnpenn wrote:
| The whole post is pretty obnoxious. Its literally "you made
| this? I made this":
|
| https://i.kym-cdn.com/photos/images/newsfeed/001/079/173/ed2...
| sophacles wrote:
| Some credit as the motivator of the fix is deserved. The author
| very clearly states: Undoubtedly, as Markdown
| became more popular, someone else would have pointed out this
| problem. Gruber himself would have been annoyed by it if he
| ever needed to write a code block with backslashes in it. But I
| was there first. And you're welcome.
|
| I don't think they are trying to take more credit than is due.
| dathanb82 wrote:
| But also > You can paste source code directly into your
| Markdown document without any changes, and it will appear as
| expected in the rendered HTML. That's my doing.
|
| In that sentence, it kinda does sound like they're trying to
| take credit for it.
| kergonath wrote:
| Or maybe the reader can do better than isolate a sentence
| out of context and assume bad intent. It's obvious this is
| not to be taken seriously. It's a few paragraphs on a blog,
| FFS.
| water-your-self wrote:
| Its upon the reader to ascribe malintent. Ill choose not
| to.
| sophacles wrote:
| Generally I don't like to point out typos, but in the
| context of malintent: Ill vs I'll is pretty amusing :D
| [deleted]
| sophacles wrote:
| It is their doing - they started the series of events. It's
| other people's doings ALSO. This sentence doesn't imply
| exclusivity, it just doesn't say others did stuff.
| Fortunately the entire rest of the document, particularly
| the part I highlighted above, makes it very clear:
|
| 1. what their doing is in more specific detail
|
| 2. what others' doings are in more specific detail
|
| I'm going to assume that the author included all that
| additional detail in the document on purpose, and with the
| intent of clarifying what "That's my doing" entails. It
| seems pretty unlikely that your hypothesis of "the person
| is claiming the whole thing is their doing and accidentally
| wrote a whole bunch of words undermining that simple
| sentence" is the right one.
| IncRnd wrote:
| There is an entire article. There doesn't need to be just
| one sentence plucked out of context.
|
| "I pointed this out in the Markdown mailing list, and
| Gruber agreed that it should be changed. In the next
| Markdown release--which was, I believe, his last--he made
| the change, and all the text in code blocks has been
| treated literally ever since."
|
| What's wrong with that? He said what he did, said who fixed
| the issue, and stated the result.
| Veen wrote:
| It's not that. It's tongue in cheek, as anyone who has followed
| Gruber and Dr. Drang for a while will understand.
| redditor98654 wrote:
| It is still a contribution, which is what the title is. It did
| not say "my feature implementation in Markdown". A good feature
| suggestion which is thoughtful and genuinely improves a product
| not just for that one user but for everyone is a great
| contribution.
| remram wrote:
| The exact phrasing:
|
| > That's my doing.
|
| Come on now.
| [deleted]
| kergonath wrote:
| There is even worse than that. He also wrote:
|
| > I
|
| Which clearly means that he takes full credit for the whole
| Markdown implementation. What a scandal!
| actuallyalys wrote:
| I interpreted it as a joke, but I'm familiar with the
| author and hyperbole doesn't always translate, so I can see
| why it rubbed people the wrong way.
| klez wrote:
| Right. That's why I can claim that my biggest contribution to
| Firefox is suggesting indicating the estimated reading time
| at the top of an article in reader mode. I'm the one who made
| the feature request [0].
|
| It took some time, but they finally implemented it and I felt
| (and still feel) very good about it :)
|
| [0] https://bugzilla.mozilla.org/show_bug.cgi?id=1265304
| capableweb wrote:
| I think the claim "that's my biggest contribution to X" is
| fine, if you feel like that was what you think is the
| biggest contribution you made to X.
|
| Where it starts to feel wrong, would be if you somehow
| started claiming "I suggested it first. It's because of me
| it's there. You're welcome", when you merely suggested the
| feature, not implemented or drove it to be implemented.
___________________________________________________________________
(page generated 2022-09-02 23:00 UTC)