Re: Ready to make page-per-item ddocs the default?
On 1/9/15 4:17 PM, Andrei Alexandrescu wrote: On 1/9/15 12:59 PM, Jacob Carlborg wrote: On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? Oh yah :o). Steve? -- Andrei Apparently, the documentation generator ignores items that are tagged as documented but without any substance. If I compile a simple doc with a /// before an item, it does show up when I do dmd -D. So I have no idea how to make it work for this new doc system. -Steve
Re: Ready to make page-per-item ddocs the default?
On 1/11/15 11:26 AM, Steven Schveighoffer wrote: On 1/9/15 4:17 PM, Andrei Alexandrescu wrote: On 1/9/15 12:59 PM, Jacob Carlborg wrote: On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? Oh yah :o). Steve? -- Andrei Apparently, the documentation generator ignores items that are tagged as documented but without any substance. If I compile a simple doc with a /// before an item, it does show up when I do dmd -D. So I have no idea how to make it work for this new doc system. Martin Nowak? Sönke Ludwig? Andrei
Re: Ready to make page-per-item ddocs the default?
On Sunday, 11 January 2015 at 19:52:42 UTC, Andrei Alexandrescu wrote: On 1/11/15 11:26 AM, Steven Schveighoffer wrote: On 1/9/15 4:17 PM, Andrei Alexandrescu wrote: On 1/9/15 12:59 PM, Jacob Carlborg wrote: On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? Oh yah :o). Steve? -- Andrei Apparently, the documentation generator ignores items that are tagged as documented but without any substance. If I compile a simple doc with a /// before an item, it does show up when I do dmd -D. So I have no idea how to make it work for this new doc system. Martin Nowak? Sönke Ludwig? Andrei That's a feature, not a bug ! (tm) I think what's going on is that `--only-documented` is somehow specified. I had a glance at dlang.org and couldn't find the flag, but it's present by default if you build with dub, and I have no idea how Phobos' ddox are build ATM. `--only-documented` filters everything that have an empty comment out (https://github.com/rejectedsoftware/ddox/blob/master/source/ddox/main.d#L193). Which looks like a bug (or at least, something that has been overlooked), as dmd differentiate between empty comment and no comment.
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 08:46:41 UTC, Vladimir Panteleev wrote: * I still have reservations about using Disqus. I'm quite happy with the self hosted isso comments on my blog. https://code.dawg.eu/reducing-vibed-turnaround-time-part-2-less-compiling.html#isso-thread
Re: Ready to make page-per-item ddocs the default?
On 1/8/15 4:01 PM, Steven Schveighoffer wrote: 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 :) https://github.com/D-Programming-Language/druntime/pull/1091 -Steve
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 12:08 PM, Martin Nowak wrote: On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote: One thing that may be misleading about this -- our headers don't include *everything* from C-land. What's missing? They should just match their C counterparts. Andrei had the idea to put the blurb in one place as a macro, so we can change it quite easily if you can think of a better statement. See here: https://github.com/D-Programming-Language/dlang.org/pull/752 -Steve
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 12:08 PM, Martin Nowak wrote: On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote: One thing that may be misleading about this -- our headers don't include *everything* from C-land. What's missing? They should just match their C counterparts. Perhaps they do, I don't think we should guarantee it though. For instance, a macro may not be suited to be included in D because we have better options. -Steve
Re: Ready to make page-per-item ddocs the default?
On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote: One thing that may be misleading about this -- our headers don't include *everything* from C-land. What's missing? They should just match their C counterparts.
Re: Ready to make page-per-item ddocs the default?
On Fri, Jan 09, 2015 at 11:46:47AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: [...] Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. [...] Isn't this caused by the fact that the various *REF*/*LINK* macros insert gratuitous nbsp;'s after the link? I ran into this several times while rewriting std.algorithm docs, and it's very annoying, since it precludes using these macros in many places where I'd like to use them. I've had to rephrase sentences just so the extraneous spaces don't show up in the wrong place. T -- Programming is not just an act of telling a computer what to do: it is also an act of telling other programmers what you wished the computer to do. Both are important, and the latter deserves care. -- Andrew Morton
Re: Ready to make page-per-item ddocs the default?
On 01/09/2015 07:35 PM, Andrei Alexandrescu wrote: Maybe Calypso could be used for that? -- Andrei What's calypso, can't find anything.
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 10:10 AM, Steven Schveighoffer wrote: On 1/9/15 12:08 PM, Martin Nowak wrote: On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote: One thing that may be misleading about this -- our headers don't include *everything* from C-land. What's missing? They should just match their C counterparts. Perhaps they do, I don't think we should guarantee it though. For instance, a macro may not be suited to be included in D because we have better options. Maybe Calypso could be used for that? -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 10:46 AM, Steven Schveighoffer wrote: On 1/9/15 12:08 PM, Martin Nowak wrote: On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote: One thing that may be misleading about this -- our headers don't include *everything* from C-land. What's missing? They should just match their C counterparts. Andrei had the idea to put the blurb in one place as a macro, so we can change it quite easily if you can think of a better statement. See here: https://github.com/D-Programming-Language/dlang.org/pull/752 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On Friday, 9 January 2015 at 20:00:27 UTC, H. S. Teoh via Digitalmars-d wrote: On Fri, Jan 09, 2015 at 11:46:47AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: [...] Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. [...] Isn't this caused by the fact that the various *REF*/*LINK* macros insert gratuitous nbsp;'s after the link? I ran into this several times while rewriting std.algorithm docs, and it's very annoying, since it precludes using these macros in many places where I'd like to use them. I've had to rephrase sentences just so the extraneous spaces don't show up in the wrong place. T In this case there is a span class=pln /span that is 16px wide and occupies exactly the space you want to get rid of. It only shows up when viewing the HTML using the Chrome developer tools (F12). It's not in the page source.
Re: Ready to make page-per-item ddocs the default?
On 01/09/2015 09:29 PM, Tobias Pankrath wrote: In this case there is a span class=pln /span that is 16px wide and occupies exactly the space you want to get rid of. It only shows up when viewing the HTML using the Chrome developer tools (F12). It's not in the page source. It's highlighted as D source.
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 12:35 PM, Martin Nowak wrote: On 01/09/2015 09:29 PM, Tobias Pankrath wrote: In this case there is a span class=pln /span that is 16px wide and occupies exactly the space you want to get rid of. It only shows up when viewing the HTML using the Chrome developer tools (F12). It's not in the page source. It's highlighted as D source. Found Waldo. Please review. https://github.com/D-Programming-Language/dlang.org/pull/756 -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 11:58 AM, H. S. Teoh via Digitalmars-d wrote: On Fri, Jan 09, 2015 at 11:46:47AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: [...] Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. [...] Isn't this caused by the fact that the various *REF*/*LINK* macros insert gratuitous nbsp;'s after the link? No, I looked; I think it's because of the newline thereafter. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 12:59 PM, Jacob Carlborg wrote: On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? Oh yah :o). Steve? -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 1:18 PM, Andrei Alexandrescu wrote: On 1/9/15 1:17 PM, Andrei Alexandrescu wrote: On 1/9/15 12:59 PM, Jacob Carlborg wrote: On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? Oh yah :o). Steve? -- Andrei http://dlang.org/library-prerelease/core/stdc/errno.html does list the enum values. -- Andrei ... albeit wrongly: https://issues.dlang.org/show_bug.cgi?id=13961 -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 1:17 PM, Andrei Alexandrescu wrote: On 1/9/15 12:59 PM, Jacob Carlborg wrote: On 2015-01-09 20:46, Andrei Alexandrescu wrote: Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei Is it just me or are the actual declarations missing? Oh yah :o). Steve? -- Andrei http://dlang.org/library-prerelease/core/stdc/errno.html does list the enum values. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/9/15 2:14 AM, Jacob Carlborg wrote: 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. Sure, that is fine by me. But I'm not going to do it, as I don't know what it's for :) -Steve
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
On 1/8/2015 1:01 PM, 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. Yeah, the mere existence of that module grates.
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
On 2015-01-08 22:25, Andrei Alexandrescu wrote: Yah, as I said it's a project. Can we at least generate the documentation on multiple platforms, just to make sure we got all modules. -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On 1/8/2015 7:41 AM, Andrei Alexandrescu wrote: If we get real cocky we might insert for each symbol a LUCKY link googling for the header name and symbol name. Livin' on the edge!
Re: Ready to make page-per-item ddocs the default?
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 long 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.
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 1:03 AM, Andrei Alexandrescu wrote: On 1/6/15 6:17 PM, Steven Schveighoffer wrote: On 1/6/15 5:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. std.algorithm has many of the descriptions showing samples. Also, I know the table at the top is to make things easier for standard ddoc, should that be removed? But I like it. It's redundant. Right below is the same exact info (see Cheat sheet). BTW, I'm all for the docs to be switched. Just the cross-referencing alone is worth it. One thing we need to do is offer for each module view as one page so people still have that option. That would be nice. In fact, I would recommend for when javascript is enabled, a way to expand a function/class inline. -Steve
Re: Ready to make page-per-item ddocs the default?
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. -Steve
Re: Ready to make page-per-item ddocs the default?
On 2015-01-08 13:18, Steven Schveighoffer wrote: 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. I like it. -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On Thursday, 8 January 2015 at 12:18:37 UTC, 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. -Steve All public symbols in any module should have a ddoc comment, even if said comment is empty. Does that sound like a reasonable rule-of-thumb?
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
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.
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
On 1/7/2015 12:41 AM, Vladimir Panteleev wrote: On Wednesday, 7 January 2015 at 07:12:33 UTC, Walter Bright wrote: I find dman.exe to be very handy and use it all the time, but since it is a hand-built index, it is always hopelessly out of date. Why not reuse the index built by chmgen? It's very inclusive and mostly accurate. There seems to be a lack of documentation on it :-( Anyhow, dman is pretty simple. It maps the command line argument to a url and opens the browser on the url. If the argument is not in its index, it reverts to using google. It would be much improved if it were combined with chmgen somehow.
Re: Ready to make page-per-item ddocs the default?
On 2015-01-07 00:44, weaselcat wrote: Is it intentional for all of the stdc pages to be empty? Why is even std.c.* still available. These should all be replaced with core.stdc.*. -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On 2015-01-06 23:43, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. What about all those suggestions in the thread Improving ddoc [1]? Some of those suggestions might require to redesign the documentation. Is it still worth updating to the new layout? [1] http://forum.dlang.org/thread/m81k2p$k47$1...@digitalmars.com -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 08:46:41 UTC, Vladimir Panteleev wrote: * Overzealous linking of words in the documentation that happen to coincide with symbols in the same module. This should only be done for text in $(D ...) tags. According to the specs: Identifiers in documentation comments that are function parameters or are names that are in scope at the associated declaration are emphasized in the output. This emphasis can take the form of italics, boldface, a hyperlink, etc. How it is emphasized depends on what it is - a function parameter, type, D keyword, etc. To prevent unintended emphasis of an identifier, it can be preceded by an underscore (_). The underscore will be stripped from the output. So it's conforming. However, I think this specific part of the spec cause more problems than it solves. Just think about using `any`, `all`, `find` and so on in `std.algorithm. Maybe it's time to update the specs ? :)
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 01:13:21 UTC, Andrei Alexandrescu wrote: On 1/6/15 4:26 PM, Robert burner Schadek wrote: std.string looks fine only the indexOfNeither and lastIndexOfNeither are missing Could you please fix -- thanks! -- Andrei I think I just did. Does the webpage show 2.066? If so indexOfNeither must not be part as it was merged after the release.
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 12:22 AM, Tobias Pankrath 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 Has it been generated from an up-to-date version? Where are the sub modules of std.container? http://dlang.org/library/std/container.html Try http://dlang.org/library-prerelease/std/container.html -- Andrei
Re: Ready to make page-per-item ddocs the default?
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 Has it been generated from an up-to-date version? Where are the sub modules of std.container? http://dlang.org/library/std/container.html
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 12:24 AM, Andrei Alexandrescu wrote: On 1/7/15 12:22 AM, Tobias Pankrath 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 Has it been generated from an up-to-date version? Where are the sub modules of std.container? http://dlang.org/library/std/container.html Try http://dlang.org/library-prerelease/std/container.html -- Andrei Apparently the links exist, but don't work, e.g. http://dlang.org/library-prerelease/std/std_container_array is not to be found. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 2:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Many thanks to those who provided feedback on the new layout! I've fixed a few issues, but it looks like there are quite a few more problems than I had anticipated. I encourage any and all of you to build the documentation locally (make -j should work nicely) and help with pull requests to github. Let's get this off the ground together. Thanks, Andrei
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 07:12:33 UTC, Walter Bright wrote: On 1/6/2015 10:48 PM, Andrei Alexandrescu wrote: Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page. That would be quite an involved project. -- Andrei I find dman.exe to be very handy and use it all the time, but since it is a hand-built index, it is always hopelessly out of date. Why not reuse the index built by chmgen? It's very inclusive and mostly accurate.
Re: Ready to make page-per-item ddocs the default?
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. From my last complain thread: http://forum.dlang.org/post/zazgfoxjwhjbdrgdi...@forum.dlang.org I see that many of the issues with my example got fixed. Remaining issues: * Overzealous linking of words in the documentation that happen to coincide with symbols in the same module. This should only be done for text in $(D ...) tags. * Compile-time expressions are expanded to their computed variant. For example, `size_t.max` is expanded to `18446744073709551615LU`, which is not informative, and wrong on 32-bit systems. `Config.none` is now `cast(Config)0`, which sucks. I guess this is a compiler issue rather than a DDox one. More issues I noticed now from a quick look: * http://dlang.org/library/std/process.html : The comparison table is gone, replaced with an unstructured blob of text. * http://dlang.org/library/std/parallelism.html : More overzealous linking (e.g.: These include _parallel_ foreach, _parallel_ reduce, _parallel_ eager map, ...). * http://dlang.org/library/core/time.html : More overzealous linking - symbols within D string literals should not be linked. * I still have reservations about using Disqus.
Re: Ready to make page-per-item ddocs the default?
Apparently the links exist, but don't work, e.g. http://dlang.org/library-prerelease/std/std_container_array is not to be found. -- Andrei It works from the tree on the left.
Re: Ready to make page-per-item ddocs the default?
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 I think there needs to a clear separation between the end of the overview (e.g. the cheat sheet in std.algorithm) and the rather arbitrarily organised content beneath. A big header saying API Reference or similar would do the trick. I guess it makes sense in a way, but should an end user care that std.algorithm.map happens to be written as a function nested in a template and std.algorithm.find is a function template? I'm not sure. The name column in the variable reference tables is often far too narrow. It is *much* harder to get the general feel of a module in the new format, unless it has a comprehensive overview. Previously I would just scan down the page, seeing which symbols had more documentation and examples (probably major entry points to the API), quickly gaining context by having glanced at things on the way through. Now I'd have to go through symbols individually, without context, by laboriously clicking on links. Awful. Overall it's a good idea, but while it will make std.algorithm, std.range and some other well-documented modules with extensive summaries and tables easier to use, it makes less well documented modules even worse than they were before.
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu wrote: That would be quite an involved project. -- Andrei http://dpldocs.info/
Re: Ready to make page-per-item ddocs the default?
On 2015-01-07 23:35, Andrei Alexandrescu wrote: The way I see this, these items are good to have and by nature of our process will be deployed (if at all) incrementally by whomever is interested in implementing them. We can't afford to block progress of docs layout on this possibility. -- Andrei I guess that's a fair point. -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 12:46 AM, Vladimir Panteleev wrote: Remaining issues: * Overzealous linking of words in the documentation that happen to coincide with symbols in the same module. This should only be done for text in $(D ...) tags. Yah, I'm quite unhappy about that, too. * Compile-time expressions are expanded to their computed variant. For example, `size_t.max` is expanded to `18446744073709551615LU`, which is not informative, and wrong on 32-bit systems. `Config.none` is now `cast(Config)0`, which sucks. I guess this is a compiler issue rather than a DDox one. Hrm, not sure how easy it would be to fix this. More issues I noticed now from a quick look: * http://dlang.org/library/std/process.html : The comparison table is gone, replaced with an unstructured blob of text. * http://dlang.org/library/std/parallelism.html : More overzealous linking (e.g.: These include _parallel_ foreach, _parallel_ reduce, _parallel_ eager map, ...). * http://dlang.org/library/core/time.html : More overzealous linking - symbols within D string literals should not be linked. Could you please fix or file these. Thanks! * 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. Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 11:12 AM, Jacob Carlborg wrote: Most of the ideas I had might require some redesign of the documentation layout, these are: * Summary of symbols * Documentation for private symbols * Simplified signatures * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses BTW the thing that have bothered me the most when writing documentation is there's no good way to even manually cross-reference symbols. We really should have a special syntax for that as well. The way I see this, these items are good to have and by nature of our process will be deployed (if at all) incrementally by whomever is interested in implementing them. We can't afford to block progress of docs layout on this possibility. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 1:06 AM, Jacob Carlborg wrote: On 2015-01-07 00:44, weaselcat wrote: Is it intentional for all of the stdc pages to be empty? Why is even std.c.* still available. These should all be replaced with core.stdc.*. Please fix or file so this isn't forgotten. -- Andrei
Re: Ready to make page-per-item ddocs the default?
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 I don't think I have to point out the problems with http://dlang.org/library/std/algorithm/find.html
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 1:14 AM, Jacob Carlborg wrote: On 2015-01-06 23:43, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. What about all those suggestions in the thread Improving ddoc [1]? Some of those suggestions might require to redesign the documentation. Is it still worth updating to the new layout? [1] http://forum.dlang.org/thread/m81k2p$k47$1...@digitalmars.com My summary of that discussion follows. There were quite a few radical suggestions, some of which were interesting but that seemed to entail a lot of work compared to the reaped benefits. (I have to say it was quite fun to re-read the whole thread and see Walter calmly dismantling some of the less valid arguments.) The suggestions I think are actionable: * Detect `xyz` and replace it with $(BACKQUOTED xyz), pull request in progress at https://github.com/D-Programming-Language/dmd/pull/4228. Maybe detect some __underscored__ or **bolded** words similarly. * Better whitespace control * Macros that expand without $() - possibly an extension of ESCAPES. * Add a subset of markdown on top of ddoc (details unclear). * Make [text](url) denote a link. * Hashtags for headings * Generate cross-references automatically. * Clever automatic linking or embedding of overridden functions docs. * Automatic links to source code. * Simplified signatures (__FILE__ etc, template constraints) * Replace some of the parens with indent nesting. * Not in that thread, but it was somewhere proposed that we use recursive macros for nice $(LIST item one, two, three). What did I miss? Among the more radical proposals: * Use markdown * Use doxygen Again, it seems to me these would yield little benefit for the effort even assuming perfect execution. Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 7:55 AM, Vladimir Panteleev wrote: On Wednesday, 7 January 2015 at 15:42:24 UTC, Andrei Alexandrescu wrote: Could you please fix or file these. Thanks! The D or DDox issue tracker? Either, appropriately :o). -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/7/15 8:20 AM, John Colvin 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 I don't think I have to point out the problems with http://dlang.org/library/std/algorithm/find.html Bummer. It doesn't seem ddox is ready for prime time. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 2015-01-07 16:42, Andrei Alexandrescu wrote: Please fix or file so this isn't forgotten. -- Andrei https://issues.dlang.org/show_bug.cgi?id=13948 Perhaps it should automatically ignore deprecated modules? -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On 2015-01-07 17:22, Andrei Alexandrescu wrote: My summary of that discussion follows. There were quite a few radical suggestions, some of which were interesting but that seemed to entail a lot of work compared to the reaped benefits. (I have to say it was quite fun to re-read the whole thread and see Walter calmly dismantling some of the less valid arguments.) The suggestions I think are actionable: * Detect `xyz` and replace it with $(BACKQUOTED xyz), pull request in progress at https://github.com/D-Programming-Language/dmd/pull/4228. Maybe detect some __underscored__ or **bolded** words similarly. * Better whitespace control * Macros that expand without $() - possibly an extension of ESCAPES. * Add a subset of markdown on top of ddoc (details unclear). * Make [text](url) denote a link. * Hashtags for headings * Generate cross-references automatically. * Clever automatic linking or embedding of overridden functions docs. * Automatic links to source code. * Simplified signatures (__FILE__ etc, template constraints) * Replace some of the parens with indent nesting. * Not in that thread, but it was somewhere proposed that we use recursive macros for nice $(LIST item one, two, three). What did I miss? Among the more radical proposals: * Use markdown * Use doxygen Again, it seems to me these would yield little benefit for the effort even assuming perfect execution. Most of the ideas I had might require some redesign of the documentation layout, these are: * Summary of symbols * Documentation for private symbols * Simplified signatures * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses BTW the thing that have bothered me the most when writing documentation is there's no good way to even manually cross-reference symbols. We really should have a special syntax for that as well. -- /Jacob Carlborg
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 15:42:24 UTC, Andrei Alexandrescu wrote: Could you please fix or file these. Thanks! The D or DDox issue tracker? * 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.
Re: Ready to make page-per-item ddocs the default?
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?
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 00:06:28 UTC, Danny wrote: http://dlang.org/library/core/math/ldexp.html Compute n * 2⊃ Huh? Weird. It's `Compute n * 2$(SUP exp)` in the source[1]. SUP is a locally defined macro. Maybe ddox doesn't like local macros? 1. https://github.com/D-Programming-Language/druntime/blob/v2.066.1/src/core/math.d#L96
Re: Ready to make page-per-item ddocs the default?
http://dlang.org/library/core/math/ldexp.html Compute n * 2⊃ Huh?
Re: Ready to make page-per-item ddocs the default?
On Tuesday, 6 January 2015 at 23:44:30 UTC, weaselcat wrote: Is it intentional for all of the stdc pages to be empty? I think it's intentional that they don't duplicate the documentation for those headers, but we probably should add links to pages that document the C headers.
Re: Ready to make page-per-item ddocs the default?
std.string looks fine only the indexOfNeither and lastIndexOfNeither are missing
Re: Ready to make page-per-item ddocs the default?
On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. The table: http://dlang.org/phobos/std_math.html#.cos got lost: http://dlang.org/library/std/math/cos.html Also, the 2$(SUP 64). got turned into 2,64.
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 4:42 PM, Brad Anderson wrote: On Wednesday, 7 January 2015 at 00:06:28 UTC, Danny wrote: http://dlang.org/library/core/math/ldexp.html Compute n * 2⊃ Huh? Weird. It's `Compute n * 2$(SUP exp)` in the source[1]. SUP is a locally defined macro. Maybe ddox doesn't like local macros? 1. https://github.com/D-Programming-Language/druntime/blob/v2.066.1/src/core/math.d#L96 Yah, looks like a problem with ddox. Anyhow for now I fixed by using SUPERSCRIPT. https://github.com/D-Programming-Language/druntime/commit/8f655bbdd8f7aa77907053c918d78d2286c93ab2 http://dlang.org/library-prerelease/core/math/ldexp.html Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 4:26 PM, Robert burner Schadek wrote: std.string looks fine only the indexOfNeither and lastIndexOfNeither are missing Could you please fix -- thanks! -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 5:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. std.algorithm has many of the descriptions showing samples. Also, I know the table at the top is to make things easier for standard ddoc, should that be removed? BTW, I'm all for the docs to be switched. Just the cross-referencing alone is worth it. -Steve
Re: Ready to make page-per-item ddocs the default?
On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. In: http://dlang.org/library/std/algorithm/make_index.html if you click on the 'forward' link, it takes you to something quite unexpected. Looks like an issue with automatic cross referencing?
Re: Ready to make page-per-item ddocs the default?
On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages. -- Paul O'Neil Github / IRC: todayman
Re: Ready to make page-per-item ddocs the default?
On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Looks nice! And will provide motivation to fix a lot of the under-documented functions.
Re: Ready to make page-per-item ddocs the default?
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Very first function I looked at: http://dlang.org/library/std/string/format.html I find all the horizontal bar's throughout the docs quite noisy and tiring, and somewhat antiquated stylistically. I expected the parameters to jump out at me, but I didn't notice that that block surrounded by black lines and bold headings was actually the parameter list. I don't think I need headings to tell me which column is the name and which is the description. Ie, the parameters didn't jump out at me, the noise surrounding them did, and distracted me from the parameters themselves. There's obviously a bug here where the text is red too. My suggestions to make that page look more professional: * Prototype needs proper syntax highlighting, and elements (builtin types, types, template args, runtime args, and the function name itself) need to be styled distinctly (and tastefully). * The noise around the parameter listing can be removed completely. * The parameter name string in the parameter listing should match the styling of the prototype, so you can immediately recognise the thing in the prototype's description on the page. * The coloured box that houses the prototype is 6 times wider than it needs to be (on my monitor). I think it should be horizontally sized to fit the content. * Authors, license, and other uninteresting information should be spaced from the content (give an extra line-break or 2), and also the text should be significantly smaller. This is, literally, the fine-print. Comment box at the bottom is awesome! Taking another random sample: http://dlang.org/library/std/csv.html My previous criticisms stand equally. I feel like 'see also' should be the last thing before the 'fine print', not the first thing. Clicking through to see a class: http://dlang.org/library/std/csv/csv_exception.html Prior criticisms apply, but looks okay otherwise. There is 'fields' and 'methods', but they look the same. This is unexpected, since methods are functions, with return types, and arguments... why can't I see those? I'll leave it there for a moment. How do we style this stuff? Is there some way that we can experiment with styling ourselves?
Re: Ready to make page-per-item ddocs the default?
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another thought, since per-page docs result in a lot more page loads, this page *really* needs to be populated by ajax requests. It's wasteful to reload the whole page on every click. I'm in Australia, we don't really have internet in this country anymore! Is there a server that serves the raw data for the docs? It would be ideal for the client to format the page. We don't need to be sending HTML around.
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 07:06:42 UTC, Andrei Alexandrescu wrote: On 1/6/15 11:02 PM, Mathias LANG wrote: On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu wrote: On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote: On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page. That would be quite an involved project. -- Andrei I don't think so, since vibed.org has exactly that. I'm not familiar with JS, but I believe https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js could be a good starter place. Oh, nice. I would, however, hope we fix the many more pressing issues with dub right now. For starters, I have no idea how to fix http://dlang.org/library-prerelease/std/string/format.html in spite of having operated this: https://github.com/D-Programming-Language/phobos/commit/e03e647cea5a2cff0ff72195e8c7907127b3b5e6. How does documentation in std.format make it in std.string's documentation? Andrei That's funny. Looks like symbol publicly imported are generated (but not indexed). For example, icmp is there as well.
Re: Ready to make page-per-item ddocs the default?
On Tue, 06 Jan 2015 14:43:45 -0800 Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful. on the previous version it was not only enough to press home and see that, i was able to start quicksearching for other functions and read all the documentation without reloading the page (now two pages, actually). i don't know about others, but for me new version is like a modern smartphone: shiny, cool, looking pretty and making phone talks worser. signature.asc Description: PGP signature
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 7:27 PM, Paul O'Neil wrote: On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages. Thanks! -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 7:20 PM, Walter Bright wrote: On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. The table: http://dlang.org/phobos/std_math.html#.cos got lost: http://dlang.org/library/std/math/cos.html Also, the 2$(SUP 64). got turned into 2,64. https://github.com/D-Programming-Language/phobos/commit/7e766e6796a494de5a55c11d106889b47c303eff Andrei
Re: Ready to make page-per-item ddocs the default?
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page.
Re: Ready to make page-per-item ddocs the default?
On 7/01/2015 7:20 p.m., Manu via Digitalmars-d wrote: On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another thought, since per-page docs result in a lot more page loads, this page *really* needs to be populated by ajax requests. It's wasteful to reload the whole page on every click. I'm in Australia, we don't really have internet in this country anymore! Is there a server that serves the raw data for the docs? It would be ideal for the client to format the page. We don't need to be sending HTML around. I was thinking a little similarly. But using DDOC to generate JSON. Serve that from web server. Something like https://github.com/rikkimax/client-templating could be used to fill out based upon the data via widgets. Of course then it won't be prefilled when served but meh. Think Facebook's Big Pipe only more open.
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 7:27 PM, Paul O'Neil wrote: On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages. Fixed in http://dlang.org/library-prerelease/index.html. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 8:54 PM, Manu via Digitalmars-d wrote: On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Very first function I looked at: http://dlang.org/library/std/string/format.html I find all the horizontal bar's throughout the docs quite noisy and tiring, and somewhat antiquated stylistically. FWIW the table styling is the least problem with that page. Apparently the indexer messes up things quite a lot, making text red when it shouldn't and not rendering code correctly etc. I expected the parameters to jump out at me, but I didn't notice that that block surrounded by black lines and bold headings was actually the parameter list. I don't think I need headings to tell me which column is the name and which is the description. Ie, the parameters didn't jump out at me, the noise surrounding them did, and distracted me from the parameters themselves. So Name/Description should go? Also parameters should be in code font. There's obviously a bug here where the text is red too. Yah that's a biggie. Notice the code snippets that were supposed to be syntax colored too... Looks like that's a problem in the source. This looks just as bad: http://dlang.org/phobos/std_string.html#.format My suggestions to make that page look more professional: * Prototype needs proper syntax highlighting, and elements (builtin types, types, template args, runtime args, and the function name itself) need to be styled distinctly (and tastefully). * The noise around the parameter listing can be removed completely. * The parameter name string in the parameter listing should match the styling of the prototype, so you can immediately recognise the thing in the prototype's description on the page. * The coloured box that houses the prototype is 6 times wider than it needs to be (on my monitor). I think it should be horizontally sized to fit the content. * Authors, license, and other uninteresting information should be spaced from the content (give an extra line-break or 2), and also the text should be significantly smaller. This is, literally, the fine-print. Noice. Comment box at the bottom is awesome! Taking another random sample: http://dlang.org/library/std/csv.html My previous criticisms stand equally. I feel like 'see also' should be the last thing before the 'fine print', not the first thing. Clicking through to see a class: http://dlang.org/library/std/csv/csv_exception.html Prior criticisms apply, but looks okay otherwise. There is 'fields' and 'methods', but they look the same. This is unexpected, since methods are functions, with return types, and arguments... why can't I see those? I'll leave it there for a moment. How do we style this stuff? Is there some way that we can experiment with styling ourselves? Mainly css, see https://github.com/D-Programming-Language/dlang.org/tree/master/css. Some styling in the html.ddoc and other .ddoc files, see https://github.com/D-Programming-Language/dlang.org/tree/master/. Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote: On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page. That would be quite an involved project. -- Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 11:02 PM, Mathias LANG wrote: On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu wrote: On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote: On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page. That would be quite an involved project. -- Andrei I don't think so, since vibed.org has exactly that. I'm not familiar with JS, but I believe https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js could be a good starter place. Oh, nice. I would, however, hope we fix the many more pressing issues with dub right now. For starters, I have no idea how to fix http://dlang.org/library-prerelease/std/string/format.html in spite of having operated this: https://github.com/D-Programming-Language/phobos/commit/e03e647cea5a2cff0ff72195e8c7907127b3b5e6. How does documentation in std.format make it in std.string's documentation? Andrei
Re: Ready to make page-per-item ddocs the default?
On 1/6/2015 10:48 PM, Andrei Alexandrescu wrote: Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page. That would be quite an involved project. -- Andrei I find dman.exe to be very handy and use it all the time, but since it is a hand-built index, it is always hopelessly out of date.
Re: Ready to make page-per-item ddocs the default?
On 1/6/15 6:17 PM, Steven Schveighoffer wrote: On 1/6/15 5:43 PM, Andrei Alexandrescu wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. std.algorithm has many of the descriptions showing samples. Also, I know the table at the top is to make things easier for standard ddoc, should that be removed? But I like it. BTW, I'm all for the docs to be switched. Just the cross-referencing alone is worth it. One thing we need to do is offer for each module view as one page so people still have that option. Andrei
Re: Ready to make page-per-item ddocs the default?
On Wed, Jan 07, 2015 at 07:44:39AM +0200, ketmar via Digitalmars-d wrote: On Tue, 06 Jan 2015 14:43:45 -0800 Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful. [...] You should use Vimperator. :-P I started using it recently, didn't like it that much at first, but I'm starting to like it more and more. Thanks to the hinting system, my rodent is even more out-of-use nowadays, which I consider a Good Thing(tm). T -- LINUX = Lousy Interface for Nefarious Unix Xenophobes.
Re: Ready to make page-per-item ddocs the default?
On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu wrote: On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote: On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. Andrei Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page. That would be quite an involved project. -- Andrei I don't think so, since vibed.org has exactly that. I'm not familiar with JS, but I believe https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js could be a good starter place.
Re: Ready to make page-per-item ddocs the default?
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
Re: Ready to make page-per-item ddocs the default?
On Tue, 6 Jan 2015 22:32:05 -0800 H. S. Teoh via Digitalmars-d digitalmars-d@puremagic.com wrote: On Wed, Jan 07, 2015 at 07:44:39AM +0200, ketmar via Digitalmars-d wrote: On Tue, 06 Jan 2015 14:43:45 -0800 Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com wrote: Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful. [...] You should use Vimperator. :-P I started using it recently, didn't like it that much at first, but I'm starting to like it more and more. Thanks to the hinting system, my rodent is even more out-of-use nowadays, which I consider a Good Thing(tm). sadly, there is no such thing for Opera 12. T_T signature.asc Description: PGP signature
