Comment #2 by petar.p.kirov — 2016-08-19T06:59:57Z
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).
Comment #3 by doob — 2016-08-19T07:57:19Z
(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.
Comment #4 by petar.p.kirov — 2016-08-19T08:29:14Z
(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).
Comment #5 by dfj1esp02 — 2016-08-19T10:42:04Z
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!
Comment #6 by andrei — 2016-08-19T13:46:42Z
(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.
Comment #7 by Marco.Leise — 2016-08-20T07:02:08Z
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.
Comment #8 by greensunny12 — 2016-08-20T18:25:47Z
> 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.