On 1/7/15 10:55 AM, Vladimir Panteleev wrote:
> On Wednesday, 7 January 2015 at 15:42:24 UTC, Andrei Alexandrescu wrote:
>>> * I still have reservations about using Disqus.
>>
>> I did keep that in mind. The long and short of it it it's impossible
>> to make a change that everybody likes. We must move forward.
>
> I agree, it might very well be the least of all evils.

Just a thought on this -- from personal experience I like disqus quite a lot for commenting on fleeting topics, such as blog posts or articles. But these are quite static pages. However, I've benefited greatly from e.g. php doc comments which show ways to solve problems I am trying to solve. So I think we should keep these for that purpose.

We have several issues to consider with disqus (or any commenting system):

Inevitably, questions about the docs will be asked. If nobody looks at the docs (and let's face it, most of our veterans do not look at the docs every day), then the perception is that nobody is listening. Can we at least forward the posts to a NG/mailing list? I doubt such questions would happen frequently.

I think anyone who has commit rights to any D project should be made moderator so they can stomp out trolls, remove fleeting/simple questions (after nudging towards d.learn), etc.

There is going to be a push at some point to split up docs (e.g. std.datetime), is it possible to move a disqus comment from one page to another?

-Steve

On 1/8/15 4:18 AM, Steven Schveighoffer wrote:
> On 1/6/15 8:16 PM, Andrei Alexandrescu wrote:
>> On 1/6/15 3:44 PM, weaselcat wrote:
>>> On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
>>>> Let's crowdsource the review. Please check the entries linked from
>>>> here: http://dlang.org/library/index.html.
>>>>
>>>> Andrei
>>>
>>> Is it intentional for all of the stdc pages to be empty?
>>
>> It's a somewhat unfortunate fallout of the level of granularity. I think
>> each of these headers should include a standard text and a link to some
>> good documentation in C-land. -- Andrei
>
> I like this idea.
>
> One thing that may be misleading about this -- our headers don't include
> *everything* from C-land.
>
> What would be a good generic blurb? strawman:
>
> core.stdc.ctype:
> "This contains bindings to selected types and functions from the
> standard C header <ctype.h> (see
> http://pubs.opengroup.org/onlinepubs/009695399/basedefs/ctype.h.html).
> Note that this is not automatically generated, and may omit some
> types/functions from the original C header."
>
> I'm thinking we should actually just put a /// before every symbol, to
> get it in the ddoc so you can see what *is* included.
>
> Thoughts? I can put together a pull for core.stdc.* if it makes sense.

Blurb LGTM, please make it happen. Also let's experiment with the ///'s. If we get real cocky we might insert for each symbol a LUCKY link googling for the header name and symbol name. Thanks! -- Andrei

On 1/8/15 4:31 AM, Steven Schveighoffer wrote:
> I think anyone who has commit rights to any D project should be made
> moderator so they can stomp out trolls, remove fleeting/simple questions
> (after nudging towards d.learn), etc.

Sönke could do this I think. -- Andrei

On 1/8/15 10:41 AM, Andrei Alexandrescu wrote:
> On 1/8/15 4:18 AM, Steven Schveighoffer wrote:

>> Thoughts? I can put together a pull for core.stdc.* if it makes sense.
>
> Blurb LGTM, please make it happen. Also let's experiment with the ///'s.

Just to put a semaphore on this, I'm partway through doing this, please don't someone else do it too, it's tedious work :)

A couple of questions though:

core.stdc.config is not technically a standard C header, and it seems pretty strange. I'm going to leave that one alone unless someone objects.

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.

-Steve

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

On Thursday, 8 January 2015 at 21:14:43 UTC, Andrei Alexandrescu wrote:
> I don't think there is a way.

version(Ddoc) dummy prototypes maybe. But that gets painful.

Though I think the compiler should NOT do conditional compilation when generating documentation. Instead, I'd prefer to just put it all out and then maybe group.

So the doc would actually list the separate entries under all version headers. Not just OS, but arch or custom bits too. Then the user can see it all. Then by attaching classes to the outputted data you could easily do a filter by OS.

On 1/8/15 1:23 PM, Adam D. Ruppe wrote:
> On Thursday, 8 January 2015 at 21:14:43 UTC, Andrei Alexandrescu wrote:
>> I don't think there is a way.
>
> version(Ddoc) dummy prototypes maybe. But that gets painful.

In doc builds we can probably define Windows on Linux etc.

> Though I think the compiler should NOT do conditional compilation when
> generating documentation. Instead, I'd prefer to just put it all out and
> then maybe group.
>
> So the doc would actually list the separate entries under all version
> headers. Not just OS, but arch or custom bits too. Then the user can see
> it all. Then by attaching classes to the outputted data you could easily
> do a filter by OS.

Yah, as I said it's a project.


Andrei

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.

On 2015-01-08 22:01, Steven Schveighoffer wrote:

> core.stdc.config is not technically a standard C header, and it seems
> pretty strange. I'm going to leave that one alone unless someone objects.

Shouldn't this then be documented like any other druntime/Phobos module.

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

That would be cool.

-- 
/Jacob Carlborg

On 2015-01-08 22:23, Adam D. Ruppe wrote:
> On Thursday, 8 January 2015 at 21:14:43 UTC, Andrei Alexandrescu wrote:
>> I don't think there is a way.
>
> version(Ddoc) dummy prototypes maybe. But that gets painful.

Tango is using this method quite heavily in some modules. It also gives the opportunity to simplify signatures.

> Though I think the compiler should NOT do conditional compilation when
> generating documentation. Instead, I'd prefer to just put it all out and
> then maybe group.
>
> So the doc would actually list the separate entries under all version
> headers. Not just OS, but arch or custom bits too. Then the user can see
> it all. Then by attaching classes to the outputted data you could easily
> do a filter by OS.

That would be really nice.

-- 
/Jacob Carlborg