On 2015-12-17 00:43, BLM768 wrote:

> On the subject of "one's own ideas", here's mine, FWIW:
>
> First, my background thoughts. We seem to have four main "sections" of
> the site: the forums (built on DFeed), the wiki (built on MediaWiki),
> the language docs (DDoc), and the "main" site (in DDoc/HTML). The first
> three are using technologies which were explicitly designed for what
> they do, and they work quite nicely. The only thing left is the "main"
> site (the download page, articles, etc.), which doesn't fit into the
> models of the first two technologies and is somewhat clumsy for some
> people to edit because it's built on more than just "common" Web standards.

Exactly, this is spot on.

> I can think of a couple of ideas for making the main page more palatable
> to Web developers. One is to make as much of it as possible in plain old
> static HTML. Stuff like the articles rarely changes, after all.

This is an horrible idea. No sane person would use raw HTML. The only advantage is that it's HTML so there's documentation available.

> Another idea is to use a Web application framework. There's a significant
> advantage there: we can have one master "layout" template, and almost
> any content we want (forums, DDoc-generated HTML, static HTML, and so
> on) can be rendered in that template with relatively minimal code. There
> are lots of frameworks that shouldn't be hard to use. I'm sure that
> someone has already suggested doing it in vibe.d, and that probably got
> shot down due to a technical issue or something, but it would be
> interesting from a PR standpoint.

That's exactly what we should do. Ddoc already can do some of this, just not in a good way.

-- 
/Jacob Carlborg

On 2015-12-17 00:55, Walter Bright wrote:

> I've done that before, a lot. Ddoc cut the work involved in that in
> half, and I mean in half. It also made it easy to change the look of a
> whole site, rather than being a mess of tedium.
>
> No way I'm going back to that.

No sane person would use raw HTML. I hope no one takes that suggestion serious.

-- 
/Jacob Carlborg

On 2015-12-16 21:59, Andrei Alexandrescu wrote:

> If some of these are unnecessary, they can be easily fixed. There's no
> problem with breaking other people's code etc.
>
> Which would you eliminate?

A sane doc generation system would need at most two macros/syntaxes/functions to create links. One macro accepting a symbol name (fully qualified or not) used for cross-referencing and one macro used for page and external links, accepting a relative or an absolute URL.

It's also possible to manged without any of these at all. The doc tool could automatically do cross-referencing and detect URL's.

-- 
/Jacob Carlborg

On 2015-12-17 00:46, Andrei Alexandrescu wrote:

> Overall I think a few additions to the macro engine could be very
> beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to
> expand b if a is nonempty and c otherwise.

Oh, God, please no. Just use vibe.d and be done with it. We obviously need a proper programming language to generate dconf.org.

-- 
/Jacob Carlborg

On 2015-12-16 21:54, Walter Bright wrote:

> I'm not so sure. There are lots of tools to develop websites. Let's say
> A, B, and C. If we picked "B", we most assuredly would have analogous
> threads here saying "I won't use anything but A" and "Everybody else
> uses C."

Anything that is explicitly created for web development would be better.

> I've heard all sorts of excuses for decades about why people won't chip
> in, and I know they are excuses because when the excuse is fixed, they
> still won't chip in. This excuse sounds the same as the rest.
>
> The thing is, if you know html, then you know Ddoc. Ddoc is just a
> stupidly simple text-substitution macro system a programmer should be
> able to learn in a few minutes.

I know HTML, and I know there's no problem with underscores in HTML. Yet Ddoc is causing issues with underscores because Latex is used to generate the PDF [1].

[1] http://forum.dlang.org/post/n4tpdd$2kun$1@digitalmars.com

-- 
/Jacob Carlborg

On 2015-12-16 23:32, H. S. Teoh via Digitalmars-d wrote:

> This is a limitation of ddoc that needs to be fixed.  Historically,
> template functions used to be written like this:
>
> 	template amap(Args...)
> 	{
> 		auto amap(Args args) {
> 			implementation();
> 		}
> 	}
>
> Then a shorthand was introduced (the so-called "eponymous template"
> syntax), such that the above incantation could be abbreviated to:
>
> 	auto amap(Args...)(Args args) {
> 		implementation();
> 	}
>
> It would appear that ddoc came after eponymous templates became the
> norm, so currently, ddoc only understands ddoc comments attached to the
> latter syntax, while it fails to recognize that the former syntax is
> actually equivalent.  Several other functions in Phobos suffer from the
> resulting formatting disparity, IIRC map(), and maybe reduce(), and one
> or two others. It's rare enough that we don't encounter it very often,
> but the functions affected happen to be ones that are likely to be
> frequently used, so we really ought to fix this limitation in ddoc.

How would Ddoc know that you want to document the function and not the template? Just assume so if there's only one symbol in the template? It still needs to be possible to individually document the template and the function, and least when there's more than one symbol in the template.

-- 
/Jacob Carlborg

On Thursday, 17 December 2015 at 08:06:28 UTC, Jacob Carlborg wrote:
> On 2015-12-17 00:46, Andrei Alexandrescu wrote:
>
>> Overall I think a few additions to the macro engine could be very
>> beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to
>> expand b if a is nonempty and c otherwise.
>
> Oh, God, please no. Just use vibe.d and be done with it. We obviously need a proper programming language to generate dconf.org.

That would be a whole re-write of the website though.

It would be preferable of course. The official D site being run through one of it's more popular libraries (it's most popular library maybe?) can only be a good thing.

On 12/16/2015 11:49 PM, Jacob Carlborg wrote:
> I already help, and I use Ddoc, that's how I know it's crap ;).

You're not one of the people I was referring to, since you do help.

> I wrote the
> documentation for interfacing with Objective-C [1]. It was very frustrating,
> especially since the PDF generator broke because latex can't handle underscores
> as in "D_ObjectiveC". I did get some help in the pull request but not from
> someone that knew how this actually worked. It was most guesses.
>
> If a more widely tool had been used I might have been able to find out how this
> actually works and fixed it. Instead I had to revert to use a hack like wrapping
> the text in the $(D_CODE) macro.

Your issue with Ddoc is that the latex pdf generator you used was broken? Latex meets your critera as being very widely used. Use another pdf generator. Nobody has chained you to Latex.


> Of course, you will always have the issues you mention above. But if you choose
> a tool that is created for web design and is widely used you will most likely
> have less of these issues. Most importantly, when something doesn't work there's
> documentation online to get help from.

Amazon broke the PDF reader in their latest Kindle. I filed a bug report, but there's nothing I can do about it, and Amazon hasn't/won't fix it. They've sold millions of the things.

Jacob, I've adapted several books for Ddoc on their way to being Kindle ebooks. Ddoc works fine for the formatting. The WORK is simply not the formatting, it's the text creation/editting. If you're spending the bulk of your time fiddling with Ddoc rather than text creation, I suspect you've gone off the rails somewhere.

On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote:
> Having said that, though, using ddoc for the website leads to other
> problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the
> associated relative/absolute URL nightmare that a proper web authoring
> system would have taken care of by default).

Annoying, and maybe you have to spend a couple minutes picking the right one if you've forgotten for the moment => absolute nightmare? Come on.

On Thursday, 17 December 2015 at 08:15:49 UTC, wobbles wrote:
> That would be a whole re-write of the website though.

We could of course also use ddoc and write a generator to whatever template language we like. The rest is peanuts.