News for hackers. Stuff that matters.
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @08:03AM (#17686517)
Markdeep has some very nice features. I love to be able to have more expressiveness than in regular markdown.

But I am not so sure about the diagramming feature. Writing diagrams as ascii art seems like a PITA to me, especially when you need to update a diagram with new shapes, etc.

For this I prefer PlantUML markdown integration: http://plantuml.com

I use VS Code and it has a nice plugin to handle this.

Re:Markdeep markup language by shitloadofbooks on Saturday August 04, 2018 @12:39PM (#17687493)
We had a really bad experience with PlantUML (as a Confluence plugin) ~2 years ago: https://github.com/plantuml/plantuml/issues/25.

(Also, this: https://github.com/plantuml/plantuml/pull/94)

Something to keep in mind.

Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @02:02PM (#17687820)
wtf?? Wow, thanks for these pointers. I have not run into any trouble, but these are some bad coding practices. At least they are in the process of addressing them all :)
Re:Markdeep markup language by nhh9000 on Saturday August 04, 2018 @01:05PM (#17687592)
Shameless plug:

I have been working on a tool like markdeep but with PlantUML-like syntax. It's here: http://markdown.online

The syntax help page is a kitchen-sink of what's supported: http://markdown.online/view/public/syntaxhelp

Planning on supporting more than sequence and flowcharts, but for now that's what I have.

Please note, this is not ready yet for prime time, it's alpha quality at best.

Finally, I think there is a place for a tool like Markdeep. There is only so much expressiveness that a tool like mine can support. Yes, ascii art to diagrams is PITA, but it is the most generic solution if you want diagrams with flexibility. I find my tool and tools like PlantUML to fit in the other end of the spectrum, you want a quick diagram without much fussing over how it really looks.

Re:Markdeep markup language by BLanen on Saturday August 04, 2018 @04:47PM (#17688361)
Bit weird that on such a 'static' website, the pages don't render without javascript.

Are you doing the rendering completely client side?

>you want a quick diagram without much fussing over how it really looks.

It's also way easier to edit and collaborate with. Could even be version controlled in a source-code way.

Re:Markdeep markup language by nhh9000 on Saturday August 04, 2018 @06:25PM (#17688718)
Everything is rendered on the clientside, yes. One of the big issues right now is that one of the libraries which I use for layout (ELK.js) weighs in at 3MB which is huge (and most of the code is unused). But re-implementing it all from scratch is quite a bit of work, and I need to pick between perfect and getting something done. :)

> It's also way easier to edit and collaborate with. Could even be version controlled in a source-code way.

Overall idea is to make this into a wiki. I am also planning to add an ability to collaboratively edit the same page (like google docs).

In terms of version control, yes, also thought about it. It's a bit more complex, and I don't have a good architecture as a solution at the moment.

Re:Markdeep markup language by scott113341 on Saturday August 04, 2018 @01:55PM (#17687792)
Monodraw is the best application I've found for ASCII (and Unicode) diagramming: https://monodraw.helftone.com
Re:Markdeep markup language by jkabrg on Saturday August 04, 2018 @10:04AM (#17686887)
What about freehand drawn diagrams? It seems pretty fast and intuitive, and would deal with your problem* . Are there any tools for making freehand diagrams look professional? It would be analogous to how Markdown makes "crude" text look "professional".

* As long as you have good coordination.

Re:Markdeep markup language by paultopia on Saturday August 04, 2018 @11:50AM (#17687291)
This is an interesting idea---how hard would it be to do this? It might be as simple as doing k-means on the pixels or some other kind of clustering algorithm, and then fitting a spline curve to each cluster...
Re:Markdeep markup language by hawski on Saturday August 04, 2018 @10:34AM (#17686990)
A ruler would make a difference. Maybe also using something at least a level or two better than cheapest ball point pen available. Those and a bit of calligraphy exercises.
Re:Markdeep markup language by hobo_mark on Saturday August 04, 2018 @12:12PM (#17687385)
I do all my markup, including diagrams (PlantUML and more), in AsciiDoc and I have yet to find a good reason to switch to one of the many markdowns.
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @12:28PM (#17687447)
Yes, I am considering to switch to AsciiDoc in future. Does Github have proper support, or do you have to write in a subset?
Re:Markdeep markup language by geraldcombs on Saturday August 04, 2018 @02:28PM (#17687925)
Asciidoctor is in the supported markup list in the GitHub Markup README[1], which means you might need to enable compat-mode for strict AsciiDoc syntax support. The Asciidoctor repository's README.adoc renders just fine[2].

[1] https://github.com/github/markup [2] https://github.com/asciidoctor/asciidoctor

Re:Markdeep markup language by jtbayly on Saturday August 04, 2018 @11:35AM (#17687228)
I could never write that diagram in ASCII. My brain is unable think in lines like that or something.
Re:Markdeep markup language by SahAssar on Saturday August 04, 2018 @05:27PM (#17688496)
Mermaid.js has worked pretty well for me and has vscode plugins: https://mermaidjs.github.io/
Re:Markdeep markup language by sudeepj on Saturday August 04, 2018 @08:15AM (#17686560)
Yeah, if there are merge conflicts within the ascii charts then it is even more PITA.
Re:Markdeep markup language by asah on Saturday August 04, 2018 @09:59AM (#17686863)
PlantUML looks neat! Great for design docs
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @10:32AM (#17686979)
Yes, it is a very easy text-only format, and with that VS Code plugin you see the rendered diagram updated in real-time in the preview panel.

  ```plantuml
  @startuml
    :Actor: --> (UseCase)
  @enduml
  ```
Re:Markdeep markup language by tannhaeuser on Saturday August 04, 2018 @12:46PM (#17687516)
To go beyond generic Wiki syntax, SGML lets you define context-specific token replacement rules. For example, to make SGML format a simplistic markdown fragment into HTML, you could use an SGML prolog like this:

    <!DOCTYPE p [
      <!ELEMENT p - - ANY>
      <!ELEMENT em - - (#PCDATA)>
      <!ENTITY start-em '<em>'>
      <!ENTITY end-em '</em>'>
      <!SHORTREF in-p '*' start-em>
      <!SHORTREF in-em '*' end-em>
      <!USEMAP in-p p>
      <!USEMAP in-em em>
    ]>
    <p>The following text:
       *this*
       will be put into EM
       element tags</p>
Re:Markdeep markup language by eponeponepon on Saturday August 04, 2018 @05:04PM (#17688421)
How does the parser distinguish between in-p and in-em to substitute in the corresponding entities? It seems to me that when it reaches the second asterisk it's not going to be able to know whether to open or close the em element.

Is this one of those pieces of occult witchery that SGML excels at..?

Re:Markdeep markup language by tannhaeuser on Saturday August 04, 2018 @05:40PM (#17688550)
If the context (top-most) element is "em", the "in-em" shortref map is current (as per the second USEMAP declaration), which defines the replacement text for "*" to be "</em>", ending the emphasized text span. Whereas within "p", it's "<em>", starting an emphasized text span, and making "em" the context element.
Re:Markdeep markup language by agumonkey on Saturday August 04, 2018 @02:12PM (#17687862)
so XML removed the best part of SGML..
Re:Markdeep markup language by JadeNB on Saturday August 04, 2018 @02:37PM (#17687967)
XML was always intended more for machine than for human consumption. It's easier for machines to consume extremely regular syntax, so that's what XML has.
Re:Markdeep markup language by agumonkey on Saturday August 04, 2018 @05:07PM (#17688435)
unfortunately it had its time as a pseudo programming language period..
Re:Markdeep markup language by JadeNB on Saturday August 04, 2018 @06:18PM (#17688689)
> unfortunately it had its time as a pseudo programming language period..

You are quite right. I should probably have said something more like "XML was intended by its creators more for machine than human consumption" (and, incidentally, creation; I think I have read that XML construction wasn't really intended to be done by humans either).

Re:Markdeep markup language by quink on Saturday August 04, 2018 @05:13PM (#17688452)
There’s XSLT Markdown to HTML converters out there. And while XSL isn’t XML, it is in every browser and available next to XML in near enough everything else.
Re:Markdeep markup language by Mikhail_Edoshin on Sunday August 05, 2018 @04:51AM (#17690395)
Yes, it's not only everywhere, it's nothing less than a second programming language for the web, although very much neglected :)
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @08:44AM (#17686648)
Something I haven't seen in any markdown editor so far (suggestions welcome) is extended table support.

Say I have a table with a 'name' and 'value' column and 100 entries. And I'd like names to be alphabetically sorted. So far so good.

But this table is too long and too small, so I want to have 4 columns and 50 rows, where the name/value continue in column 3, 4. Out of luck. This is unmanageable, as you have to shift many cells when adding a new entry.

A proposal for something like this: https://github.com/github/markup/issues/1189

Also mentions multi-line cell contents, which are hard in regular markdown (require inline html)..

Re:Markdeep markup language by dustingetz on Saturday August 04, 2018 @09:51AM (#17686837)
Markdown doesn't compose very well, you kind of want to drop into a programming language for that

http://www.hyperfiddle.net/:docs/:cookbook!static-site-markd...

It can be abstracted into a function though, here's a different table done from only markdown (and backed by a database!)

http://www.hyperfiddle.net/:docs/:fiddle-markdown

Re:Markdeep markup language by duckerude on Saturday August 04, 2018 @09:07AM (#17686726)
I think Emacs's org-mode can do that, by offering an easy way to insert columns. It's not markdown, but at a glance, the table syntax seems compatible or close enough, so maybe copy/pasting to and from Emacs could do the job if you can stand Emacs.

org-mode's tables can do a lot of things.

https://orgmode.org/org.html#Tables

Re:Markdeep markup language by rcthompson on Saturday August 04, 2018 @10:41AM (#17687019)
I'm pretty sure Pandoc has an option to interpret org-mode style tables in Markdown files, and Org-mode itself has a mode for editing tables in non-org files. I haven't played with either, however, so I can't report on how well they work.
Re:Markdeep markup language by amai on Sunday August 05, 2018 @03:59AM (#17690271)
Hartl’s Tenth Rule of Typesetting:

"Any sufficiently complicated typesetting system contains an ad hoc, informally specified, bug-ridden, slow implementation of half of LATEX."

Markdeep is no exception.

http://manual.softcover.io/book/softcover_markdown#cha-softc...

Re:Markdeep markup language by s5ma6n on Saturday August 04, 2018 @12:09PM (#17687377)
Well the whole point of markdown is that it is simple enough so that devs easily document whatever necessary. As you know documentation is notoriously neglected by the developers. But this is not that simple. I doubt it will be adopted that much.
Re:Markdeep markup language by bnchrch on Saturday August 04, 2018 @12:22PM (#17687423)
I'm not sure you realize how many blogs and website are written using markdown.
Re:Markdeep markup language by alphakappa on Saturday August 04, 2018 @02:36PM (#17687959)
I think the parent's point is that markdown is simple, but markdeep is not.
Re:Markdeep markup language by mort96 on Saturday August 04, 2018 @03:49PM (#17688194)
I think your parent's point was that Markdown is used in a lot of situations where simplicity isn't as important as it is when documenting code.
Re:Markdeep markup language by sbjs on Saturday August 04, 2018 @11:28AM (#17687194)
I really like the idea of a new markup format. To me markdown has been very unintuitive in some ways. I can never remember whether more # means higher or deeper header level. Or which of - - - or === makes a first or second level header. But since markdown is first class citizen at github, I don’t think we’ll ever be able to see any real competition rise up (even though github has first class support for others, markdown is the clear winner). And I’ve never heard anyone else mention these confusions so maybe everyone else is fine with it and I’m the only one who wants an alternative.
Re:Markdeep markup language by throwaway0255 on Saturday August 04, 2018 @12:06PM (#17687362)
I think the biggest problem with Markdown is that the spec is ambiguous and there’s no clearly prevailing standard.

Jeff Atwood tried to fix this, but the creator of Markdown does not seem keen to cooperate with any attempts to standardize it.[1]

Since he owns the trademark, standardization will likely be impossible without his cooperation. Not to come down on John Gruber, I understand his position and he’s a cool cat... it’s just an unfortunate shortcoming of markdown, which I otherwise love.

With the exception of ordered lists. I can never figure out how to get multiple paragraphs or interstitial content into ordered lists, and it always resets the counter to 1... but everything else is great!

[1] https://blog.codinghorror.com/standard-markdown-is-now-commo...

Re:Markdeep markup language by type0 on Sunday August 05, 2018 @05:04AM (#17690431)
Asciidoc is a viable alternative. By now you have Asciidoctor in Ruby, AsciidoctorJ on JVM, Asciidoctor.js and even original Asciidoc Python recently rewritten for Py3.

https://github.com/asciidoctor/asciidoctor.org/blob/master/d...

Here is a very short intro on rendering in your browser: https://www.youtube.com/watch?v=4LOB3WeOUJk

Asciidoc.org at some time in the future should be the page for the language spec. The biggest feature is probably that you can produce DocBook and it's very easy!

Re:Markdeep markup language by castillar76 on Monday August 06, 2018 @12:36PM (#17699159)
We've been really happy with Asciidoc at work. We maintain multiple large versioned documents as a team and had been using Word and 'Track Changes' to do updates. We've now moved them entirely to Asciidoc and are using Git for tracking and approving changes, and the difference is night and day. We considered Markdown at the time, but things like numbered lists incorporating paragraphs, metadata inclusion, and the need to specify certain elements about the final published version meant that Asciidoc was a clear winner. To get all of those incorporated using Markdown would have meant implementing one of the Markdown dialects, and then ensuring that everyone's tool-chain that thought it spoke Markdown wouldn't then munge it to death.
Re:Markdeep markup language by j_4 on Sunday August 05, 2018 @06:42AM (#17690657)
Markdown isn't perfect, but I find it really weird that you complain about the headers in particular. I never use the underline style, but I don't think you can get more straightforward than the # notation.
Re:Markdeep markup language by geraldbauer on Saturday August 04, 2018 @01:48PM (#17687768)
I've been working on an evolved markdown format alternative - that removes some known failures such as image links e.g. ![]() and improves some such as links e.g. lets use wikipeda style links :-) and lets offer more link of syntax alternatives - and adds some stuff while trying to learn from the "real world", that is, getting the best of the world of wikipedia markup, markdown and latex all together and easy to use. The format is called texti short for text with (formatting) instructions. See https://texti.github.io for more.
Re:Markdeep markup language by akvadrako on Saturday August 04, 2018 @05:12PM (#17688449)
You don't have to remember that - it's up to you. Whatever markup you use for headings, the levels are inferred.
Re:Markdeep markup language by stewbrew on Saturday August 04, 2018 @06:16PM (#17688682)
I really wish people would simply forget about markdown and restart with a slightly more sensible and extensible markup. I personally always thought that some sort of latex/context with a simple markup for common commands would be more useful.
Re:Markdeep markup language by paultopia on Saturday August 04, 2018 @09:44AM (#17686806)
This sounds pretty cool. My own workflow is so pandoc-dependent though that I don't think I could use it unless someone who is much better at Haskell than I am works the markdeep extensions into pandoc :-(
Re:Markdeep markup language by fernly on Saturday August 04, 2018 @08:16PM (#17689043)
The day I find one of these mark* languages that supports poetry -- which simply means, a section in which it respects literal indents and line-breaks, but not by dropping into monospace font -- I'll use it.

N.B. the online publishing platform Leanpub has its own mark* variant, "markua"[1] which actually does recognize a poem section -- although as implemented it has minor formatting issues.

[1] https://leanpub.com/markua/read

Re:Markdeep markup language by ramses0 on Saturday August 04, 2018 @11:49PM (#17689568)
I've put together a book of poetry using CLI/markdown-ish tools. pandoc make texlive-xetex is what's in the Dockerfile that builds it. If you contact me directly I'd be willing to share how far I've gotten with the problem.
Re:Markdeep markup language by transfire on Saturday August 04, 2018 @10:23PM (#17689375)
I think anyone would agree that Markdown the sna bit too simplistic, and while Markdeep looks cool, it seems like it ends up at the opposite extreme with too much complexity.
Re:Markdeep markup language by ivanceras on Saturday August 04, 2018 @11:35AM (#17687223)
Re:Markdeep markup language by disqard on Saturday August 04, 2018 @12:51PM (#17687537)
Very cool. Thank you for making and sharing this!
Re:Markdeep markup language by dang on Saturday August 04, 2018 @02:10PM (#17687859)
Re:Markdeep markup language by writepub on Saturday August 04, 2018 @02:36PM (#17687964)
Shameless plug: http://write.pub supports most of the features of MarkDeep, and allows WYSIWYG writing.

It also shows with built in version control, you don't have to know git to use it

Re:Markdeep markup language by medntech on Saturday August 04, 2018 @04:37PM (#17688337)
Is this just a wrapper for tui.editor?
Re:Markdeep markup language by writepub on Saturday August 04, 2018 @05:59PM (#17688607)
The editor is indeed TUI. But TUI doesn't support editing/saving local files, which write.pub allows.

There are multiple other features, like WYSIWYG diff and version control that make this app compelling

Re:Markdeep markup language by medntech on Saturday August 04, 2018 @06:09PM (#17688647)
That's awesome! I'm a huge fan of tui so I was curious.
Re:Markdeep markup language by theshadowknows on Saturday August 04, 2018 @04:26PM (#17688310)
Is there some way of doing 3D diagrams?
Re:Markdeep markup language by janaagaard on Saturday August 04, 2018 @10:04AM (#17686883)
Justified margins?
Re:Markdeep markup language by nkkollaw on Saturday August 04, 2018 @02:46PM (#17687994)
Markdown is cool because it's minimalistic.

Markdeep might be a good idea, but if you start adding more and more feature you reimplement HTML, at that point why not simply use HTML? Isn't HTML plain text, too?

Re:Markdeep markup language by bausshf on Wednesday August 08, 2018 @07:18AM (#17714889)
This was my thought when I saw the example on the frontpage with styling