OpenBSD Journal
Home : : Add Story : : Archives : : About : : Create Account : : Login :
Comments

<< Re: New mandoc -mdoc -T markdown converter | Up: Re: New mandoc -mdoc -T markdown converter | Flattened | Expanded

Threshold: Help

  Re: New mandoc -mdoc -T markdown converter (mod 1/105)
by Ingo Schwarze (schwarze) on Wed Mar 8 20:44:09 2017 (GMT)
mdocml.bsd.lv
  > Did you consider targeting http://commonmark.org/

Not before implementing the output mode.

Because of your comment, i worked through the CommonMark specification, fixed about half a dozen bugs in my implementation where it violated CommonMark, and added a link to the mandoc(1) manual page.

The basic idea of the CommonMark project is laudable: consensus-based standardization as compatible with existing practice as possible, a reference implementation, and various testing tools.

Actually reading what they have so far, and what they consider almost finished, is not so much fun. The original idea of markdown was simplicity. The CommonMark specification is very long, very complicated, and in some places complicated to the point of absurdity. As the worst example, just read the long chapter about delimiter runs, which culminates in a list of seventeen (!!) precedence rules. Even though i inspected most of the rest, I'm not willing to study and implement that. It is plainly going over the top. There are various other examples of excessive complexity in the specification.

Ultimately, it only reinforces my point made in the Undeadly article above. The markdown language is utterly ill-designed from the ground up, and no standardization effort can cure the numerous ailments. It ought to be abandoned outright. DO NOT USE IT. If others force you to produce documentation in markdown, consider writing mdoc(7) instead and converting to markdown with mandoc. Comparing the CommonMark specification to the mdoc(7) manual, writing mdoc(7) is several orders of magnitude easier, and you get semantic rather than very primitive presentational markup.
  [ Show thread ] [ Reply to this comment ] [ Mod Up ] [ Mod Down ]

[ Home | Add Story | Archives | Polls | About ]

Copyright © 2004-2008 Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to April 2nd 2004 as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. Some icons from slashdot.org used with permission from Kathleen. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. Search engine is ht://Dig. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]