Ready to make page-per-item ddocs the default?

[H. S. Teoh via Digitalmars-d]

On Thu, Jan 08, 2015 at 01:14:43PM -0800, Andrei Alexandrescu via Digitalmars-d wrote:
> On 1/8/15 1:01 PM, Steven Schveighoffer wrote:
> >
> >There are many cases where the members are dependent on the OS. The
> >one that strikes me as the most OS dependent (so far) is errno.d. I'm
> >guessing that only one of those docs is going to go into the online
> >docs? Is there a standard way to make them all show up (with nice
> >categories to show which OS they apply to) which is not painful?
> >
> >If not, then we really need a good way to solve this... An idea might
> >be to make a switch that tells the compiler to override it's internal
> >predefinitions (e.g. compile with -DWin32 on Linux) just for doc
> >generation, and have the resulting page have a way to "flavor" the
> >page based on the OS you select or browse from.
> 
> I don't think there is a way. Making ddoc "cross-compilation" work
> would be an interesting project, but one of a lower priority. --
[...]

It's not just an "interesting" project; it's a pretty important one,
seeing that the "std.windows.charset" link on dlang.org has been broken
for a looooong time (probably *years*, by my estimation), just because
dlang.org happens to be built on a Linux machine, so none of the Windows
module make it into the ddoc pass (and even if they did, they'd be empty
due to version(Windows) in the code).

Not to mention the tons of other Windows-specific docs that will never
make it to dlang.org for the same reason.  It's a pretty nice way to
turn off Windows users who are trying to find docs on dlang.org. :-P

(I'm not a Windows user btw, so this doesn't really bother me in the
least.  But I'm sure you're probably a lot more concerned about the
potential loss of users here.)


T

-- 
Heads I win, tails you lose.