On 10/06/14 16:06, Andrei Alexandrescu wrote:

> I think ddoc is a lot more flexible than markdown, and I'm baffled by
> the claim that ddoc is difficult to learn. That said I do agree it's a
> turnoff for first-time website contributors. IMHO if we switch away from
> ddoc we should switch to something better, not something just different.

Something better/more powerful would be something backed by a proper programming language.

-- 
/Jacob Carlborg

Am 10.06.2014 16:06, schrieb Andrei Alexandrescu:
> On 6/10/14, 3:42 AM, Sönke Ludwig wrote:
>> * Are there any other opinions on this? I remember that there have been
>> some strong proponents of using DDOC for things, so it would be bad if
>> in the end Markdown were to be dropped, after all of the work has
>> already been done. Personally I'd strongly favor Markdown, though.
>
> I think ddoc is a lot more flexible than markdown, and I'm baffled by
> the claim that ddoc is difficult to learn. That said I do agree it's a
> turnoff for first-time website contributors. IMHO if we switch away from
> ddoc we should switch to something better, not something just different.
> -- Andrei
>

Markdown has the advantages of a semantic content representation - so while it doesn't have a flexible macro system, external processors can be used to transform it into any desired output format (including binary or white space sensitive formats).

But the key points for me would be better readability and its broad prevalence among the general developer community. One possibly major consequence of this is tool support. For example, GitHub has a built-in editor with preview for Markdown documents, so that anyone with a GitHub account can quickly edit page contents without having to clone or build the site.

Am 10.06.2014 14:31, schrieb Kiith-Sa:
> (But I'd recommend extended GitHub-like markdown if possible, plain
> markdown is pretty bare bones. Personally I use ReStructuredText but I
> think the GitHub markdown is pretty good and most potential contributors
> can already write it without learning a new format.

Agreed. The Markdown parser in vibe.d does support some of the GitHub extensions, but still lacks some useful things like tables.

On Tue, 10 Jun 2014 10:06:57 -0400, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:

> On 6/10/14, 3:42 AM, Sönke Ludwig wrote:
>> * Are there any other opinions on this? I remember that there have been
>> some strong proponents of using DDOC for things, so it would be bad if
>> in the end Markdown were to be dropped, after all of the work has
>> already been done. Personally I'd strongly favor Markdown, though.
>
> I think ddoc is a lot more flexible than markdown, and I'm baffled by the claim that ddoc is difficult to learn. That said I do agree it's a turnoff for first-time website contributors. IMHO if we switch away from ddoc we should switch to something better, not something just different.

Markdown can be instantly understood by anyone who sees it. DDOC requires lookup/learning, even if you know how DDOC works, you still have to figure out what all the macros mean and do. And none of that is documented as far as I know.

Flexibility isn't everything. The goal is to make it easy to be an author.

-Steve

On Tuesday, 10 June 2014 at 14:54:32 UTC, Steven Schveighoffer wrote:
> Markdown can be instantly understood by anyone who sees it. DDOC requires lookup/learning, even if you know how DDOC works, you still have to figure out what all the macros mean and do. And none of that is documented as far as I know.
>
> Flexibility isn't everything. The goal is to make it easy to be an author.

This. I use DDOC for actual documentation daily and still was reluctant to spend time on figuring out what all those macros mean and how to use those. Better spend time on something both interesting and useful.

Flexibility is hardly important at all here.

On Tuesday, 10 June 2014 at 14:50:51 UTC, Sönke Ludwig wrote:
> Am 10.06.2014 14:31, schrieb Kiith-Sa:
>> (But I'd recommend extended GitHub-like markdown if possible, plain
>> markdown is pretty bare bones. Personally I use ReStructuredText but I
>> think the GitHub markdown is pretty good and most potential contributors
>> can already write it without learning a new format.
>
> Agreed. The Markdown parser in vibe.d does support some of the GitHub extensions, but still lacks some useful things like tables.

I can definitely live without Markdown style tables. I'm happy enough to write HTML for that.

I thought I'd post an update on this work so I don't leave any people hanging who are wondering about this.

I haven't had the time in the last week or so to work on this as I have been very busy recently with other responsibilities. With my day job in particular, I will be in Berlin most of next week hosting a conference with my company. Because it's a small world, by pure coincidence Sociomantic are actually sponsoring this conference. (I doubt the marketing guys talk to the D programmers that much, though.)

http://www.performancemarketinginsights.com/14/europe/sponsor/sociomantic/

However, after I get back I will defintely work on this redesign some more. Unless somebody pins me down, I'll keep going with it. I only just realised that I made the terrible mistake of not pushing my most recent changes, so you can find them now on GitHub.

I started working on discovering Markdown files at runtime for filling in a sections of pages, like center part of changelog pages, and generating the table of contents from the HTML automatically. Because the prospect of parsing HTML myself scares me, I just copied in Adam D Ruppe's DOM library for that. I hope that I have properly attributed the authors for that code, please advise me if I should add any additional attribution in there otherwise.

The early result of that I think has been pretty good. I can edit a file and see a change pretty quickly. I lost the functions I was using to generating the Bugzilla links, but I'm going to replacing them with links to /bug/<id> instead, and making that page redirect to the right place, just so I can make my Markdown files a little smaller. The amount of memory consumed while compiling is better, going from something like 2GB to 1.2GB, because there aren't tons of Diet templates to build in anymore. The Markdown parsing is just the library functionality that comes with vibe.d.

I totally have not converted all of the pages from Diet to Markdown yet. In fact, if you run the site as is now, you can't see any of the changelog pages except 2.000 anymore. Plus, you could perhaps do something involving caching files instead of loading them from the drive all the time, but I just want something that works for now.

So there's my update for now.

I just finished translating all of the pages I have worked on so far from diet templates to Markdown files. Now there is only one diet layout loaded, and the rest is all Markdown files. This has dramatically reduced the amount of memory consumed at build time. You can see the results at the usual place at http://w0rp.com:8010 and view the source on GitHub. I'll keep at it and convert more pages from the main site.

On 6/29/14, 3:15 PM, w0rp wrote:
> I just finished translating all of the pages I have worked on so far
> from diet templates to Markdown files. Now there is only one diet layout
> loaded, and the rest is all Markdown files. This has dramatically
> reduced the amount of memory consumed at build time. You can see the
> results at the usual place at http://w0rp.com:8010 and view the source
> on GitHub. I'll keep at it and convert more pages from the main site.

This is looking really good!

On Sunday, 29 June 2014 at 22:15:48 UTC, w0rp wrote:
> I just finished translating all of the pages I have worked on so far from diet templates to Markdown files. Now there is only one diet layout loaded, and the rest is all Markdown files. This has dramatically reduced the amount of memory consumed at build time. You can see the results at the usual place at http://w0rp.com:8010 and view the source on GitHub. I'll keep at it and convert more pages from the main site.

Please use the correct logo and the correct colours. Branding is extremely important!

http://media.sukimashita.com/d/d-5.svg