# Scdoc vs. asciidoc **URL:** \ **Category:** Off Topic\ **Tags:** language\ **Created:** [August 25, 2019, 6:32pm UTC](https://discuss.kakoune.com/t/scdoc-vs-asciidoc/694 "2019-08-25T18:32:03Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![robertmeta](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/robertmeta/32/833_2.png) [@robertmeta](https://discuss.kakoune.com/u/robertmeta)\ **Post date:** [August 25, 2019, 6:32pm UTC](https://discuss.kakoune.com/t/scdoc-vs-asciidoc/694/1 "2019-08-25T18:32:03Z")
[https://drewdevault.com/2018/05/13/scdoc.html](https://drewdevault.com/2018/05/13/scdoc.html) – possibly this would fit better with the goals of Kakoune? ---
**Author:** ![andreyorst](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/andreyorst/32/29_2.png) [@andreyorst](https://discuss.kakoune.com/u/andreyorst)\ **Post date:** [August 25, 2019, 6:57pm UTC](https://discuss.kakoune.com/t/scdoc-vs-asciidoc/694/2 "2019-08-25T18:57:27Z")
I’ve always thought why manpages are not simple plaintext? the `_underline_`, `/cursive/`, `*bold*` notations exist for years going way before Unix birth date. If you need to generate beautifully rendered pages or PDFs that’s not feasible, but for simple terminal manual pages I don’t know if you need more than that. I also think that a good manual should have the information necessary to understand the tool, not beautiful look. Otherwise we would use LaTeX ![img](https://discuss.kakoune.com/uploads/default/original/1X/dcb319db6337a6e352b707273444889a7144cb63.png). ---
**Author:** ![Screwtapello](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/screwtapello/32/12_2.png) [@Screwtapello](https://discuss.kakoune.com/u/Screwtapello)\ **Post date:** [August 26, 2019, 5:22am UTC](https://discuss.kakoune.com/t/scdoc-vs-asciidoc/694/3 "2019-08-26T05:22:00Z")
The HTML document model is pretty generic, so Markdown can get away with being a pretty generic [pidgin](https://www.merriam-webster.com/dictionary/pidgin). People who have written HTML long-hand (or not-very-simplified HTML variants like phpBB’s BBCode) fall in love with Markdown because 90% of the time it just does the right thing. The problem comes when people try to extend the Markdown model to more complex document models, like DocBookXML, or mdoc, or whatever. Then there’s a few basic approaches you can take: - Keep the markup simple, at the cost of making poor documents in the target format (scdoc, whatever syntax HN comments use) - Keep the markup simple for simple things, but more complex things require much more complex markup (AsciiDoc, maybe BBCode) - Keep the markup regular and consistent, at the cost of simple things feeling over-complicated (ReStructuredText) I’m probably always going to use Markdown for any kind of HTML prose, but for technical writing I’d probably go for ReStructuredText, and for manpages honestly mdoc is not nearly as complex as people make out, and it’s _really easy_ to test. > [@andreyorst](#): > > If you need to generate beautifully rendered pages or PDFs that’s not feasible, but for simple terminal manual pages I don’t know if you need more than that. Unix was originally sold as a document typesetting system, and came with binders full of printed-out documentation, generated by that typesetting system (troff). The fact that the source code for those documents was also installed, and could be read without printing it out, was more of a happy bonus, it’s definitely not how the documentation was _intended_ to be read. ---
**Author:** ![Delapouite](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/delapouite/32/10_2.png) [@Delapouite](https://discuss.kakoune.com/u/Delapouite)\ **Post date:** [August 26, 2019, 12:30pm UTC](https://discuss.kakoune.com/t/scdoc-vs-asciidoc/694/4 "2019-08-26T12:30:05Z")
Here’s the scdoc’s doc written in scdoc: [https://git.sr.ht/~sircmpwn/scdoc/blob/master/scdoc.5.scd](https://git.sr.ht/~sircmpwn/scdoc/blob/master/scdoc.5.scd)