Thread overview | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
August 19, 2016 [Issue 16112] Replace ddoc with markdown | ||||
---|---|---|---|---|
| ||||
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? -- |
August 19, 2016 [Issue 16112] Replace ddoc with markdown | ||||
---|---|---|---|---|
| ||||
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). -- |
August 19, 2016 [Issue 16112] Replace ddoc with markdown | ||||
---|---|---|---|---|
| ||||
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. -- |
August 19, 2016 [Issue 16112] Replace ddoc with markdown | ||||
---|---|---|---|---|
| ||||
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). -- |
August 19, 2016 [Issue 16112] Replace ddoc with markdown | ||||
---|---|---|---|---|
| ||||
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! -- |
August 19, 2016 [Issue 16112] Replace ddoc with markdown | ||||
---|---|---|---|---|
| ||||
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. -- |
August 19, 2016 [Issue 16112] Enhance ddoc with more markdown support | ||||
---|---|---|---|---|
| ||||
https://issues.dlang.org/show_bug.cgi?id=16112 greenify <greeenify@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |greeenify@gmail.com Summary|Replace ddoc with markdown |Enhance ddoc with more | |markdown support -- |
August 20, 2016 [Issue 16112] Enhance ddoc with more markdown support | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
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. -- |
September 07, 2021 [Issue 16112] Enhance ddoc with more markdown support | ||||
---|---|---|---|---|
| ||||
https://issues.dlang.org/show_bug.cgi?id=16112 Basile-z <b2.temp@gmx.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |RESOLVED CC| |b2.temp@gmx.com Resolution|--- |FIXED -- |
Copyright © 1999-2021 by the D Language Foundation