On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright wrote:
> I've done that before, a lot. Ddoc cut the work involved in that in half, and I mean in half.

So does a simple `cat head.html body.html foot.html > output.html` loop. There's plenty of ways to achieve this.

On Wednesday, 16 December 2015 at 23:49:52 UTC, Andrei Alexandrescu wrote:
> But I dislike typing HTML. DDoc improves on that significantly.

Fair enough. Vibe.d has diet templates, though. They're pretty nice.

As long as the pages are mainly static anyway, though, it's all plain boring HTML to the client no matter what's used on the back end.

> Ironically Ddoc does exactly that, and quite nicely.

I thought about that, too. It's great for static content, but doesn't dynamic content become kind of tricky? Given that the forum sidebar operates differently from the main page sidebar (most noticeably in the giant image link at the top), I'd guess that it's not using the same DDoc template. (I haven't looked at the source, though.) Of course, it would need custom template code for the forum menu, so there's really not much to share with the main site...

On 12/16/2015 3:49 PM, Andrei Alexandrescu wrote:
> On 12/16/2015 06:43 PM, BLM768 wrote:
>> 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.
>
> Ironically Ddoc does exactly that, and quite nicely.

It also takes a bit of using it to realize that.

On 12/16/2015 4:04 PM, Adam D. Ruppe wrote:
> On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright wrote:
>> I've done that before, a lot. Ddoc cut the work involved in that in half, and
>> I mean in half.
> So does a simple `cat head.html body.html foot.html > output.html` loop. There's
> plenty of ways to achieve this.


Give me some credit, Adam :-)

On 12/16/2015 3:18 PM, Andrei Alexandrescu wrote:
> On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote:
>> Also, the lack of flexibility in number of macro arguments means you end
>> up with LINK, LINK2, LINK3, etc., with no obvious indication what the
>> difference is and where you should use which macro.
>
> (Well the obvious indication is the number innit :o).)
>
> A _simple_ way to handle arity might be worth adding to ddoc. Any ideas?

Note that Ddoc macros already support CDR/CAR. These are already used to great effect with the TROW macro. I suggest exploring this before new features.

On Wednesday, 16 December 2015 at 15:19:12 UTC, Adam D. Ruppe wrote:
> On Wednesday, 16 December 2015 at 13:49:22 UTC, Andrei Alexandrescu wrote:
>>> One still most likely need to build the site, which is kind of a pain to
>>> do.
>>
>> Building the site mimicks building dmd, druntime, and phobos. It's an invocation of make. What are the difficulties? -- Andrei
>
> Building dmd, druntime, and phobos is a big pain in the butt too.
>
> To check a change to the documentation right now, you first need to download and build git dmd (which depends on an existing dmd). Then druntime and phobos with it. Only then are you in a position to build the website since it depends on running the compiler over phobos which often depends on bleeding edge dmd.
>
> Maybe that's easy if you're already running bleeding edge everything, but it is an awful lot of process when you just want to eyeball a quick visual change.
>
> (and there's all the stuff about git branches being out of sync for me too because I'm a more casual contributor)
>
> When I make doc changes, I tend to just do it blind on the website and hope it works because it isn't worth spending half an hour setting up just to paste in an example or something.
>
>
> ...and then the auto-tester is awfully whiny so the pull request needs more adjustment and I'm left dropping f-bombs and vowing to never try contributing to upstream D again.

Indeed the effort required to make a simple change to the website is unacceptable.

Independent from the ddoc discussion, this could be solved with a server showing the code of a given page of the site, allowing editing and showing the resulting modification.

On 12/16/2015 07:04 PM, Adam D. Ruppe wrote:
> On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright wrote:
>> I've done that before, a lot. Ddoc cut the work involved in that in
>> half, and I mean in half.
>
> So does a simple `cat head.html body.html foot.html > output.html` loop.
> There's plenty of ways to achieve this.

Hmmmmmmmm... that's not so simple. -- Andrei

On Thursday, 17 December 2015 at 02:21:03 UTC, Andrei Alexandrescu wrote:
> Hmmmmmmmm... that's not so simple. -- Andrei

Well, it would complicate a bit as you add more to it (like changing the title on other pages...) but not a whole lot.

It is certainly simpler than the current dlang.org build process! There's over 1,000 lines of makefile for it.


Though, I actually run some kind of processor over my generated ddoc most the time anyway, and now I am really tempted to just go ahead and ditch the ddoc part since it doesn't add *that* much. At least for standalone pages.

On 12/16/2015 6:34 PM, Adam D. Ruppe wrote:
> Well, it would complicate a bit as you add more to it (like changing the title
> on other pages...) but not a whole lot.

You don't use it like I do. I use it to do abstractions, like sections, lists, etc., and then just change the markup to completely change the html generated.

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

> Exactly.
>
> We'll never get anywhere chasing people who say "I'll help only if you
> convert to my way of doing things." I've done enough of that in the
> past, and concluded they're just seeing how long you'll dance to their
> tune and have no real intention of ever helping - there will just be
> another excuse.

I already help, and I use Ddoc, that's how I know it's crap ;). 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.

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.

[1] http://dlang.org/spec/objc_interface.html

-- 
/Jacob Carlborg