[Issue 16112] Replace ddoc with markdown

[Issue 16112] Enhance ddoc with more markdown support

Aug 19, 2016

greenify

Aug 20, 2016

Marco Leise

Aug 20, 2016

greensunny12@gmail.com

Sep 07, 2021

Basile-z

https://issues.dlang.org/show_bug.cgi?id=16112 Andrei Alexandrescu <andrei@erdani.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |andrei@erdani.com --- Comment #1 from Andrei Alexandrescu <andrei@erdani.com> --- Does markdown allow defining macros? --

https://issues.dlang.org/show_bug.cgi?id=16112 ZombineDev <petar.p.kirov@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |petar.p.kirov@gmail.com --- Comment #2 from ZombineDev <petar.p.kirov@gmail.com> --- Andrei, I think the idea is to add markdown support to the existing ddoc feature set. That way the following documentation features: 1. Headers 2. Lists (ordered and unordered) 3. Links & imagss 4. Emphasis 5. Tables would be be easier to use, than using ddoc macros. At the same time, by keeping the existing ddoc macro engine we'll still support the more advanced use cases (like LaTeX). --

https://issues.dlang.org/show_bug.cgi?id=16112 Jacob Carlborg <doob@me.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |doob@me.com --- Comment #3 from Jacob Carlborg <doob@me.com> --- (In reply to ZombineDev from comment #2) > Andrei, I think the idea is to add markdown support to the existing ddoc feature set. That way the following documentation features: > > 1. Headers > 2. Lists (ordered and unordered) > 3. Links & imagss > 4. Emphasis > 5. Tables > > would be be easier to use, than using ddoc macros. > At the same time, by keeping the existing ddoc macro engine we'll still > support the more advanced use cases (like LaTeX). There are already a few features from Markdown implemented, like `` for inline code. --

https://issues.dlang.org/show_bug.cgi?id=16112 --- Comment #4 from ZombineDev <petar.p.kirov@gmail.com> --- (In reply to Jacob Carlborg from comment #3) > > There are already a few features from Markdown implemented, like `` for inline code. I think backticks are the only one (that's why I didn't mention it). --

https://issues.dlang.org/show_bug.cgi?id=16112 Sobirari Muhomori <dfj1esp02@sneakemail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Hardware|x86_64 |All OS|Linux |All --- Comment #5 from Sobirari Muhomori <dfj1esp02@sneakemail.com> --- Consider sections. Markdown ## License Boost 1.0 (can be confused with an ordered list) License ======= Boost 1.0 (ugh, 3 lines) Wiki == License == Boost 1.0 (pretty readable) ddoc License: Boost 1.0 One line and readable! --

https://issues.dlang.org/show_bug.cgi?id=16112 --- Comment #6 from Andrei Alexandrescu <andrei@erdani.com> --- (In reply to ZombineDev from comment #2) > Andrei, I think the idea is to add markdown support to the existing ddoc feature set. Then please change the title of the issue, thanks. > That way the following documentation features: > > 1. Headers > 2. Lists (ordered and unordered) > 3. Links & imagss > 4. Emphasis > 5. Tables > > would be be easier to use, than using ddoc macros. Some of these would be nice but add only marginal value. --

https://issues.dlang.org/show_bug.cgi?id=16112 Marco Leise <Marco.Leise@gmx.de> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |Marco.Leise@gmx.de --- Comment #7 from Marco Leise <Marco.Leise@gmx.de> --- Some may have noticed on the forums that Ferdinand Majerech modified Brian Schott's harbored (https://github.com/kiith-sa/harbored-mod) which is DDoc with all the MarkDown features that don't collide with existing DDoc syntax. Sociomantic is switching over to that according to a prominent employee. I think because it extends the syntax rather than replacing it, it provides a smooth, gradual switch-over experience - although I'm not speaking out of experience. Everyone interested in more MarkDown can use that instead of pure DDoc today and gather some intel. Maybe even those not interested in it, to see if it would break anything for them. --

August 20, 2016

[Issue 16112] Enhance ddoc with more markdown support

Posted by greensunny12@gmail.com

Permalink

greensunny12@gmail.com

Permalink

https://issues.dlang.org/show_bug.cgi?id=16112

--- Comment #8 from greensunny12@gmail.com ---
> although I'm not speaking out of experience. Everyone interested in more MarkDown can use that instead of pure DDoc today and gather some intel. Maybe even those not interested in it, to see if it would break anything for them.

tl:dr: imho in the best case this will lead to a fragmentation as once you start using the full set of Markdown in your documentation, you can't switch back.

Full text:
----------

I can speak out of experience as we tried _all_ available solutions for Mir, here's a selection of the top five:

- ddox  (https://github.com/libmir/mir/pull/150)
- bootDoc (https://github.com/libmir/mir/pull/126)
- ddoc (https://github.com/libmir/mir/pull/203)
- harbored: http://docs.mir.dlang.io/harbored/
- adrdox (https://github.com/libmir/mir/issues/32)

A couple of general points:
---------------------------

(warning: this is a small rant)

- the documentation ecosystem is horrible (except for ddox none of these tools
are easy to setup)
- it's pretty damn hard to get something visually appealing
- using custom macros and features of a documentation engine lock one into the
setup
- Imho the reason that no good predefined themes and macros for Ddoc exist is
because (1) it's pretty difficult to hack, (2) because all time is spent on
building tools to avoid Ddoc
- If a project has some kind of documentation, it usually maintains its own
docs engine

-> in the end we cloned dlang.org and patched it, s.t. we can use the setup for
Mir
(http://docs.mir.dlang.io/latest/index.html) and have a similar setup to
Phobos, which was in our case important, because some modules of Mir are
intended to be part of Phobos eventually (after testing them in the wild).

However the patched Makefile (https://github.com/libmir/mir/blob/master/doc/Makefile) looks still really messy & I would love to dump it in favor of ddox.

--

Forums