On Wed, Dec 16, 2015 at 06:47:26PM +0000, deadalnix via Digitalmars-d wrote:
> On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:
> >>Also, ddoc always appeared to me like a big NIH syndrome.
> >
> >What would you have done instead?
> >
> 
> Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know.

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.

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


T

-- 
Жил-был король когда-то, при нём блоха жила.

On Wednesday, 16 December 2015 at 18:47:26 UTC, deadalnix wrote:
> On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:
>> What would you have done instead?
>
> Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know.

Yep. Completely agree.

On 12/16/2015 02:12 PM, H. S. Teoh via Digitalmars-d wrote:
>   the ongoing fiasco with XREF, LREF, whatever-REF and the
> associated relative/absolute URL nightmare

What's the issue there? -- Andrei

On Wed, Dec 16, 2015 at 02:33:15PM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/16/2015 02:12 PM, H. S. Teoh via Digitalmars-d wrote:
> >  the ongoing fiasco with XREF, LREF, whatever-REF and the
> >associated relative/absolute URL nightmare
> 
> What's the issue there? -- Andrei

See:

	https://github.com/D-Programming-Language/phobos/pull/3852
	https://github.com/D-Programming-Language/dlang.org/pull/1082

and their associated bugzilla tickets.


T

-- 
People say I'm arrogant, and I'm proud of it.

On 2015-12-16 20:12, H. S. Teoh 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.

There's DScanner [1].

[1] https://github.com/Hackerpilot/Dscanner/#syntax-highlighting

-- 
/Jacob Carlborg

On Wednesday, 16 December 2015 at 19:44:13 UTC, Jacob Carlborg wrote:
> There's DScanner [1].
>
> [1] https://github.com/Hackerpilot/Dscanner/#syntax-highlighting

Aye, and post-processing html to clean up the edge cases, reuse headers, etc. is really easy to do - easier than running bleeding-edge dmd over a makefile that requires three repos...

On 2015-12-16 20:33, Andrei Alexandrescu wrote:

> What's the issue there? -- Andrei

One problem is that it doesn't work for symbols arbitrary nested packages. That is, XREF only forks for "a.b.c" not "a.b.c.d".

-- 
/Jacob Carlborg

On 2015-12-16 14:50, Andrei Alexandrescu wrote:

> What standardized format was dominant in 2001? Thanks! -- Andrei

2001? According to the changelog Ddoc was added 2005 [1]. I hadn't really started to use D back then and barely programming at all. I would say Javadoc, Doxygen or Markdown, without knowing how standardized they were back then (if they existed).

But most important, Ddoc should not be used for website. I would prefer a template language with a proper server side language. Something like Haml, which allows to use filters where Markdown is one of the filters [2]. Good when writing longer texts. vibe.d's diet templates seems to be a good choice, it's indirectly based on Haml. Not sure if it supports filters though.

[1] http://www.digitalmars.com/d/1.0/changelog1.html#new0132
[2] http://haml.info/docs/yardoc/file.REFERENCE.html#filters

-- 
/Jacob Carlborg

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.

On 12/16/2015 5:50 AM, Andrei Alexandrescu wrote:
> On 12/16/15 3:00 AM, Jacob Carlborg wrote:
>> On 2015-12-16 02:15, Andrei Alexandrescu wrote:
>>
>>> It seems knowing ddoc is part of knowing D. -- Andrei
>>
>> I'm wondering how you can think it's perfectly acceptable to invent our
>> own (crappy) language for documentation and at the same time loudly
>> complain that SDLang is use for Dub config files and not a (more widely)
>> standardized format.
>
> What standardized format was dominant in 2001? Thanks! -- Andrei
>

To be fair, Ddoc came along later.

But Jacob has a good point. I looked at 2 other systems in common use at the time - Javadoc, which I thought was aesthetically ugly, and Doxygen, which is aesthetically ugly and way overly complex, as well as being C++ specific.

I wanted a system that looked good even without processing, i.e. it looked good in the the source code for basic use. Javadoc, Doxygen, both failed at that.

Ddoc looks good in its basic use, is ridiculously simple, and has proven powerful enough to generate html, pdf, Latex, and Kindle ebook results from the same source.

Ddoc has its shortcomings, too, like unittest. But it has achieved its goal, like unittest, which is to be so easy to use and built in that it it becomes completely natural to use it.

I regard unittest and Ddoc as being extremely successful in that they have transformed D programming. (This is true of Javadoc as well, but not for Doxygen.)

BTW, I've also used Ddoc to create several ebooks which I've published on Amazon, and for all the web sites I've created. It works very nicely for that. I don't think Doxygen nor Javadoc is useable in that way. It's kinda weird to run a history book through dmd to get an ebook out, but also kinda cool :-)