Funny enough, browsing without Javascript resulted in the same plain text appearing in both windows. I was nearly ready to comment about how easy that is with a pair of <pre> tags. :)
That said, I'm OK with it degrading like that. The text file is perfectly readable, and conveys the information within quite well. I even kind of preferred it.
I'm terribly sorry for providing context for the rest of my comment. My sincerest apologies.
EDIT: On a less passive-aggressive note, I'll stop announcing my blocking of JavaScript by default when static content sites stop requiring JavaScript to read them.
I opened the site, saw two identical boxes of text with some ascii in the middle, read the first paragraphs.. then scrolled down and saw some license thrown in there...
Almost got too happy seeing a satire get so popular on HN. :(
I too thought it was satire at first. I was all like "hmm, that's slightly amusing". And then I realised it was serious and I was all like "wtf is the point?", then "and if it's so amazing, why isn't the main website built using it?".
I'm over Markdown and related formats for the web. We have a great ASCII format for marking up the web, and it's called HTML.
I keep a text file that grows noticeably every day. I write it in Restructured Text (could have been Markdown) for two reasons:
1. My text editor (Vim in this case) renders the text file in colors, and helps me distinguish different elements.
2. If I want, I can export to html.
Markdown and the like grew out of what people were already doing in plain text: dashes and asterisks for bullets, indentation, etc.
I would much rather write plain text, or minimally marked up Markdown or rst, than have to write <tags> for everything, especially for something like my text file that isn't really intended for the web, but can be converted if needed. html is not really meant to be read, but rendered. The various markdowns can be comfortably written, and read as is.
I don't get it. Why would I do diagrams in ascii when I can use any one of dozens of good programs and export the result via DVI or PDF. I guess it must might be nice if I want to read the document on a text console, but I don't see that use case coming up nearly often enough to justify learning yet another version of markdown and commit to doing diagrams with ascii art.
Because using ASCII makes the documents more portable, more cross-platform.
There is not need to learn another version of Markdown, the diagrams are just plain ASCII and Markdeep supports the Markdown you know and love, plus more.
The "have ASCII diagrams converted to images" thing is getting ridiculous. No, I don't want to type a border around my diagram. Text is completely and utterly unsuitable for this, I don't want to have every change require me to reformat everything.
(And frankly, the diff thing is nonsense, too. Diff produces an unreadable mess on ASCII art. I'd rather see the diff of some XML that shows me nodes added, removed, properties changed.)
I actually like the idea, for simple diagrams at least. No need to keep separate image resources anywhere. No need to even have a separate image processing program. Want to change that diagram? Well, it's right there in the document itself -- just change it. Done. And the diagram is legible both pre- and post-rendering of the document.
Exactly. There are lots of situations where it's worth trading up some polish for simpler tools and formats. Especially simpler formats.
There is lots of prior art extracting diagrams from textual drawing but AFAIK all required global conformance to some accepted "syntax". Markdeep's(?) idea of local beautification while maintaining the global fixed-width layout is brilliant as you're not limited to particular structures and anything unsupported degrades gracefully!
(If this idea has no name, let's call it "2D ligatures"?)
We could have a dozen different tools based on this idea, each supporting a somewhat different dialect, yet any diagram will be reasonably readable under any of them — which is exactly the quality you want when excavating a 40-year-old README of unknown origin.
It's the simplest thing that could possibly work. Except one: using line drawing characters directly in the source (and requiring no tool at all, just view in fixed-width font). Let's try:
Hmm, not as good but mostly OK (though font dependent), except for circles. Disappointingly I found no matching parts for bigger than 2x2 circle. It's easy (technically, not sure about politically) to add a few more but it's impossible to support smooth circles of arbitrary radiuses. (OTOH, neither does Markdeep.)
Perhaps the best of both worlds would be writing unicode (perhaps using some ascii->unicode helper at typing time) and further enhancing it with this kind of tool...
Version control. If I add an ASCII art diagram to a text document, I can git diff it, and see that the ASCII art diagram was added. If my documentation is is in PDF, I can keep it in version control, but I lose a lot of the advantages that version control provides because PDF is a binary format.
I agree, it's kind of a one-time affair too because if you ever need to add or change a word in a node, you're fcked and have to edit ascii to change borders and lines and what not. There are way better ways to spend your time than to draw an ascii diagram.
I've only been using it for a few seconds, so I don't know if I'm off-base here, but isn't that what the third-to-last icon at the top does (box with diagonal arrow)?
Well, the only worst think would be to have to launch Visio, Powerpoint or whatever and then export and then re-embed.
Especially if you want to fix something done by someone else so you only have the image and not the binary... Also, versioning.
There are literally dozens of examples of text-based markup tools that are cross-platform, version-controllable, and can be rendered in a terminal if you're into that, and which don't require me to waste time drawing ridiculous ASCII art borders to denote logical relations.
I think all editors can read in the results of an external program, which might be a better solution. For example, the par text reformatter. Vim doesn't know a thing about it, but it will feed selected text to it, and replace it with results.
So for ascii diagrams, you might have an external program that generates, at least, various kinds of boxes and connectors, then you could edit the labels from the editor. Bonus if the external ascii diagram generator would take labels associated with entities.
Maybe that's an additional feature for Markdeep, or maybe it's a specific itch for someone else to scratch.
Nice setup, but its very cumbersome to write graphs in ascii, i prefer DOT if i dont care about layout too much, otherwise i use gliffy or something like that. For simple diagrams this is nice. However i think the main reason to use this is not diagrams. However then i think its better to use Markdown since most people know that.
The author seems very proud of the automatic-rendering JS they've written, and it's kind of cute but personally I'd much rather a batch-conversion tool.
On the other hand, that ASCII-art-to-SVG conversion is golden, and I'd absolutely love to have that supported in my API docs and blog-posts.
It would probably be trivial to pre-process the text with the script if you wanted to - at the end of the day it has to just be outputting DOM elements.
I for one love that it doesn't require a preprocessing step, because it means that any text file can easily be rendered without any need to do anything else.
Fantastic job OP, I think this is really awesome. Would be perfect if this was integrated with github - I would do all my readmes with this.
After 10 seconds of inspection: no, not a good idea, don't think this solves a nice problem.
Speaking as a PL & s-exp guy, I don't really have a problem writing
(bullets
(item "pick up milk")
(item "drop off desk"))
... but at the end of the day, I see that I can convey the same structure in a clearer way using markdown. Markdown is lovely because it's the thinnest possible skin over the structure; you can immediately see what structure the syntax is attaching. (Yes, there's still some parsing nastiness around paragraphs). This thing, though, doesn't have that "brilliant solution to a simple but really important problem" feel to it. I don't see this catching on.
Of course, I said the same thing about the internet in the spring of 1993.
I don't think this is the right way to look at this. They both transform to the most sensible html given the input.
If you want to use an underline for emphasis instead of cursive, this is more of a style concern than anything else, so the appropriate place to change this would be in the stylesheet, which is perfectly possible.
If you specifically want it to output the <u> html tag, I agree that this is not as convenient.
> They both transform to the most sensible html given the input.
I'm going to have to disagree with you. Long before Markdown came along, the convention was to use asterisks for * bold *, slashes for /italics/ and underscores for _underlined_ text. And that's just for starters.
Those three examples perfectly convey the intended effect, quite unlike the Markdown versions where asterisks will somehow imply italics, but only if they're single asterisks? It's a strange thing!
The point is that bold, italics, underline are all a property of the style, but not intent. The intent is "emphasis". How emphasis is rendered is dependent on the stylesheet.
That's because underlining is inferior typography. It's from back in the typewriter days when the only way to add emphasis was to back up and put underscores underneath the text. Either bold or italic is more preferable.
That's well and good, but the reason that it is appropriate when using a pen on printed text is that the vast majority of people don't differentiate their penmanship when representing emphasized text.
Historically underlined content == actionable hyperlink; for content that is intended for public consumption (ie. not a note that you're writing for your own use) there are usability issues with typographic styles that represent emphasis with an underline.
I am thinking of using this for my personal website.
It has been a while since I have had to think about licenses, and I am having trouble thinking this one through.
Markdeep is open source. You may use, extend, and redistribute Markdeep without charge under the terms of the BSD license:
...
Markdeep includes markdown.js, so you are also bound by the MIT license (which is BSD-compatible):
...
...and the highlight.js BSD license:
If I understand correctly that means I have to serve all three licenses in my HTML?
It's reasonably common for LaTeX documents to use PSTricks or PGF/TikZ or Asymptote to specify diagrams as text, within the main document. However, these use textual descriptions of diagrams, rather than ASCII-art pictures of them.
I think before there were GUI tools for editing ladder diagrams [0], there were tools that would read ASCII-art diagrams, and program PLCs with the corresponding logic. However, a quick Google didn't give a source confirming this.
DrawIt for Vim: http://www.vim.org/scripts/script.php?script_id=40 . I think I started using this in the previous millennium, and if not, not much later. It's awesome. Not all (former) coworkers agree with that sentiment though, to be honest.
Two other tools that render images from ascii are ditaa (http://ditaa.sourceforge.net/) and plantuml (http://plantuml.com/). Those tools, some scripts to render and combine markdown and images, and DrawIt (+ some other vim tools like 'boxes' (not sure if that still has a web page), 'sketch.vim' and 'boxdraw') make for the least painful, versionable documentation system, for me. ('least painful' in the sense that I still need to code way too much to get it all to work, but there isn't anything ready-made and stable enough that I have been able to find the last decade).
This looks pretty sweet!
(On a sidenote, I'm trying to figure out whether making the documentation look like daringfireball.net was intentional or not.)
That said, I'm OK with it degrading like that. The text file is perfectly readable, and conveys the information within quite well. I even kind of preferred it.
So, yeah. Great job, OP.