3 ms·

If you'll indulge me for a moment, I have a story to tell: Many years ago, I had this idea of creating a documentation tool for my hobby projects that was base

If you'll indulge me for a moment, I have a story to tell: Many years ago, I had this idea of creating a documentation tool for my hobby projects that was based on Awk. I liked Doxygen, but it was a bit heavy duty for a small C library with only a handful of functions. You could almost guarantee that Awk would be available on the system where you might be compiling the project, so you could just bundle the awk script with your sources, add two lines to your makefile and have HTML documentation ready to go. Now I had never heard of Markdown at this time; It was before StackOverflow or GitHub was a thing (perhaps they existed, but I haven't used them yet). Therefore my syntax was a crude markup scheme that was difficult to explain and didn't always work correctly. Skip forward a couple of years and I had the bright idea to rewrite the script to rather use a Markdown syntax. This ended up being one of those hobby projects that you never really finish, and it grew organically to include all sorts of Markdown features. The result of that effort is now on GitHub [1]. Where does Markdeep fit into all of this? Sometimes when I stumble upon a project on GitHub that I find interesting, I click on the author's name to see what other repositories they have that looks interesting. One day I browsed GitHub like that and stumbled upon user r-lyeh's `stddoc.c` file [2]. It is a C program that simply extracts the comments from your source file and appends the Markdeep tags to the end. If you save the result to a HTML file, you achieve the same result as my script, except the implementation is much much simpler. I nearly fell off my chair when I realised that all the effort I put into my own script was basically made useless(*) by Markdeep. Instead of parsing the markdown, I could rather have had Markdeep do all the heavy lifting, and it comes with a bunch of very nice features that I doubt I'd ever be able to implement in my own script. [1]: https://github.com/wernsey/d.awk https://github.com/wernsey/d.awk [2]: https://github.com/r-lyeh/stddoc.c https://github.com/r-lyeh/stddoc.c

JadeNB 4y ago
> I nearly fell off my chair when I realised that all the effort I put into my own script was basically made useless(*) by Markdeep. Was there meant to be a following footnote (*)?
- wernsey 4y ago
  whoops, yes, it was supposed to be (*) my script strives for compatibility with GitHub-flavoured markdown, so you could do things like extract the markdown in your code comments to, say, a GitHub wiki, and the markdown flavour stays the same between your README.md and your code documentation. YMMV on whether this is actually a useful quality
ComputerGuru 4y ago
This is actually how the bundled, first-party rustdoc that ships with the rust compiler works. Triple slash /// comments above public API members are extracted as-is, rendered as markdown, cross-linked to one another, and rendered to HTML.

JadeNB 4y ago

> I nearly fell off my chair when I realised that all the effort I put into my own script was basically made useless(*) by Markdeep. Was there meant to be a following footnote (*)?

wernsey 4y ago
whoops, yes, it was supposed to be (*) my script strives for compatibility with GitHub-flavoured markdown, so you could do things like extract the markdown in your code comments to, say, a GitHub wiki, and the markdown flavour stays the same between your README.md and your code documentation. YMMV on whether this is actually a useful quality

ComputerGuru 4y ago

This is actually how the bundled, first-party rustdoc that ships with the rust compiler works. Triple slash /// comments above public API members are extracted as-is, rendered as markdown, cross-linked to one another, and rendered to HTML.