On Wednesday, 16 December 2015 at 19:12:04 UTC, H. S. Teoh wrote:
> On Wed, Dec 16, 2015 at 06:47:26PM +0000, deadalnix via Digitalmars-d wrote:
>> [...]
>
> Using ddoc for the website may be NIH, but the ability to easily display snippets of D code without jumping through hoops is a big plus. Trying to do syntax-highlighted D code in plain HTML (or any other web authoring system, for that matter) is an exercise in masochism.

Re. syntax highlighting -- it looks like Pygments supports D. http://pygments.org/languages/

On 12/15/2015 12:31 AM, Gary Willoughby wrote:
> We've all said time and time again if ddoc wasn't used for the entire site more
> people would help with it. Ddoc makes sense for the documentation but not
> everything else.

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."


> more people would help with it.

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 do agree that the macros defined in the site's .ddoc files are ridiculously overlapping, redundant, etc. That all could use a redesign and an overhaul, but that isn't Ddoc's fault. It's just like any piece of crap code that has suffered from too many quick&dirty hacks layered on to it.

On 12/16/2015 03:05 PM, Vladimir Panteleev wrote:
> DDoc itself is very simple. The problem is the endless number of macros
> we use on dlang.org.

I see that as a blessing.

> E.g. all the different ways to link to something:
> A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, XREF2, CXREF,
> ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, OBJREF...

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?

> There is also
> no strong reason to use e.g. DIVCID instead of plain HTML.

I agree. I added that more for completeness, easier typing, and so I can rely on editors showing the closing paren.


Andrei

On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
> I'm not so sure...

Like they say: "A father will never agree that his child is ugly!"

:)

John.

On 12/16/2015 12:21 AM, ZombineDev wrote:
> Well DDoc may have it's disadvantages, but I'm certain that the documentation
> would have been far worse if it wasn't for it.

No need to speculate :-) Before Ddoc, the Phobos documentation was horrific, probably the worst I'd ever seen. It was so bad it was unusual for there to be any correct documentation for a particular function, or even anything at all.

Ddoc utterly transformed that, almost overnight. It's hard to underestimate the positive impact Ddoc has had on D documentation.

On 12/16/2015 03:59 PM, JohnCK wrote:
> On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
>> I'm not so sure...
>
> Like they say: "A father will never agree that his child is ugly!"

To me it seems he's making a few good points. -- Andrei

On Wed, Dec 16, 2015 at 08:05:03PM +0000, Vladimir Panteleev via Digitalmars-d wrote:
> On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote:
> >On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote:
> >>On 12/15/15 5:54 AM, tcak wrote:
> >>>The harder it is made for people to contribute the system for fixations, the lesser changes are seen.
> >>
> >>I don't think we've had many contributions via the "Improve this page" button.
> >>
> >
> >I don't know how representative it is, but once in a while, i forgot all of this is in DDoc, I notice something, what to do a quick patch, and end up being reminded this is in DDoc and I have no idea how to fix the thing, because suddenly, what looked like a quick fix end up being learning a new macro language.
> 
> DDoc itself is very simple. The problem is the endless number of macros we use on dlang.org. E.g. all the different ways to link to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, OBJREF... There is also no strong reason to use e.g. DIVCID instead of plain HTML.

Yeah, this is like spaghetti code written with C macros, where all macro names are in the same namespace, there is no scoping (everything is global), and undocumented so nobody knows what's already there or when to use what, and reinvents their own unhelpfully-named macros. Worse yet, sometimes people write their own implementations of existing macros with the same name so it's far from obvious which macro is actually in force when a particular part of the website is being processed -- this actually happens in the dlang.org repo: try grepping for XREF or LREF sometime, and see how many different definitions there are, for example. Or how many different macros there are for generating hyperlinks -- when should each one be used? Who knows. Read the code^Wmacro definitions to find out.

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. It's like a worst-case scenario C library that has printf1, printf2, printf3, ..., instead of printf, fprintf, snprintf, etc., and people are expected to remember which numerical suffix does what.

It's relatively easy to keep track of this in single-person projects -- Walter's using ddoc for creating ebooks, for example -- but in large collaborative projects these seemingly-minor issues lead to spaghetti macro-ni soup. The messy, inconsistent tangle that is the dlang.org macros constitute a high barrier-to-entry for would-be contributors. Mostly people just end up copy-n-pasting stuff without understanding what's really going on.  We're at the ironical situation where ddoc macros need their usage documented -- by another ddoc page? :-P


T

-- 
There is no gravity. The earth sucks.

On Wednesday, 16 December 2015 at 20:59:46 UTC, JohnCK wrote:
> On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
>> I'm not so sure...
>
> Like they say: "A father will never agree that his child is ugly!"
>
> :)
>
> John.

Please don't go there. This is not about if ddoc is good or not, this is about making the website better.

In that regard, I think it is fair to asses that people that know webdev don't know ddoc an vice versa. So using ddoc is probably not the best bet here.

On Wednesday, 16 December 2015 at 21:06:48 UTC, Andrei Alexandrescu wrote:
> On 12/16/2015 03:59 PM, JohnCK wrote:
>> On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
>>> I'm not so sure...
>>
>> Like they say: "A father will never agree that his child is ugly!"
>
> To me it seems he's making a few good points. -- Andrei

Ops, just to clarify, I

On Wednesday, 16 December 2015 at 21:18:43 UTC, JohnCK wrote:
> On Wednesday, 16 December 2015 at 21:06:48 UTC, Andrei Alexandrescu wrote:
>> On 12/16/2015 03:59 PM, JohnCK wrote:
>>> On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
>>>> I'm not so sure...
>>>
>>> Like they say: "A father will never agree that his child is ugly!"
>>
>> To me it seems he's making a few good points. -- Andrei
>
> Ops, just to clarify, I

Ops again, so just to clarify, I'm not saying the ddocs is that ugly, but let's face it, like others said it has some flaws or otherwise it wouldn't be so discussed every time.

JohnCK.