Fix Issue 17121 - DDoc documentation is out of date

[wilzbach]

Not really sure on the best course of action here. Just dumping the entire file with all its stylesheets feels wrong.

The new predefined macros are in a separate file [1]. Is it possible to embed that in the rest of the Ddoc documentation?

@jacob-carlborg I guess you would like to be able to preprocess DDoc, e.g. #1688?

CC @acehreli

[dlang-bot]

Fix	Bugzilla	Description
✓	17121	DDoc documentation is out of date

[jacob-carlborg]

jacob-carlborg I guess you would like to be able to preprocess DDoc, e.g. #1688?

I'm not sure what you mean with preprocess Ddoc. #1688 suggests to use Ddoc comments but there are no Ddoc comments. If the Ddoc document are but in comments as is, the compiler would evaluate the macros. I'm thinking of if there's some way to escape the whole Ddoc default theme document to be able to render that on the site.

[wilzbach]

. #1688 suggests to use Ddoc comments but there are no Ddoc comments.

#1688 allows to evaluate D code and inject arbitrary variables into you the Ddoc template, i.e. it makes proper templates out of the Ddoc files, e.g. on the D site you could do sth. like this:

context["DDOC_COMPILER_TEMPLATE"] = "default_ddoc_theme".readText.rescapeDdoc;

and then in the Ddoc file:

...
{{ DDOC_COMPILER_TEMPLATE }}
...

If the Ddoc document are but in comments as is, the compiler would evaluate the macros.

You can escape it manually as well, but I thought the main point of this issue was to automatically keep the specification in sync?

[jacob-carlborg]

Aha, cool. As long as it works 😃.

[CyberShadow]

Currently this change is not useful, and neither is embedding the entire HTML of the new theme. Probably the best course of action is to link to the file on GitHub. The wording needs change: avoid "current"; avoid "a bit"; link to $(LATEST); remove "enhanced and provides more options for styling".

IMO, the addition of the new DDoc theme was not executed correctly - the default theme should've been left as it was, and the new theme should've been shipped as a separate file that was parsed by default by the compiler, similar to object.d.

[jacob-carlborg]

IMO, the addition of the new DDoc theme was not executed correctly - the default theme should've been left as it was, and the new theme should've been shipped as a separate file that was parsed by default by the compiler, similar to object.d.

How is that different from now?

[CyberShadow]

How is that different from now?

I see that the DDoc theme is built into the DMD executable with an import expression; it would have been better to include it directly with the binary and make DMD load it at runtime, so that it's more transparent to the users. Also, I don't know of any way to get the old theme with a command-line switch.

[andralex]

Close this as superseded by #1805?

[jacob-carlborg]

Close this as superseded by #1805?

Fine by me.