On Wednesday, 16 December 2015 at 20:05:03 UTC, Vladimir Panteleev 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.

The number of macros bothers me, but mostly it's the complete lack of documentation and guidelines on where/how to use them*.
It's pretty unreasonable to expect someone submitting a passing doc fix to
1) find where the macros are defined
2) decipher them
3) use the "right" one**
It's just too much unpleasant work for people to bother with.

*If there is documentation and guidelines on this and I don't know about it, consider what it would be like for someone who doesn't spend many hours a week on the various subdomains of dlang.org: it might as well not exist!

**there must be some reasons for the existence of all of those macros, so presumably there are good and bad choices for certain situations, even if nothing is obviously broken using the bad choice. Sure, we might say "submit something naïve and then people will help you fix it", but that's still a barrier to entry; 1) how were they supposed to know we felt that way about submissions? 2) people don't like looking stupid.

On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote:
> 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.

How does a user who happens to spot a mistake in the docs and wants to help work this out?

On Wednesday, 16 December 2015 at 22:32:25 UTC, H. S. Teoh wrote:
> On Wed, Dec 16, 2015 at 10:00:50PM +0000, Meta via Digitalmars-d wrote:
>> There's also weird stuff like this, with an outer template and a documented inner template function.
>> 
>> http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
>
> 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.

I think in this particular case it can only be done with a nested template, because there are two variadic parameters.

On Thursday, 17 December 2015 at 07:53:02 UTC, Jacob Carlborg wrote:
> No sane person would use raw HTML. I hope no one takes that suggestion serious.

HTML + a couple simple helper tools is a different story though. That's basically what ddoc is anyway, but it has the weird behavior of just thinly wrapping html in macros.... $(DIVID $(B $(LINK2 seriously wtf))

In IRC I mentioned XSLT as a bit of a joke, but it solves the problem of reusing skeleton layouts too.

There's LOTS of ways to do this, and the language in which the doc pages are written is different than the framework which brings them all together and does other post processing.

On Thursday, 17 December 2015 at 08:06:28 UTC, Jacob Carlborg wrote:
> We obviously need a proper programming language to generate dconf.org.

I can't agree with this. I think there's too many conditionals already. Build the docs on posix and you miss out on Windows functions. Ugh.

On Thursday, 17 December 2015 at 07:51:42 UTC, Jacob Carlborg wrote:
> On 2015-12-17 00:43, BLM768 wrote:
>> 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.

Yeah. I didn't think that one through.

The idea I had in my head was to build a template in (mostly) raw HTML, write each article as an HTML snippet, and use either a framework or a build script to paste them together, so it's not _completely_ raw, just enough so you actually see the HTML. The main thing was to move away from building all the tags with macros.

But yeah, I didn't express that clearly enough (or think through it properly).

On 12/17/2015 5:44 AM, John Colvin wrote:
> On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote:
>> 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.
>
> How does a user who happens to spot a mistake in the docs and wants to help work
> this out?

1. he can file a bugzilla issue

2. he can click on the "Improve this page"

3. to find out what LREF does:

    grep LREF *.ddoc

If what a trivial text macro does is beyond his ken, and/or using grep, I wonder if he should be improving programming documentation at all. I do expect this to be part of the baseline knowledge a programmer should have. I wouldn't expect an accountant to know this stuff.

On 12/16/2015 10:47 AM, deadalnix wrote:
> 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.


I've never heard of .

On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote:
> 3. to find out what LREF does:
>
>     grep LREF *.ddoc

So, you're working on Phobos and see a LREF macro.

me@arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc
me@arsd:~/d/dmd2/src/phobos$

....where is it?

I happen to know it is hidden in the dlang.org repo, but would someone who saw a problem in the Phobos docs know that? They seem to be generated from the source code.... except when they aren't.

You can't assume everybody knows all the institutional knowledge you do!

On 12/16/15 6:47 PM, BLM768 wrote:
> On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote:
>> [snip]
>
> ...and as I read some older posts, I see that mine is completely
> redundant. ;)
>
> Seriously, though, I'm willing to help prototype something. I've got
> time before the next semester starts.

If you have some time and motivation to improve the documentation, there's tremendous opportunity for impact. So much low-hanging fruit, all well before we explore switching to a different way of building the site. And whatever improvements you make won't compete with future changes. There's so much opportunity there it hurts. -- Andrei