www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [dlang.org] Getting the ddox pages out of limbo

reply anonymous <anonymous example.com> writes:
We currently have two differently generated versions of the library 
documentation on dlang.org:

1) dlang.org/phobos/* (and dlang.org/phobos-prerelease/*) is generated 
by dmd's Ddoc functionality. These are the official docs, part of the 
"Documentation" section.

2) dlang.org/library/* (and dlang.org/library-prerelease/*) is generated 
by ddox (<https://github.com/rejectedsoftware/ddox>). Once upon a time, 
these docs were supposed to become official, replacing the other ones. 
Currently, they're in an unfortunate state of beta-forever.

ddox has a number of issues that make it currently not feasible to just 
switch over:

* Macro for "path to base of docs"?
     https://github.com/rejectedsoftware/ddox/issues/87

* macros from parent scopes are not known in child scopes
     https://github.com/rejectedsoftware/ddox/issues/116

* treating of underscore not consistent with dmd
     https://github.com/rejectedsoftware/ddox/issues/117

There may be more.

Now, is the plan still to make the switch to ddox for the official 
documentation? Is anyone actually working towards that goal?

If not, maybe we should get rid of the ddox pages, at least for the time 
being. Currently, I think they do more harm than good: They confuse 
people who find them through google, and they drain maintenance resources.

Regarding google, hiding them via robots.txt could be a milder 
alternative to outright deleting them.

And then there's Adam D. Ruppe's <http://dpldocs.info/>. No idea how 
that plays into the whole mess we're in.
Feb 12 2016
next sibling parent via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Fri, Feb 12, 2016 at 06:19:45PM +0100, anonymous via Digitalmars-d wrote:

 And then there's Adam D. Ruppe's <http://dpldocs.info/>. No idea how that
 plays into the whole mess we're in.


It is separate exactly to avoid the trouble of the official site.

I certainly wouldn't mind if we were to switch over, but I'm not quite ready
for that yet, I am still doing a lot of changes on my site.
Feb 12 2016
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
The irony of a thread about "getting [...] out of limbo" 
apparently being in limbo is amusing to me.
Feb 16 2016
prev sibling parent =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 12.02.2016 um 18:19 schrieb anonymous:

 ddox has a number of issues that make it currently not feasible to just
 switch over:

 * Macro for "path to base of docs"?
      https://github.com/rejectedsoftware/ddox/issues/87


I'm a little worried about introducing such special behavior, because it 
could lead to doc comments that are incompatible with vanilla Ddoc.

 * macros from parent scopes are not known in child scopes
      https://github.com/rejectedsoftware/ddox/issues/116

 * treating of underscore not consistent with dmd
      https://github.com/rejectedsoftware/ddox/issues/117


Both fixed now.
Feb 17 2016