On 06/02/2016 09:09 PM, Sönke Ludwig wrote:
> Which are the remaining issues that you know of? I've searched bugzilla
> earlier today and couldn't find anything apart from broken "Improve this
> page" links for package.d modules.

The big one I know of is (M)REF_ALTTEXT. We need something better than the ugly parentheses thing we've got.

Other than that I don't have any blockers on my mind. We've made good progress. I haven't really looked for issues, though.

Maybe there is no point in hiding the pages from Google now. But they should have been hidden before. Then again, we would have had less pressure to fix things then.

Am 02.06.2016 um 21:27 schrieb Adam D. Ruppe:
> On Thursday, 2 June 2016 at 19:06:42 UTC, Sönke Ludwig wrote:
>> But I'd hate to implement some kind of special case here instead of
>> simply fixing the Phobos sources to use macros that carry proper
>> semantical meaning.
>
> That's actually exactly what I did:
>
> https://github.com/dlang/dlang.org/pull/1177
>
> The foundation even got merged into upstream dlang.org, six months ago!
>
> Sadly, the follow-up, just about two weeks after I laid the foundation*
> got stalled out <https://github.com/dlang/phobos/pull/3926> until
> recently, now a PR based on that one
> <https://github.com/dlang/phobos/pull/4303> got merged ten days ago.
>
> * Cross-linking in ddoc has been remarkably non-trivial until recently,
> and even so, MREF, REF, and REF_ALTTEXT, while much better than it was
> before, still aren't ideal.
>
> Fixing links is, in theory, one of the easiest tasks people can do, but
> in practice the plethora of bizarre macros makes it far harder than it
> should be. Even the REF macro family, which aims to unify them, has hit
> hurdles:
>
> https://github.com/dlang/dlang.org/pull/1257

I know and I think I misunderstood your last message. So you actually display the documentation for your own Phobos fork, right? That would make a lot more sense then. This hasn't been an option for the DDOX based documentation for obvious reasons, though, so no reason to laugh at it..

Am 02.06.2016 um 21:29 schrieb ag0aep6g:
> On 06/02/2016 09:09 PM, Sönke Ludwig wrote:
>> Which are the remaining issues that you know of? I've searched bugzilla
>> earlier today and couldn't find anything apart from broken "Improve this
>> page" links for package.d modules.
>
> The big one I know of is (M)REF_ALTTEXT. We need something better than
> the ugly parentheses thing we've got.
>
> Other than that I don't have any blockers on my mind. We've made good
> progress. I haven't really looked for issues, though.

Okay, that should be solved in a minute!

>
> Maybe there is no point in hiding the pages from Google now. But they
> should have been hidden before. Then again, we would have had less
> pressure to fix things then.

Agreed, unlisting from search engines + making the link to the docs more prominent to keep the pressure would probably have been the best choice.

On 06/02/2016 03:27 PM, Adam D. Ruppe wrote:
> Fixing links is, in theory, one of the easiest tasks people can do, but
> in practice the plethora of bizarre macros makes it far harder than it
> should be.

We'd be greatly helped by some automation here (i.e. pinpoint the wrong links). -- Andrei

On 06/02/2016 09:57 PM, Sönke Ludwig wrote:
> Okay, that should be solved in a minute!

Nice :D

On Thursday, 2 June 2016 at 19:53:29 UTC, Sönke Ludwig wrote:
> So you actually display the documentation for your own
> Phobos fork, right?

Yeah.

> This hasn't been an option for the DDOX based documentation for obvious reasons, though, so no reason to laugh at it..

Well, I think ddox is a competent implementation (of an iffy design, I don't love ddoc itself), and the fact that it is ahead on search engine rankings shows the page breakdown is more SEO-friendly than stock ddoc, among other advantages.

But what I find laughable is the surrounding ecosystem. It got added to the official website without a real support plan: a clear commitment was never made to fix Phobos issues, and nobody knew if we were actually going to transition from ddoc, or live side-by-side, or what. Certainly, nobody knew when, so there was no sense of urgency to fix the Phobos source regardless.

It just kinda sat in a dark corner of the website for years with little attention from the Phobos crew. I doubt many of them use it.


I feel the same thing is happening with dub by the way: we're told that it is the D package manager and there's code.dlang.org... but where's the follow-up action to back it up? It isn't included with the dmd zip and has very little marketing on the website. There's still a drive to get stuff into Phobos proper, or at least std.experimental, instead of dogfooding the package manager.

Sure, there's a link to it on the website, but there seems to be little personal use of it - and thus little drive to improve it - from among the Phobos core themselves.

On 06/02/2016 04:27 PM, Adam D. Ruppe wrote:
> It got added to the official website without a real support plan: a
> clear commitment was never made to fix Phobos issues, and nobody knew if
> we were actually going to transition from ddoc, or live side-by-side, or
> what. Certainly, nobody knew when, so there was no sense of urgency to
> fix the Phobos source regardless.
>
> It just kinda sat in a dark corner of the website for years with little
> attention from the Phobos crew. I doubt many of them use it.

Interestingly it came as encouraging and empowering some fledgling work that had compelling things going for it (including but not limited to enthusiastic receipt in this forum), which ironically is exactly what you just asked for.

Yes, I do wish /library/ were better and got more TLC. But I'm not sorry for approving it.


Andrei

On Thursday, 2 June 2016 at 20:34:24 UTC, Andrei Alexandrescu wrote:
> Interestingly it came as encouraging and empowering some fledgling work that had compelling things going for it (including but not limited to enthusiastic receipt in this forum), which ironically is exactly what you just asked for.

Yes, indeed, it was a good first (and second) step. But further steps are necessary too in order to finish a project.

Here's what would have been ideal to me:

1) Someone writes a cool thing.

2) We encourage further exploration and see interest.

3) After deciding there's serious potential, we decide on the end goal, a timeframe, and set the conditions of success. For example: ddox becomes the official documentation generator at the end of the year if there are no major bugs remaining open.

4) We put it on the website and work toward the goal, with all the teams - Phobos, dlang.org, RejectedSoftware, etc., understanding their role.

5) When the goal deadline arrives, if it passes the major bug test, it goes live and we are committed to it going forward.



Why this order? First, someone writing the cool thing means we actually have something to sink our teeth into and a de facto champion in the original author.

Second, we need to incubate this work and not discourage the author.

ddox got a decent go up to here.

But then we need to decide what's next - a clear goal, including a due date, gets us all aligned and removes a lot of the uncertainty on the author's side; it is some reassurance that they aren't wasting their time, and encourages outside teams to get onboard.

That leads directly into step four, and then step five actually proves that the others were not in vain.

On 06/02/2016 09:09 PM, Sönke Ludwig wrote:
> Which are the remaining issues that you know of?

Next up: MYREF.

Example page with missing links:
http://dlang.org/library/std/string.html

In std.ddoc, MYREF is defined as:

     MYREF = <a href="#.$1">$(TT $1)</a>$(NBSP)

In std-ddox-override.ddoc it's:

     MYREF = $1

That's no good, of course. But I also don't see a way to define it properly. It would have to be something like this:

    MYREF = <a href="./$(MODULE)/$1.html">$(TT $1)</a>$(NBSP)

where $(MODULE) is the current module name without packages.

But:

1) Something like $(MODULE) doesn't seem to exist. (Loosely related: DDOX doesn't emit $(TITLE) properly.)

2) camelCase strikes again. $1 would have to be transformed from fooBar to foo_bar to match DDOX's naming scheme. No can do with macros alone. I think those underscore names may have been a mistakee.

Am 03.06.2016 um 11:49 schrieb ag0aep6g:
> On 06/02/2016 09:09 PM, Sönke Ludwig wrote:
>> Which are the remaining issues that you know of?
>
> Next up: MYREF.
>
> Example page with missing links:
> http://dlang.org/library/std/string.html
>
> In std.ddoc, MYREF is defined as:
>
>       MYREF = <a href="#.$1">$(TT $1)</a>$(NBSP)
>
> In std-ddox-override.ddoc it's:
>
>       MYREF = $1
>
> That's no good, of course. But I also don't see a way to define it
> properly. It would have to be something like this:
>
>      MYREF = <a href="./$(MODULE)/$1.html">$(TT $1)</a>$(NBSP)
>
> where $(MODULE) is the current module name without packages.
>
> But:
>
> 1) Something like $(MODULE) doesn't seem to exist. (Loosely related:
> DDOX doesn't emit $(TITLE) properly.)
>
> 2) camelCase strikes again. $1 would have to be transformed from fooBar
> to foo_bar to match DDOX's naming scheme. No can do with macros alone. I
> think those underscore names may have been a mistakee.

Since only 12 modules are affected, probably the easiest way is to use the same approach as std.algorithm and define MYREF in each module separately as:

	MYREF = $(REF_ALTTEXT $(TT $1), $1, std, xxx)$(NBSP)

And then remove the definition from std.ddoc