Re: Worst Phobos documentation evar!
On Sun, Jan 04, 2015 at 08:56:28PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 5:07 PM, H. S. Teoh via Digitalmars-d wrote: > >I've yet to locate the cause of this problem, it's an unpleasant task > >trying to wade through the layers of make macro hacks in posix.mak to > >figure out what went wrong.) > > I'm not sympathetic because everyone hated my straightforward (but > voluminous) makefiles and changed them to what you see now. Yet another nail in the long-overdue coffin of make. T -- Winners never quit, quitters never win. But those who never quit AND never win are idiots.
Re: Worst Phobos documentation evar!
On 12/31/2014 5:07 PM, H. S. Teoh via Digitalmars-d wrote: I've yet to locate the cause of this problem, it's an unpleasant task trying to wade through the layers of make macro hacks in posix.mak to figure out what went wrong.) I'm not sympathetic because everyone hated my straightforward (but voluminous) makefiles and changed them to what you see now.
Re: Worst Phobos documentation evar!
On 1/3/2015 8:21 PM, Manu via Digitalmars-d wrote: template function(Arg) { @uda(Arg) void function() { ... } } Ah, interesting. I've never written a template function like that. Hmmm, is that how code is rewritten when compiling? If so, why doesn't it just work already? The stuff outside of the function is not in scope with the function, that's why. I'm not sure it should be put in the scope. I'm just saying where I'm at with it. It got stuck on problems I didn't-know-how/couldn't to resolve. I need to know my design is sound (ie, works), otherwise committing to the design is the wrong thing to do. You don't need forceinline to know if your design is sound.
Re: Worst Phobos documentation evar!
"Manu via Digitalmars-d" wrote in message news:mailman.4110.1420345278.9932.digitalmar...@puremagic.com... > > template function(Arg) > { > @uda(Arg) void function() { ... } > } Ah, interesting. I've never written a template function like that. Hmmm, is that how code is rewritten when compiling? If so, why doesn't it just work already? I'm pretty sure you were told about this last time you asked about the same thing. Yes, this is how the compiler re-writes function templates internally, but if you have udas: @uda(Arg) void function(Arg)() { ... } becomes @uda(Arg) template function(Arg) { void function() { ... } } This makes more sense when you remember that @uda(Arg) void function(Arg)() { ... } is identical to @uda(Arg) { void function(Arg)() { ... } } so it doesn't make a lot of sense to pull the UDA inside the template. One weird thing is that it doesn't work with postfix udas either: void function(Arg)() @uda(Arg) { ... } Would that be appropriate for your code if it worked? If so, it might be worth opening an enhancement.
Re: Worst Phobos documentation evar!
On 4 January 2015 at 13:48, Walter Bright via Digitalmars-d wrote: > On 1/2/2015 2:05 AM, Manu via Digitalmars-d wrote: >> >> This: >>@uda(Arg) void function(Arg)() >>{ >>} >> >> I need to be able to supply a template arg to a UDA. The runtime cpuid >> branching tech depends on it, and thus the whole API design depends on >> it. >> >> So, yeah they're all coming back to me now slowly :) >> There were a number of things I was blocked on. If I can't prove that >> my API approach works, then it needs to completely change. >> These things were blocking me from proving the design actually works. >> >> Can this one be addressed? > > > template function(Arg) > { > @uda(Arg) void function() { ... } > } Ah, interesting. I've never written a template function like that. Hmmm, is that how code is rewritten when compiling? If so, why doesn't it just work already? >> Well, it kinda does. Swapping register types is one of the biggest >> performance hazards there is. >> Use of SIMD opcodes will generate use of xmm regs. As much as I preach >> best practise is to commit 100% to SIMD, people will inevitably find >> themselves moving float data into SIMD regs. x64 should actually be >> the most tolerant of that sort of code, because float data *should* >> already be in xmm regs, but I think in our case we're going to see >> some pretty ordinary simd benchmarks whenever floats appear. The >> register swapping will very probably result in code that is slower >> than just issuing sequential float ops. > > > The best thing to do is make the library work, and then we go about making > it faster. > > The thing is, > > > M: Implement feature X and then I can deliver fantastic library A 2 years > later. > W: Ok, but I've got to first implement Y because it's blocking delivery of > fantastic library B today. > > > M: Implement feature X and then I can deliver fantastic library A tomorrow! > W: Ok, it's at the top of the queue! Don't get me wrong, I'm not trying to rearrange priorities. The stuff going on at the moment is super important! I'm just saying where I'm at with it. It got stuck on problems I didn't-know-how/couldn't to resolve. I need to know my design is sound (ie, works), otherwise committing to the design is the wrong thing to do.
Re: Worst Phobos documentation evar!
On 1/2/2015 2:05 AM, Manu via Digitalmars-d wrote: I don't believe in the utility of a customizable float implementation. There is one, but it is pretty much useless. For example, halffloat cannot be implemented using it. Why? The same reason I don't see a point to a 17 bit integer type. This: @uda(Arg) void function(Arg)() { } I need to be able to supply a template arg to a UDA. The runtime cpuid branching tech depends on it, and thus the whole API design depends on it. So, yeah they're all coming back to me now slowly :) There were a number of things I was blocked on. If I can't prove that my API approach works, then it needs to completely change. These things were blocking me from proving the design actually works. Can this one be addressed? template function(Arg) { @uda(Arg) void function() { ... } } Well, it kinda does. Swapping register types is one of the biggest performance hazards there is. Use of SIMD opcodes will generate use of xmm regs. As much as I preach best practise is to commit 100% to SIMD, people will inevitably find themselves moving float data into SIMD regs. x64 should actually be the most tolerant of that sort of code, because float data *should* already be in xmm regs, but I think in our case we're going to see some pretty ordinary simd benchmarks whenever floats appear. The register swapping will very probably result in code that is slower than just issuing sequential float ops. The best thing to do is make the library work, and then we go about making it faster. The thing is, M: Implement feature X and then I can deliver fantastic library A 2 years later. W: Ok, but I've got to first implement Y because it's blocking delivery of fantastic library B today. M: Implement feature X and then I can deliver fantastic library A tomorrow! W: Ok, it's at the top of the queue!
Re: Worst Phobos documentation evar!
On Friday, 2 January 2015 at 23:03:19 UTC, Walter Bright wrote: On 12/31/2014 4:39 PM, Adam D. Ruppe wrote: But the point is translating a module name to a Phobos link requires transformation code too complex for a ddoc macro... In my C++ compiler library documentation, I made a point in the code examples to hyperlink every call to a library function to the documentation for that library function. Yes, it would be nice to make this automatic. ironically needing something like LUCKY - an external search engine - to fix... LUCKY isn't the only macro I use to make horrific url's palatable. I also use them for Amazon links, for example. by the way, how about a link in the docs to source for methods, types and everything?
Re: Worst Phobos documentation evar!
On 12/31/2014 4:39 PM, Adam D. Ruppe wrote: But the point is translating a module name to a Phobos link requires transformation code too complex for a ddoc macro... In my C++ compiler library documentation, I made a point in the code examples to hyperlink every call to a library function to the documentation for that library function. Yes, it would be nice to make this automatic. ironically needing something like LUCKY - an external search engine - to fix... LUCKY isn't the only macro I use to make horrific url's palatable. I also use them for Amazon links, for example.
Re: Worst Phobos documentation evar!
On 01/01/15 23:48, Iain Buclaw via Digitalmars-d wrote: I've had the exact same talks as you. I would back any incentive to further push it further (I've only really made tidbit changes). Sounds good, maybe the three of us can follow up on this together some time in the not-too-distant future.
Re: Worst Phobos documentation evar!
On 02/01/15 10:59, Manu via Digitalmars-d wrote: Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work. I'm sure it would. What do you mean 'do something about real'? You mean that x87 is deprecated for more than 10 years now, and will probably go away at some point. I mean the fact that std.math functions on floating point are hardcoded to use real for their input and return types.
Re: Worst Phobos documentation evar!
On 2015-01-01 00:51, Rikki Cattermole wrote: I know. And btw currently ddoc cannot output json. I was considering some form of external tool that used e.g. DScanner to grab all the AST/comments and then parse them a little similar to DDoc just without the macros. You can already get the documentation when generating the JSON using the -X flag. That's how Ddox works, if I recall correctly. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2014-12-31 21:40, Walter Bright wrote: Documentation for code winds up on a web site. I find it very handy that the Ddoc embedded in D code, and the Ddoc used for the rest of the web site, all use the same style sheets, the same macro files, etc. And an ebook and pdf can all be generated from the same. If, hypothetically, Ddoc was removed and replaced with something completely different, that doesn't mean you need to stop using it. You could even continue to ship it with DMD was a separate tool. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2015-01-01 00:53, Walter Bright wrote: As I said, I grepped the Phobos sources for $(COMMA), and found 2 instances, neither of which were necessary. And how do you plan to find all commas that should actually be $(COMMA)? -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2015-01-01 00:52, Walter Bright wrote: On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote: ah, the following is even better: Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to. The point is to have consistent look and feel, not be able to customize every single thing. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2 January 2015 at 08:26, Walter Bright via Digitalmars-d wrote: > On 1/1/2015 6:43 AM, Manu via Digitalmars-d wrote: >>> >>> Make it work in dmd (with my help, of course) and prove the design. Then >>> GDC >>> will come along. >> >> >> I can't do anything that isn't supported by the GCC backend; that's >> the platform for almost all the cross-compilers, which I really care >> about. >> I also have a suspicion that anybody who uses SIMD seriously will >> probably be building with LDC or GCC because of improved codegen >> across the board. > > > Have to start somewhere. Or, it might rather just be best to drop such ambitious goals for the API from the first revision :/ >>> Half-float is here: >>> >>> http://digitalmars.com/sargon/halffloat.html >>> >>> in the Sargon component library :-) >> >> >> That's probably not the best place for it ;) >> What was the controversy blocking it? I don't remember. > > > I think the root issue was nobody thought it was useful other than you and > I. There is a reasonable issue about "should this really be in the Standard > Library, or an add-on?" > > I created Sargon as a place to put things I think would be generally useful, > but have been unable to convince others of. std.simd would ideally depend on it. half8 is a very useful SIMD primitive. It might be tricky to define a half8 type in std.simd alongside float4, short8, etc, that feels sufficiently related to the others and emits hardware opcodes. >>> It would be trivial to use halffloat as a model for building other custom >>> floating point types. >> >> >> Isn't there a competing custom float implementation though? >> Should they be unified? > > > I don't believe in the utility of a customizable float implementation. There > is one, but it is pretty much useless. For example, halffloat cannot be > implemented using it. Why? Well could custom float alternatively be implemented by generalising halffloat? But I agree that it's basically useless. Half float on the other hand is a standard type that appears in geometry and image data all the time these days. That stuff all needs forceinline too to be particularly useful. >>> >>> >>> >>> I agree, but that does NOT block you from designing and writing the code. >>> It >>> only blocks the final polish. >> >> >> I wrote the code years ago. I was at the point of polish where it got >> stuck on those issues... and unittest's, and documentation >_< > > > The last 10% of the work is always 90% of the work. Get it done! > > > >>> It also may be worthwhile to look through std.algorithm and see what can >>> be >>> specialized to use simd, such as string searching. >> >> >> SSE provides some special opcodes for string processing that aren't >> really portable, so I don't expect those would be expressed in >> std.simd, but they could be used opportunistically in other places. >> The main trouble is that they are SSE4.2, which is still sufficiently >> new that we can't rely on it's presence on end-user machines. How will >> we tell the compiler it is okay to use those opcodes? >> GCC/LDC have args to say what SSE level to build for. We need a way to >> query the requested SSE level in the code, and we also need that >> concept added to DMD. > > > std.algorithm is portable for the user. It is very accommodating for > specializations, so most definitely it can be specialized for x86 with SIMD. > > Some platforms, such as OSX, have a reliable minimum standard. This is why > we, for example, have abandoned 32 bit OSX. For others, a runtime switch > based on CPUID is fine. I don't think a runtime switch is practical that far down the call-tree. We need to be able to supply a SIMD level to the compiler, and ideally, also change it locally with a pragma or an attribute (GCC and Clang use an attribute). Runtime SIMD branch selection needs to be positioned as high up the stack as possible. >> So, where it sits is: DMD needs a commandline arg to request an SSE >> target level and made available to the code, I need to work out what >> to do about GDC, and I need to write the unittest's and docs... which >> is probably the biggest block tbh ;) >> Otherwise, it still rests in my fork where I left it. Some people have >> used it. When it's done I'll extend it to support matrices, and >> perhaps some higher-level linear algebra stuff. > > > The thing is, if you don't do the unittests and docs, you will be throwing > away all the other work you've done. If you do them, there will be a large > incentive to get forceinline working. I just recalled another problem actually. This: @uda(Arg) void function(Arg)() { } I need to be able to supply a template arg to a UDA. The runtime cpuid branching tech depends on it, and thus the whole API design depends on it. So, yeah they're all coming back to me now slowly :) There were a number of things I was blocked on. If I can't prove that my API approach works, then it needs to completely change. These things were blocking me from provi
Re: Worst Phobos documentation evar!
On 2 January 2015 at 08:40, Joseph Rushton Wakeling via Digitalmars-d wrote: > On 01/01/15 15:43, Manu via Digitalmars-d wrote: >> >> Oh yeah, and a massive one that I've discussed with Ethan and I think >> he's discussed with you; DMD likes to use the x87 in win64 builds... >> that's really no good. We can't be swapping between x87 and xmm regs. >> float/double args are passed in xmm according to the ABI, and then >> everywhere a float operation is performed, a swap from xmm -> x87 is >> emitted, and then back again. It's madness. You're gonna have to let >> the x87 go on x64 ;) > > > Don't know if it's entirely the same issue, but Don C. and I have been > having occasional (admittedly fairly casual) chats about the need to do > something about std.math and its use of real. I don't want to make any > strong promises (far too much going on work-wise), but I could well be > persuaded to look into that with some seriousness, if it could be helpfully > related to std.simd work. I'm sure it would. What do you mean 'do something about real'? You mean that x87 is deprecated for more than 10 years now, and will probably go away at some point.
Re: Worst Phobos documentation evar!
"H. S. Teoh via Digitalmars-d" wrote in message news:mailman.3882.1420060673.9932.digitalmar...@puremagic.com... Yeah no kidding. How do I hate make? Let me count the ways: ... Most of these are only problems with large projects, and large makefiles. For smaller projects make is vastly superior to a shell script, and almost always already installed.
Re: Worst Phobos documentation evar!
On 1 January 2015 at 22:40, Joseph Rushton Wakeling via Digitalmars-d wrote: > On 01/01/15 15:43, Manu via Digitalmars-d wrote: >> >> Oh yeah, and a massive one that I've discussed with Ethan and I think >> he's discussed with you; DMD likes to use the x87 in win64 builds... >> that's really no good. We can't be swapping between x87 and xmm regs. >> float/double args are passed in xmm according to the ABI, and then >> everywhere a float operation is performed, a swap from xmm -> x87 is >> emitted, and then back again. It's madness. You're gonna have to let >> the x87 go on x64 ;) > > > Don't know if it's entirely the same issue, but Don C. and I have been > having occasional (admittedly fairly casual) chats about the need to do > something about std.math and its use of real. I don't want to make any > strong promises (far too much going on work-wise), but I could well be > persuaded to look into that with some seriousness, if it could be helpfully > related to std.simd work. I've had the exact same talks as you. I would back any incentive to further push it further (I've only really made tidbit changes).
Re: Worst Phobos documentation evar!
On 01/01/15 15:43, Manu via Digitalmars-d wrote: Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm -> x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;) Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work.
Re: Worst Phobos documentation evar!
On 31/12/14 12:25, Walter Bright via Digitalmars-d wrote: What you can contribute that would be very valuable is what we've discussed before - your simd expertise. Your influence is what has shaped the current simd support. I don't know anyone who knows even half of what you do about simd. What you know could make D really fly with vector math. You and I both know that auto vectorization, the approach used by everyone else, is not the key to high performance simd. We have an opportunity here. FWIW Manu, I would be really excited to see what you could put together here. :-)
Re: Worst Phobos documentation evar!
On 1/1/2015 6:43 AM, Manu via Digitalmars-d wrote: Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along. I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board. Have to start somewhere. Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-) That's probably not the best place for it ;) What was the controversy blocking it? I don't remember. I think the root issue was nobody thought it was useful other than you and I. There is a reasonable issue about "should this really be in the Standard Library, or an add-on?" I created Sargon as a place to put things I think would be generally useful, but have been unable to convince others of. It would be trivial to use halffloat as a model for building other custom floating point types. Isn't there a competing custom float implementation though? Should they be unified? I don't believe in the utility of a customizable float implementation. There is one, but it is pretty much useless. For example, halffloat cannot be implemented using it. That stuff all needs forceinline too to be particularly useful. I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish. I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation >_< The last 10% of the work is always 90% of the work. Get it done! It also may be worthwhile to look through std.algorithm and see what can be specialized to use simd, such as string searching. SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD. std.algorithm is portable for the user. It is very accommodating for specializations, so most definitely it can be specialized for x86 with SIMD. Some platforms, such as OSX, have a reliable minimum standard. This is why we, for example, have abandoned 32 bit OSX. For others, a runtime switch based on CPUID is fine. So, where it sits is: DMD needs a commandline arg to request an SSE target level and made available to the code, I need to work out what to do about GDC, and I need to write the unittest's and docs... which is probably the biggest block tbh ;) Otherwise, it still rests in my fork where I left it. Some people have used it. When it's done I'll extend it to support matrices, and perhaps some higher-level linear algebra stuff. The thing is, if you don't do the unittests and docs, you will be throwing away all the other work you've done. If you do them, there will be a large incentive to get forceinline working. Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm -> x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;) That shouldn't affect vector code.
Re: Worst Phobos documentation evar!
On 12/31/14 3:51 PM, Rikki Cattermole wrote: On 1/01/2015 4:23 a.m., Jacob Carlborg wrote: On 2014-12-30 06:13, Rikki Cattermole wrote: Hmm I have an idea. I wonder if I can get ddoc to generate json files. You would still need to write the documentation in Ddoc, which is what we're complaining about. I know. And btw currently ddoc cannot output json. Json generation should follow this mold: https://github.com/D-Programming-Language/dlang.org/pull/737 -- Andrei
Re: Worst Phobos documentation evar!
On 1 January 2015 at 19:47, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 8:46 PM, Manu via Digitalmars-d wrote: >> >> Okay, well it's not really useful without a forceinline attribute. >> std.simd functions need to be pseudo-intrinsics, ie, the cost of a >> function call will definitely negate the work they perform. >> Yes, they will (probably) be inlined in release, but debug performance >> is also important, and I can't have maths code that runs much slower >> in debug builds because it makes a function call passing structs by >> value for every single maths opcode in the hottest loops. >> >> There were also troubles with GDC; I haven't been able to make it emit >> the opcode that I want. It reinterprets to emit something else >> depending on the SSE level argument passed to the compiler. There are >> attributes to set the 'target' per-function, but that didn't work for >> some reason, so I need to work out if that can be resolved, otherwise >> my whole approach (goal of being able to generate multiple SIMD >> version code paths for runtime selection) won't work (in GCC)... >> >> We need to get a quality low-level API out there, that is portable, >> and fills gaps in the various architectures, then we can focus on >> high-level wrappers and niceties. > > > Make it work in dmd (with my help, of course) and prove the design. Then GDC > will come along. I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board. >> I really want to see your half-float module merged. Where did that go? >> I recall some people were saying it should be conflated with the >> custom-float stuff, so half-float was just a specialisation of custom >> float... > > > Half-float is here: > > http://digitalmars.com/sargon/halffloat.html > > in the Sargon component library :-) That's probably not the best place for it ;) What was the controversy blocking it? I don't remember. >> I'm not so sure about that... but maybe? I have been needing a 3.7 >> (10bit) float too, maybe that fits in there? > > > It would be trivial to use halffloat as a model for building other custom > floating point types. Isn't there a competing custom float implementation though? Should they be unified? >> That stuff all needs forceinline too to be particularly useful. > > > I agree, but that does NOT block you from designing and writing the code. It > only blocks the final polish. I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation >_< > It also may be worthwhile to look through std.algorithm and see what can be > specialized to use simd, such as string searching. SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD. So, where it sits is: DMD needs a commandline arg to request an SSE target level and made available to the code, I need to work out what to do about GDC, and I need to write the unittest's and docs... which is probably the biggest block tbh ;) Otherwise, it still rests in my fork where I left it. Some people have used it. When it's done I'll extend it to support matrices, and perhaps some higher-level linear algebra stuff. Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm -> x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;)
Re: Worst Phobos documentation evar!
On 31/12/14 14:50, Joseph Rushton Wakeling via Digitalmars-d wrote: Second and more importantly, I ran into some tricky cases implementing Params: lists for functions that have multiple overloads with different parameter lists. Slightly more subtle variant of same: if the first, documented code is a struct or class definition, and the /// ditto'd code blocks are factory functions to generate instances of that code, you get the same warnings, and it means that _none_ of the parameters will have type info attached. (Encountered with e.g. randomCover and randomSample.) On the bright side, PR is in :-) https://github.com/D-Programming-Language/phobos/pull/2831
Re: Worst Phobos documentation evar!
On 12/31/2014 8:46 PM, Manu via Digitalmars-d wrote: Okay, well it's not really useful without a forceinline attribute. std.simd functions need to be pseudo-intrinsics, ie, the cost of a function call will definitely negate the work they perform. Yes, they will (probably) be inlined in release, but debug performance is also important, and I can't have maths code that runs much slower in debug builds because it makes a function call passing structs by value for every single maths opcode in the hottest loops. There were also troubles with GDC; I haven't been able to make it emit the opcode that I want. It reinterprets to emit something else depending on the SSE level argument passed to the compiler. There are attributes to set the 'target' per-function, but that didn't work for some reason, so I need to work out if that can be resolved, otherwise my whole approach (goal of being able to generate multiple SIMD version code paths for runtime selection) won't work (in GCC)... We need to get a quality low-level API out there, that is portable, and fills gaps in the various architectures, then we can focus on high-level wrappers and niceties. Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along. I really want to see your half-float module merged. Where did that go? I recall some people were saying it should be conflated with the custom-float stuff, so half-float was just a specialisation of custom float... Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-) I'm not so sure about that... but maybe? I have been needing a 3.7 (10bit) float too, maybe that fits in there? It would be trivial to use halffloat as a model for building other custom floating point types. That stuff all needs forceinline too to be particularly useful. I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish. It also may be worthwhile to look through std.algorithm and see what can be specialized to use simd, such as string searching.
Re: Worst Phobos documentation evar!
On 12/31/14 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. Just write $(ARGS lots, of, commas). -- Andrei
Re: Worst Phobos documentation evar!
Rikki Cattermole wrote: > On 1/01/2015 4:23 a.m., Jacob Carlborg wrote: >> On 2014-12-30 06:13, Rikki Cattermole wrote: >> >>> Hmm I have an idea. >>> I wonder if I can get ddoc to generate json files. >> >> You would still need to write the documentation in Ddoc, which is what >> we're complaining about. > > I know. > And btw currently ddoc cannot output json. If ddoc cannot generate json that's a bug in ddoc. -- Andrei
Re: Worst Phobos documentation evar!
On 31 December 2014 at 21:25, Walter Bright via Digitalmars-d wrote: > What you can contribute that would be very valuable is what we've discussed > before - your simd expertise. Your influence is what has shaped the current > simd support. I don't know anyone who knows even half of what you do about > simd. What you know could make D really fly with vector math. > > You and I both know that auto vectorization, the approach used by everyone > else, is not the key to high performance simd. We have an opportunity here. Okay, well it's not really useful without a forceinline attribute. std.simd functions need to be pseudo-intrinsics, ie, the cost of a function call will definitely negate the work they perform. Yes, they will (probably) be inlined in release, but debug performance is also important, and I can't have maths code that runs much slower in debug builds because it makes a function call passing structs by value for every single maths opcode in the hottest loops. There were also troubles with GDC; I haven't been able to make it emit the opcode that I want. It reinterprets to emit something else depending on the SSE level argument passed to the compiler. There are attributes to set the 'target' per-function, but that didn't work for some reason, so I need to work out if that can be resolved, otherwise my whole approach (goal of being able to generate multiple SIMD version code paths for runtime selection) won't work (in GCC)... We need to get a quality low-level API out there, that is portable, and fills gaps in the various architectures, then we can focus on high-level wrappers and niceties. I really want to see your half-float module merged. Where did that go? I recall some people were saying it should be conflated with the custom-float stuff, so half-float was just a specialisation of custom float... I'm not so sure about that... but maybe? I have been needing a 3.7 (10bit) float too, maybe that fits in there? That stuff all needs forceinline too to be particularly useful.
Re: Worst Phobos documentation evar!
On 12/31/2014 5:00 PM, Dicebot wrote: It is the way original author has formatted. There is indentation so must be not accidental. If you saw a piece of crummy code in language X, that means language X is a bad programming language?
Re: Worst Phobos documentation evar!
On 12/31/14 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. I agree that Markdown, especially Github's, has become a de facto standard. That's nice because tools and expertise are easy to find. It's a good argument. -- Andrei
Re: Worst Phobos documentation evar!
On Thu, Jan 01, 2015 at 01:56:43AM +0100, Joseph Rushton Wakeling via Digitalmars-d wrote: > On 01/01/15 01:42, H. S. Teoh via Digitalmars-d wrote: > >git bisect on dlang.org revealed that the problem is caused by commit > >8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84. > > > ># first bad commit: [8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84] Much nicer > >jump-to anchors > > > >I *did* say that this change would be problematic, but was summarily > >ignored. >:-( > > Ouch, nasty. :-( Any chance this could be reverted short-term until it's > resolved properly? I tried reverting on github but it failed because it conflicts with later commits. :-( You *could* just `git checkout fbc73d2d78e6b51ebb92aac1a602fbfc4dde` to get an older version of dlang.org that doesn't have that change; that should temporarily make things work again until we figure out how to clean up this mess. (And btw, while troubleshooting this, I ran into a totally nasty dependency problem in phobos/posix.mak where somehow it gets into a bad state where it stops rebuilding .html files, and attempting to clean those files will cause make to start aborting with "No rule to build index.html needed by rule `html`" for no discernible reason. Talk about non-reproducible builds... I hate make soo much right now. :-/ I've yet to locate the cause of this problem, it's an unpleasant task trying to wade through the layers of make macro hacks in posix.mak to figure out what went wrong.) T -- "You are a very disagreeable person." "NO."
Re: Worst Phobos documentation evar!
On Thursday, 1 January 2015 at 00:21:42 UTC, Walter Bright wrote: It's quite unfair to not bother with whitespace formatting in one but not the other. It's like the "before" and "after" advertisements for cosmetics where the "before" has uncombed hair, poor lighting, is frowning, didn't brush their teeth, frumpy clothes, etc., and you know what they did with the "after" picture. It is the way original author has formatted. There is indentation so must be not accidental. Furthermore, the person who wrote the Ddoc macros not only did not bother to format, he also used unnecessary markup - the $(ARGS) is redundant. Probably because it is so hard to understand what is necessary and what isn't? Making some effort myself: $(TABLE2 Kinds of Arrays, $(THEAD Syntax, Description ) $(TROW $(I type*), $(LINK2 #pointers, Pointers to data) ) $(TROW $(I type[integer]), $(LINK2 #static-arrays, Static arrays)) ) versus: |Kinds of Arrays| |---| |Syntax|Description| |-| |`type*`|[Pointers to data](/arrays.html#pointers)| |`type[integer]`|[Static arrays](/arrays.html#static-arrays)| Second version still looks much more clear to me, despite intentionally screwed formatting. It is a problem of noise-to-content ratio and it is hard to compete with ASCII art in terms of readability.
Re: Worst Phobos documentation evar!
On Thu, Jan 01, 2015 at 12:54:39AM +, Adam D. Ruppe via Digitalmars-d wrote: > On Thursday, 1 January 2015 at 00:05:10 UTC, Kiith-Sa wrote: > >DDoc with Markdown > > This is the biggest deal: what people are talking about is actually > not that different from what ddoc already does! > > If you write: > > /** > Something here. > > Something else here. > */ > > Ddoc ALREADY converts that into: > > $(DDOC_SUMMARY Something here.) > > $(DDOC_DESCRIPTION Something else here.) > > > (Which tbh sometimes bugs me, I don't like how "Given: foo" alwas > turns into a DDOC_SECTION) Ddoc has this ugly hack where if you want to suppress certain default behaviours, you stick _ in front of it. For example: _Given: x = ... will output "Given: x = ..." without a section heading, whereas removing the _ will make "Given" a section heading. There's also the (undocumented?) behaviour where multi-word headings are not recognized as such: My heading: blah blah blah does not produce a heading for "My heading". However, if you make it a single word by using _ instead of a space, then it will become a heading: My_heading: blah blah blah the _ gets replaced with a space in the output. Now I wonder what you'd have to do if you wanted a literal _ in the heading... or a word in the text... I'm guessing it's time for $(UNDERSCORE) all over again. T -- Shin: (n.) A device for finding furniture in the dark.
Re: Worst Phobos documentation evar!
On 01/01/15 01:42, H. S. Teoh via Digitalmars-d wrote: git bisect on dlang.org revealed that the problem is caused by commit 8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84. # first bad commit: [8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84] Much nicer jump-to anchors I *did* say that this change would be problematic, but was summarily ignored. >:-( Ouch, nasty. :-( Any chance this could be reverted short-term until it's resolved properly?
Re: Worst Phobos documentation evar!
On Thursday, 1 January 2015 at 00:05:10 UTC, Kiith-Sa wrote: DDoc with Markdown This is the biggest deal: what people are talking about is actually not that different from what ddoc already does! If you write: /** Something here. Something else here. */ Ddoc ALREADY converts that into: $(DDOC_SUMMARY Something here.) $(DDOC_DESCRIPTION Something else here.) (Which tbh sometimes bugs me, I don't like how "Given: foo" alwas turns into a DDOC_SECTION) Anyway, the point is that ddoc is ALREADY a variant on the markdown style of languages! Those paragraphs are assumed to have semantic meaning and converted into macros for the output. What people really are proposing is to add a few more macro shorthands. Like `foo` being changed to $(D foo). None of the ddoc flexibility would be lost and you can still define your own macros. The only difference is there'd be a few more conversions done just the way DDOC_SUMMARY is done now.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 16:39:10 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 4:16 PM, ketmar via Digitalmars-d wrote: > > i devised this sample without deep design, of course, yet it's already > > human-readable and can be used to generate any kind of table. > > You took care to carefully format your version and made no effort with the > Ddoc > version. didn't you read my post in a whole? maybe that wall of Ddoc text forces you to drop reading? i wrote that "it doesn't matter how much efforts you will put into latest, it will look like linenoise anyway." there are more macroformatting, and all that macros are still YELLING at me. it doesn't matter how good i'll format Ddoc version, it will not magically becomes human-readable due to all that macro crap. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 04:01:14PM -0800, H. S. Teoh via Digitalmars-d wrote: > On Wed, Dec 31, 2014 at 03:57:32PM -0800, Andrei Alexandrescu via > Digitalmars-d wrote: > > On 12/31/14 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: > > > > > >First, it looks like the build system has changed since I last tried > > >building docs. If I go with 'make html' in my local phobos branch, > > >the various html files generated are all empty -- with their content > > >seemingly intended to be filled by javascript which doesn't work. > > >What gives? :-( > > > > Not sure. That should work, no js no nothing. -- Andrei > > I'm seeing this problem as well, after updating to the latest dlang.org > and phobos repos. Now I can't work on any ddoc PR's, 'cos I can't see > the results anymore. :-( git bisect on dlang.org revealed that the problem is caused by commit 8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84. # first bad commit: [8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84] Much nicer jump-to anchors I *did* say that this change would be problematic, but was summarily ignored. >:-( T -- One Word to write them all, One Access to find them, One Excel to count them all, And thus to Windows bind them. -- Mike Champion
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 23:53:48 UTC, Walter Bright wrote: Have fun with LUCKY in markdown. LUCKY sucks anyway, it would be better to provide a regular link to something directly useful, even Wikipedia (which is usually the one I go straight to, and if I want more, I'll Bing it myself, thank you very much). Here's a counterpoint: make a Ddoc macro that links to the documentation of a given symbol. $(DOC std.array.array) It needs to somehow get here: http://dlang.org/phobos/std_array.html#.array The existing solution in Phobos' macros is something like this: $(XREF range,chain) But, how to you convert a name, say in a code example, to that macro without manual intervention? One of the things I like most about ddoc is the code example highlighting. Indeed, I decided to use it last night to start writing the draft of my DConf 2015 proposal: http://arsdnet.net/dcode/talk-2015.dd http://arsdnet.net/dcode/talk-2015.html Not bad, got some easy syntax highlighting and it wasn't painful to write at all. ...but when documenting code, it is nice to be able to click on names and see more information. To compile the ddoc, all imports need to resolve. Why not go ahead and make "import std.variant;" available for linking somehow? We could make it call a macro like $(XREF std.variant) but how do we get that to the link, phobos/std_variant.html? We can't do a call to replace(".", "_"). Well, I do have a solution for this: my dpldocs.info site. http://dpldocs.info/std.variant which for a while redirected to the Phobos site, then I found that useless since dlang.org couldn't link overloads and I just displayed the comment myself... but I think I'll go back to redirecting now that we can link to it. But the point is translating a module name to a Phobos link requires transformation code too complex for a ddoc macro... ironically needing something like LUCKY - an external search engine - to fix...
Re: Worst Phobos documentation evar!
On 12/31/2014 4:16 PM, ketmar via Digitalmars-d wrote: i devised this sample without deep design, of course, yet it's already human-readable and can be used to generate any kind of table. You took care to carefully format your version and made no effort with the Ddoc version.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 16:21:26 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 3:03 PM, Dicebot wrote: > > One of the very first lines: > > > > $(TABLE2 Kinds of Arrays, > > $(THEAD Syntax, Description) > > $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, > > Pointers > > to data))) > > $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2 > > static-arrays, Static arrays))) > > $(TROW $(ARGS $(I type)[]), $(ARGS $(RELATIVE_LINK2 > > dynamic-arrays, > > Dynamic arrays))) > > $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map, > > Associative Arrays, Associative arrays))) > > ) > > > Making some effort myself: > > $(TABLE2 Kinds of Arrays, >$(THEAD Syntax, Description ) >$(TROW $(I type*), $(LINK2 #pointers, Pointers to data) ) >$(TROW $(I type[integer]), $(LINK2 #static-arrays, Static arrays)) > ) not really better. it's still noisy and it's still YELLING AT ME, disctracting me from the actual text. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 3:03 PM, Dicebot wrote: One of the very first lines: $(TABLE2 Kinds of Arrays, $(THEAD Syntax, Description) $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, Pointers to data))) $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2 static-arrays, Static arrays))) $(TROW $(ARGS $(I type)[]), $(ARGS $(RELATIVE_LINK2 dynamic-arrays, Dynamic arrays))) $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map, Associative Arrays, Associative arrays))) ) I had no idea of what it is and how it will look like after doc generation until started checking each macro one by one. Similar stuff in md: | Kinds of Arrays| |--| | Syntax | Description | |--| |`type*` | [Pointers to data](/arrays.html#pointers) | |`type[integer]` | [Static arrays](/arrays.html#static-arrays) | // etc. It's quite unfair to not bother with whitespace formatting in one but not the other. It's like the "before" and "after" advertisements for cosmetics where the "before" has uncombed hair, poor lighting, is frowning, didn't brush their teeth, frumpy clothes, etc., and you know what they did with the "after" picture. Furthermore, the person who wrote the Ddoc macros not only did not bother to format, he also used unnecessary markup - the $(ARGS) is redundant. Making some effort myself: $(TABLE2 Kinds of Arrays, $(THEAD Syntax, Description ) $(TROW $(I type*), $(LINK2 #pointers, Pointers to data) ) $(TROW $(I type[integer]), $(LINK2 #static-arrays, Static arrays)) ) versus: |Kinds of Arrays| |---| |Syntax|Description| |-| |`type*`|[Pointers to data](/arrays.html#pointers)| |`type[integer]`|[Static arrays](/arrays.html#static-arrays)|
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 15:52:45 -0800 Walter Bright via Digitalmars-d wrote: > The point is, you do not have to use the macros if Ddoc if you don't want to. the point is that i can't have documentation that both readable without preprocessing and generates good standalone files. i have to choose one of that. ah, and then i'll stick to my own documenting rules, 'cause i will not use Ddoc to generate anything anyway. it's not that hard to extend human-readable markup language to allow some D-specific features. i already wrote that this can be any language, not necessary markdown. like this, for example: =|Function Name|Description|= |`boyerMooreFinder` | `find("hello world", boyerMooreFinder("or"))` returns `"orld"` using the (Byer-Moore algorithm)[1]. |`count` | Counts elements that are equal to a specified value or satisfy a predicate. `count([1, 2, 1], 1))` returns `2` and `count!"a < 0"([1, -3, 0])` returns `1`. [1] https://some-long-link-with-alot-of-args now compare with this: $(TR $(TH Function Name) $(TH Description) ) $(TR $(TDNW $(LREF boyerMooreFinder)) $(TD $(D find("hello world", boyerMooreFinder("or"))) returns $(D "orld") using the $(LUCKY Boyer-Moore _algorithm).) ) $(TR $(TDNW $(LREF count)) $(TD Counts elements that are equal to a specified value or satisfy a predicate. $(D count([1, 2, 1], 1)) returns $(D 2) and $(D count!"a < 0"([1, -3, 0])) returns $(D 1).) ) it doesn't matter how much efforts you will put into latest, it will look like linenoise anyway. yes, documentation processor should be able to see that `boyerMooreFinder` and `count` are declared in the respective module and turn that to internal links. i can't see why i should do the work that computer can do for me. i devised this sample without deep design, of course, yet it's already human-readable and can be used to generate any kind of table. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 23:53:48 UTC, Walter Bright wrote: On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote: ah, the following is even better: Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to. seriously, which part of: DDoc with Markdown do you fail to understand? This: http://defenestrate.eu/docs/tharsis-core/concepts/process.html is the kind of article I write in my documentation (one of the first few, there will be about 10 more). It's in ReStructuredText, which again, is pretty much a more feature-rich Markdown. I couldn't do that with DDoc without an extremely unreadable source; now, with DDoc+Markdown (https://github.com/kiith-sa/harbored-mod), I can do it with maybe one macro for the admonitions.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 03:57:32PM -0800, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/31/14 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: > > > >First, it looks like the build system has changed since I last tried > >building docs. If I go with 'make html' in my local phobos branch, > >the various html files generated are all empty -- with their content > >seemingly intended to be filled by javascript which doesn't work. > >What gives? :-( > > Not sure. That should work, no js no nothing. -- Andrei I'm seeing this problem as well, after updating to the latest dlang.org and phobos repos. Now I can't work on any ddoc PR's, 'cos I can't see the results anymore. :-( T -- I've been around long enough to have seen an endless parade of magic new techniques du jour, most of which purport to remove the necessity of thought about your programming problem. In the end they wind up contributing one or two pieces to the collective wisdom, and fade away in the rearview mirror. -- Walter Bright
Re: Worst Phobos documentation evar!
On 12/31/14 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: First, it looks like the build system has changed since I last tried building docs. If I go with 'make html' in my local phobos branch, the various html files generated are all empty -- with their content seemingly intended to be filled by javascript which doesn't work. What gives? :-( Not sure. That should work, no js no nothing. -- Andrei
Re: Worst Phobos documentation evar!
On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote: ah, the following is even better: Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to.
Re: Worst Phobos documentation evar!
On 1/01/2015 4:23 a.m., Jacob Carlborg wrote: On 2014-12-30 06:13, Rikki Cattermole wrote: Hmm I have an idea. I wonder if I can get ddoc to generate json files. You would still need to write the documentation in Ddoc, which is what we're complaining about. I know. And btw currently ddoc cannot output json. I was considering some form of external tool that used e.g. DScanner to grab all the AST/comments and then parse them a little similar to DDoc just without the macros.
Re: Worst Phobos documentation evar!
On 12/31/2014 2:05 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 01:51:25PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. And Markdown never needs escapes. Right. :-) It needs escapes in far less places than ddoc does. When escapes are inescapable(!), you want the solution with less occurrences, not the solution with more. As I said, I grepped the Phobos sources for $(COMMA), and found 2 instances, neither of which were necessary.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 15:26:04 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 2:28 PM, ketmar via Digitalmars-d wrote: > > i can do Ddoc myself, i just can't read the result. > > > > / > This function does blah, blah, blah. > > Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. > > Params: > x = the awesome input value > > Returns: > insightful description of the return value > > Example: > --- > int foo(int x) { ... stunning D code ... } > --- > ***/ > Implements the homonym function (also known as $(D accumulate), $(D compress), $(D inject), or $(D foldl)) present in various programming languages of functional flavor. The call $(D reduce!(fun)(seed, range)) first assigns $(D seed) to an internal variable $(D result), also called the accumulator. Then, for each element $(D x) in $(D range), $(D result = fun(result, x)) gets evaluated. Finally, $(D result) is returned. The one-argument version $(D reduce!(fun)(range)) works similarly, but it uses the first element of the range as the seed (the range must be non-empty). 'cmon, wtf all that $(XXX) crap is? and with capitals, which distracts from the actual text. ah, the following is even better: $(BOOKTABLE Cheat Sheet, $(TR $(TH Function Name) $(TH Description) ) $(LEADINGROW Searching ) $(TR $(TDNW $(LREF all)) $(TD $(D all!"a > 0"([1, 2, 3, 4])) returns $(D true) because all elements are positive) ) $(TR $(TDNW $(LREF any)) $(TD $(D any!"a > 0"([1, 2, -3, -4])) returns $(D true) because at least one element is positive) ) $(TR $(TDNW $(LREF balancedParens)) $(TD $(D balancedParens("((1 + 1) / 2)")) returns $(D true) because the string has balanced parentheses.) ) $(TR $(TDNW $(LREF boyerMooreFinder)) $(TD $(D find("hello world", boyerMooreFinder("or"))) returns $(D "orld") using the $(LUCKY Boyer-Moore _algorithm).) ) $(TR $(TDNW $(LREF canFind)) $(TD $(D canFind("hello world", "or")) returns $(D true).) ) $(TR $(TDNW $(LREF count)) $(TD Counts elements that are equal to a specified value or satisfy a predicate. $(D count([1, 2, 1], 1)) returns $(D 2) and $(D count!"a < 0"([1, -3, 0])) returns $(D 1).) ) $(TR $(TDNW $(LREF countUntil)) $(TD $(D countUntil(a, b)) returns the number of steps taken in $(D a) to reach $(D b); for example, $(D countUntil("hello!", "o")) returns $(D 4).) ) $(TR $(TDNW $(LREF commonPrefix)) $(TD $(D commonPrefix("parakeet", "parachute")) returns $(D "para").) ) this goes on and on and on. this is just a line noise. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 2:28 PM, ketmar via Digitalmars-d wrote: i can do Ddoc myself, i just can't read the result. / This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***/
Re: Worst Phobos documentation evar!
On 12/31/2014 2:47 PM, Ary Borenszweig wrote: I'm not saying that it's popular, but people keep inventing things to avoid makefiles (and I think it's good to have this for a language). People keep inventing new markup formats, too. (The first one I used, runoff, dates from the 70's.) I think the unix .man markup is even older.
Re: Worst Phobos documentation evar!
On 12/31/2014 2:47 PM, H. S. Teoh via Digitalmars-d wrote: The macro system in make is so bad, it shouldn't need an explicit mention to be obvious that it's bad. It's so bad you didn't mention it in the thread about the only similarity between make and Ddoc? C'mon. Besides, macros are where the various flavors of make differ the most anyway, Those are the various extensions people have added, and Ddoc copies none of those. That complaint about make macros is irrelevant to Ddoc.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 22:53:14 UTC, Ary Borenszweig wrote: It looks quite clean to me: https://github.com/D-Programming-Language/dlang.org/blob/master/arrays.dd One of the very first lines: $(TABLE2 Kinds of Arrays, $(THEAD Syntax, Description) $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, Pointers to data))) $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2 static-arrays, Static arrays))) $(TROW $(ARGS $(I type)[]), $(ARGS $(RELATIVE_LINK2 dynamic-arrays, Dynamic arrays))) $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map, Associative Arrays, Associative arrays))) ) I had no idea of what it is and how it will look like after doc generation until started checking each macro one by one. Similar stuff in md: | Kinds of Arrays| |--| | Syntax | Description | |--| |`type*` | [Pointers to data](/arrays.html#pointers) | |`type[integer]` | [Static arrays](/arrays.html#static-arrays) | // etc. it is just so much easier to work with : resembles actual generated layout, less noise from service symbols, no special macros for basic things. It may be somewhat less maintainable because everything is hard-coded but it is not something that changes casually.
Re: Worst Phobos documentation evar!
On 12/31/14 7:46 PM, Dicebot wrote: On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig wrote: You are right. I browsed some phobo's code and saw the documentation, it looks clean and nice. The only exception is std.algorithm which is full of macros and barely readable. So where is that other macro code? The one that has $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed? IMHO biggest issue is not inline documentation for functions but more higher level stuff like http://dlang.org/arrays.html - it was all in DDOC too last time I checked and changing anything about it is hardly a pleasure. Inline documentations only suffers when more pretty stuff like tables gets added. It looks quite clean to me: https://github.com/D-Programming-Language/dlang.org/blob/master/arrays.dd Except for the fact that instead of the familiar HTML tags there are macros. I see macros for: Paragraphs: $(P) Lists: $(UL), $(LI) Links: $(HTTP) These are very, very, vry common in documentation and sites. Couldn't DDoc provide nice, readable ways for dealing with these?
Re: Worst Phobos documentation evar!
On 12/31/14 7:43 PM, Ary Borenszweig wrote: On 12/31/14 7:14 PM, Walter Bright wrote: On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it. Oh, it's for Nimrod (Now Nim) This one: https://github.com/fowlmouth/nake I'm not saying that it's popular, but people keep inventing things to avoid makefiles (and I think it's good to have this for a language).
Re: Worst Phobos documentation evar!
On Thu, Jan 01, 2015 at 12:26:04AM +0200, ketmar via Digitalmars-d wrote: > On Wed, 31 Dec 2014 14:19:00 -0800 > Walter Bright via Digitalmars-d wrote: > > > On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote: > > > Yeah no kidding. How do I hate make? Let me count the ways: > > > > Ironically, none of your points mention the macro system. > > that's 'cause 'make' doesn't need any. it's either enough to have > envvars for simple tool, or you need a scripting language for complex > extensible tool. The macro system in make is so bad, it shouldn't need an explicit mention to be obvious that it's bad. Besides, macros are where the various flavors of make differ the most anyway, so anyone who wants anything resembling a cross-platform makefile should only use the most basic of macro functions and forego the actually-useful stuff. T -- Written on the window of a clothing store: No shirt, no shoes, no service.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig wrote: You are right. I browsed some phobo's code and saw the documentation, it looks clean and nice. The only exception is std.algorithm which is full of macros and barely readable. So where is that other macro code? The one that has $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed? IMHO biggest issue is not inline documentation for functions but more higher level stuff like http://dlang.org/arrays.html - it was all in DDOC too last time I checked and changing anything about it is hardly a pleasure. Inline documentations only suffers when more pretty stuff like tables gets added. One more fundamental issue with inline docs is not markup language but lack of any simple way to inherit / refer existing documentation entries. There is "ditto" but no "same as in base method" or "same as for symbol X".
Re: Worst Phobos documentation evar!
On 12/31/14 6:46 PM, Walter Bright wrote: On 12/31/2014 12:55 PM, Ary Borenszweig wrote: Definitely, because Markdown is not a macro system, it's a documentation tool. I write a lot of documentation. A macro system has saved enormous amounts of effort. Night and day, really. Not having a macro system is like using a programming language that does not have functions. Ketmar, for example, complained mightily about Ddoc markup. I suggested he simply email me the Phobos documentation he wants to write, and I'd mark it up for him and submit the PRs. He admitted he is not interested in actually writing any documentation. Ddoc is not the real issue, at least for him. I'll extend the same offer to you. Email me the fixed Phobos docs. I'll mark them up and submit PRs. The thing is, with Ddoc you don't actually have to write any markup. You can write: / This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***/ You are right. I browsed some phobo's code and saw the documentation, it looks clean and nice. The only exception is std.algorithm which is full of macros and barely readable. So where is that other macro code? The one that has $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed?
Re: Worst Phobos documentation evar!
On 12/31/14 7:14 PM, Walter Bright wrote: On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it. Oh, it's for Nimrod (Now Nim)
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 22:37:08 + Jacob Carlborg via Digitalmars-d wrote: > On Wednesday, 31 December 2014 at 21:23:58 UTC, Andrei > Alexandrescu wrote: > > Ary Borenszweig wrote: > > >> And it's no wonder why there are so many alternatives (rake, > >> nake, etc.) > > > > ... Neither of which successful :o) > > What!! Rake is used by every Rails project out there. Thousands > of more projects than D projects. and not only rails. mkvtools_nix using rake too, but it's pure C++ project. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 21:23:58 UTC, Andrei Alexandrescu wrote: Ary Borenszweig wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) What!! Rake is used by every Rails project out there. Thousands of more projects than D projects. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 14:10:06 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 12:44 PM, ketmar via Digitalmars-d wrote: > > that still will be MUCH better than Ddoc. > > After you refused my offer to add in the Ddoc for you, saying you weren't > going > to write documentation regardless, it's hard to put much weight on your > opinion > about it. what use for me in such documentation? i can do Ddoc myself, i just can't read the result. what i want is readable documentation in .d files, without any preprocessing. Ddoc can't do that. so i can't see any sense in investing time to write documentation which then will be uglified by Ddoc. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 14:19:00 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote: > > Yeah no kidding. How do I hate make? Let me count the ways: > > Ironically, none of your points mention the macro system. that's 'cause 'make' doesn't need any. it's either enough to have envvars for simple tool, or you need a scripting language for complex extensible tool. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 14:14:46 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: > >> And it's no wonder why there are so many alternatives (rake, nake, etc.) > > ... Neither of which successful :o) > > I googled nake and couldn't find any references to it. "nake build system", first link from google: "Nake is a magic task runner tool for .NET. It's a hybrid of Shovel and Rake. The DSL for defining tasks is uniquely minimal and it's just plain C# code!" signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote: Yeah no kidding. How do I hate make? Let me count the ways: Ironically, none of your points mention the macro system.
Re: Worst Phobos documentation evar!
On 12/31/2014 12:49 PM, Ary Borenszweig wrote: Compare \* to $(STAR) I found two instances of $(COMMA) across the Phobos sources, and neither were necessary.
Re: Worst Phobos documentation evar!
On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it.
Re: Worst Phobos documentation evar!
On 12/31/2014 12:44 PM, ketmar via Digitalmars-d wrote: that still will be MUCH better than Ddoc. After you refused my offer to add in the Ddoc for you, saying you weren't going to write documentation regardless, it's hard to put much weight on your opinion about it.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 01:51:25PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote: > >And what if you need commas in the list items? Oh right, $(COMMA). > >Very readable. > > And Markdown never needs escapes. Right. :-) It needs escapes in far less places than ddoc does. When escapes are inescapable(!), you want the solution with less occurrences, not the solution with more. T -- In theory, software is implemented according to the design that has been carefully worked out beforehand. In practice, design documents are written after the fact to describe the sorry mess that has gone on before.
Re: Worst Phobos documentation evar!
On 12/31/2014 12:54 PM, Ary Borenszweig wrote: Which still look readable (and the backslash is just one character of noise so it's also not that bad). (Then you've never tried to use regex string literals in C code.) C++ would not have added raw string literal syntax if this was not an issue. It was a welcome improvement from anyone I've heard comment on it.
Re: Worst Phobos documentation evar!
On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. And Markdown never needs escapes. Right. :-)
Re: Worst Phobos documentation evar!
On 12/31/2014 12:55 PM, Ary Borenszweig wrote: Definitely, because Markdown is not a macro system, it's a documentation tool. I write a lot of documentation. A macro system has saved enormous amounts of effort. Night and day, really. Not having a macro system is like using a programming language that does not have functions. Ketmar, for example, complained mightily about Ddoc markup. I suggested he simply email me the Phobos documentation he wants to write, and I'd mark it up for him and submit the PRs. He admitted he is not interested in actually writing any documentation. Ddoc is not the real issue, at least for him. I'll extend the same offer to you. Email me the fixed Phobos docs. I'll mark them up and submit PRs. The thing is, with Ddoc you don't actually have to write any markup. You can write: / This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***/
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 01:26:50PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 1:19 PM, H. S. Teoh via Digitalmars-d wrote: > >On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d > >wrote: > >>On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: > >>>On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: > This is a known issue: > > https://issues.dlang.org/show_bug.cgi?id=13270 > >>> > >>>Good to know. Any preferences for proceeding with this? Put in > >>>place the params even allowing for the bug, or just avoid the > >>>problem params for now? > >>> > >> > >>Just ignore the warning. > > > >Which causes non-existent parameters to slip through (e.g., if you > >mistyped a parameter name). > > You can, of course, occasionally look at the warnings :-) Of course. But it would be nice if this wasn't necessary in the first place. :-) Yes, yes, I know, where's the PR... I'll get to it! This week just isn't a good time for that, too many things going on IRL. I'm planning to submit some ddoc-related PRs in the near future; it would be a good time to fold this one in too. T -- Famous last words: I *think* this will work...
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 09:23:58PM +, Andrei Alexandrescu via Digitalmars-d wrote: > Ary Borenszweig wrote: > > On 12/31/14 9:17 AM, Jacob Carlborg wrote: > >> On 2014-12-30 02:51, Walter Bright wrote: > >> > >>> (And actually, the Ddoc macro system very closely resembles the > >>> one used by make, as that is a simple and effective one, well > >>> known by programmers.) > >> > >> "make" has to be the worst tool ever created. I not just me that > >> has that opinion [1]. That you even consider this as a positive > >> argument is baffling me. Or rather not, if you like "make" I can > >> see why you like Ddoc. > >> > >> [1] http://www.conifersystems.com/whitepapers/gnu-make/ > >> > > > > Agreed. I try to avoid makefiles as much as I can. > > > > And it's no wonder why there are so many alternatives (rake, nake, > > etc.) > > ... Neither of which successful :o) Yeah, just like D is still floundering in obscurity while inferior languages like C/C++ continue to flourish. *shrug* T -- There are four kinds of lies: lies, damn lies, and statistics.
Re: Worst Phobos documentation evar!
On 12/31/2014 1:19 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now? Just ignore the warning. Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name). You can, of course, occasionally look at the warnings :-)
Re: Worst Phobos documentation evar!
Ary Borenszweig wrote: > On 12/31/14 9:17 AM, Jacob Carlborg wrote: >> On 2014-12-30 02:51, Walter Bright wrote: >> >>> (And actually, the Ddoc macro system very closely resembles the one used >>> by make, as that is a simple and effective one, well known by >>> programmers.) >> >> "make" has to be the worst tool ever created. I not just me that has >> that opinion [1]. That you even consider this as a positive argument is >> baffling me. Or rather not, if you like "make" I can see why you like Ddoc. >> >> [1] http://www.conifersystems.com/whitepapers/gnu-make/ >> > > Agreed. I try to avoid makefiles as much as I can. > > And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o)
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 12:40:20 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 7:13 AM, Jacob Carlborg wrote: > > I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing > > documentation for code. Not web sites, not books, but documentation for > > code. > > Documentation for code winds up on a web site. finally, i got your point. D is *your* *personal* *project*. not more, not less. it something is handy for you, it will be in D, and it doesn't matter how much other people arguing about changing it. if something is of no use for you, it would be a miracle to see it in D, even when the code is ready and almost anyone who cares about the thing anough wrote "yes, do it!" and i'm not talking about Ddoc here. and about Ddoc/markdown issue: the quoted sentense says it all. you want Ddoc to be able to produce websites. and you don't care if some other people think that Ddoc was invented for documenting the source code. you know, documenting sources implies easy reading by human without preprocesing. and easy human-readable format is easy to write. but yes, it can't create a cool website for you. nor it is good for DTP. you keep inventing artificial samples to show that one still has to use escaping in markdown. you know, looking at Ddoc, which consists mostly of visual noise, i can tell you that markdown is god-given immortal purity. yet i got the idea: Ddoc is for websites, not for API documentation. it happens to understand some D, but the primary goal is to create website. ok. we just misunderstood why Ddoc is here. i appreciate all your hard work on D (and on C/C++ compilers too, which i was used from time to time). but do you really want D to be a widely used language? seems that you are thinking about some "future users", who will surely need to write a complex documents right in the D source code, so Ddoc must resemble DTP languages. that they ("future users") will write alot of code and so we can't break that unwritten code by changing the language now. and so on. what you seem to miss here is that it's the current D users who spreading a word. make D better for current passionate users, and you may get those "future users" in the future. make D great, but frustrating for current passionate users, and you will get no "future users" at all, 'cause there will be nobody to spread a word about D. i, for myself, can't see why i have to endure annoyance in the name of "future users". those "future users" did nothing for me, except making D frustrating. the thing is that "future users" will have to take what we giving 'em, not we have to take something that *might* please those "future users". do you think that vibe.d is a valuable project? Sönke wants property enforcement syntax, for example. just ask him! and patch for that syntax is already here. that patch works, my DMD build using it. yet Sönke will not come here to argue for this feature for month (or years?), he is busy developing vibe.d (and other things). Sönke is a real user with a real project. he can live without property enforcement, but... besides, enforcing property syntax will solve the bug with delegate properties, where they need `()()` to really call the delegate. and we have dfix which can be extended to automatically fix user code. and what about tuple syntax? two years passed since PR was submitted. isn't it enough to stop thinking about how accepting that PR will close the opportunity to invent better syntax in the future and just accept it? two years of stagnation is enough to see that this feature is not at the top of priority list and you and Andrei will *always* have more important tasks to do. so just merge it and forget! (yes, i know that it can't be merged right now without rebasing; seems that we simply lost it) sorry. i hate new years. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: > >On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: > >>This is a known issue: > >> > >>https://issues.dlang.org/show_bug.cgi?id=13270 > > > >Good to know. Any preferences for proceeding with this? Put in place the > >params even allowing for the bug, or just avoid the problem params for now? > > > > Just ignore the warning. Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name). T -- If it breaks, you get to keep both pieces. -- Software disclaimer notice
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 12:54:14PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 11:59 AM, Anon wrote: > >Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) > >to get a list. > > You don't have to. You can write it as: > > $(LIST A, B, C) > > or: > > $(LIST >A, >B, >C > ) [...] And what if you need commas in the list items? Oh right, $(COMMA). Very readable. T -- Be in denial for long enough, and one day you'll deny yourself of things you wish you hadn't.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 10:17:26PM +0200, ketmar via Digitalmars-d wrote: > On Wed, 31 Dec 2014 10:59:32 -0800 > Walter Bright via Digitalmars-d wrote: > > > On 12/31/2014 4:17 AM, Jacob Carlborg wrote: > > > On 2014-12-30 02:51, Walter Bright wrote: > > > > > >> (And actually, the Ddoc macro system very closely resembles the > > >> one used by make, as that is a simple and effective one, well > > >> known by programmers.) > > > > > > "make" has to be the worst tool ever created. I not just me that > > > has that opinion [1]. That you even consider this as a positive > > > argument is baffling me. Or rather not, if you like "make" I can > > > see why you like Ddoc. > > > > You can not like a car's suspension but still like its engine. > > but 'make' is a failure in every aspect, especially GNU make. bwah, > build tool that can't do autoimatic dependency tracking? you must be > joking. Yeah no kidding. How do I hate make? Let me count the ways: 1) Recursive make considered harmful. (Google it.) 2) Non-reproducible builds -- you have to make clean; make, just to be absolutely sure your build is correct (defeats the purpose of a build tool, really -- might as well use a shell script of compiler commands). 3) Changing compile flags in a makefile does not trigger rebuilding of all affected targets. You're on your own to kick make into rebuilding what's needed. Usually, this means yet another `make clean; make`. Which doesn't always work -- see (6). A great source of heisenbugs. 4) Unnecessary rebuilds -- if you edit a comment in a header file, it causes a waterfall effect in rebuilding everything that #include's it, and even though all of the .o files produced are identical to those from the previous run, make is oblivious to this fact, and wastes time linking them all and cascading even more rebuilds that depend on the link products, etc., etc.. 5) Timestamps are unreliable -- accidentally touching the timestamp of a header file included by everything (without changing its contents) will cause the entire tree to be rebuilt. Timestamps over NFS may be inconsistent, causing make to randomly rebuild files that don't need to be rebuilt and skip files that do. 6) Dependency scanning is O(n). Not scalable. 7) No built-in cleanup function -- everybody writes their own `make clean` rules, which are inevitably wrong (`rm -rf *.o *.so`, but what if you have an .so that isn't generated by the build?) or incomplete (oops, forgot to delete the .c file generated by bison). This, coupled with (2) and (3), leads to heisenbugs where stale libraries from previous builds get linked into the executable, causing runtime bugs that don't exist in the source code. The solution? `make clean; make` and have another coffee break. Very productive. (Except when your make clean rules failed to delete said stale library, then it's time to \rm -rf and git clone a new repo.) 8) Implicit dependencies between source files require external tooling support (gcc -MF, which leaves stray .dep files all over the place, which `make clean` inevitably forgets to clean up, and which cause mistakes in the dependency tree when dependencies change and the .dep files aren't updated before make reads them). 9) Build parameters (e.g. compiler flags) are not well-encapsulated -- the global CFLAGS has to be tweaked, or you have to invent your own convoluted set of macros that are combined into the final compiler flags, which leads to a maintenance nightmare. 10) No support for out-of-tree builds (which are increasingly becoming clear that it's the superior way to go -- littering generated files in the same directories as source files inevitably leads to a gigantic mess). 11) No support for simultaneous variant builds such as cross-compiling for multiple architectures in the same run (unless you manually write this, which is a royal pain and extremely error-prone for something the build system *should* have taken care of for you) -- because of (7): all build variables are global and there's no way to reuse the same build rules with different target parameters. 12) Many common build tasks are not supported by the core make system, and require the user to reinvent the wheel, which results in large, convoluted, and fragile makefiles that stop working as soon as you try to do something that wasn't anticipated by the makefile authors. 13) Anachronistic syntax requirements, like distinguishing between spaces and tabs. Make is like C... it offers you raw functionality to shoot yourself in the foot and drown in dependency bugs, just like C offers you countless ways to have buffer overruns and dangling pointers. Yet people glory in their scars acquired over decades of pain, and build entire ecosystems around it, such that mention of any alternatives is resisted at best, and ridiculed and summarily dismissed at worst. What's baffling is that such a reaction is observed even in the D community, which, ostensibly, exists exactly because people are finall
Re: Worst Phobos documentation evar!
On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now? Just ignore the warning.
Re: Worst Phobos documentation evar!
On 12/31/2014 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: The above will generate a warning because, of course, the first function signature doesn't have a parameter 'rng'. Since docs are compiled with -w, I believe this will result in an error ... ? I know, I don't care for that warning, which was added fairly recently.
Re: Worst Phobos documentation evar!
On 12/27/14 10:00 PM, Walter Bright wrote: This is so bad there isn't even a direct link to it, it hides in shame. Just go here: http://dlang.org/phobos/std_encoding.html#.transcode and scroll up one entry. Here it is: size_t encode(Tgt, Src, R)(in Src[] s, R range); Encodes c in units of type E and writes the result to the output range R. Returns the number of Es written. Let me enumerate the awesomeness of its awfulness: 1. No 'Return:' block, though it obviously returns a value. 2. No 'Params:' block, though it obviously has parameters. 3. No 'Example:' block 4. No comparison with other 'encode' functions in the same module. 5. No description of what 'Tgt' is. 6. No description of what 'Src' is. 7. No clue where the variable 'c' comes from. 8. No clue where the type 'E' comes from. 9. 'R' is a type, not an instance. 10. I suspect it has something to do with UTF encodings, but there is no clue. This one is missing some docs too: http://dlang.org/phobos/std_math.html#abs
Re: Worst Phobos documentation evar!
On 12/29/14 10:38 PM, Andrei Alexandrescu wrote: On 12/29/14 2:30 PM, Dicebot wrote: DDOC is probably one of D features with pretty idea and hardly usable design. I wish we had something like Markdown instead - can never remember Phobos macros to use and usually just resort to using plain text instead. I'm with Walter here - I find Markdown and its ilk inferior to macro systems. -- Andrei Definitely, because Markdown is not a macro system, it's a documentation tool.
Re: Worst Phobos documentation evar!
On 12/31/14 4:09 PM, Walter Bright wrote: On 12/31/2014 7:03 AM, Jacob Carlborg wrote: On 2014-12-30 00:52, Walter Bright wrote: (And I should ask, what if you wanted a | in the Markdown?) Just type a |. You don't need to escape most Markdown symbols in the middle of text. And when you want a | in a table entry? Most of the time it's not a problem, see above. And when it is, how do you escape them? Backslash character.
Re: Worst Phobos documentation evar!
On 12/31/2014 11:59 AM, Anon wrote: Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a list. You don't have to. You can write it as: $(LIST A, B, C) or: $(LIST A, B, C ) Yes, there currently isn't a LIST macro by default, but you can write one: LISTX=$(LI $1) $(LISTX $+) LIST=$(UL $(LISTX $1, $+)) I very often write custom macros for a particular job at hand. It's very, very handy. For example, suppose I want to switch between a definition list and a table? I write a higher level macro, then switch its definition. I can use the "X Macro" technique. I can "comment out" a block. I can create "variables". For example, when the D source moved from svn to github, the macro in each source code file that linked to the repository just needed its definition changed. With markdown, I'd have had to have edited every file (what, are there a thousand files?). And so on. http://en.wikipedia.org/wiki/X_Macro
Re: Worst Phobos documentation evar!
On 12/31/14 5:33 PM, Walter Bright wrote: On 12/31/2014 11:59 AM, Anon wrote: A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping? Yeah, the reason that people have added WYSIWYG string literals to languages :-) Which still look readable (and the backslash is just one character of noise so it's also not that bad).
Re: Worst Phobos documentation evar!
On 12/31/14 4:07 PM, Walter Bright wrote: On 12/31/2014 5:03 AM, Ary Borenszweig wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) Which one has a better text macro system? A real programming language without text macro systems.
Re: Worst Phobos documentation evar!
On 12/31/14 4:14 PM, Walter Bright wrote: On 12/31/2014 6:29 AM, Jacob Carlborg wrote: On 2014-12-30 01:10, Walter Bright wrote: It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup. You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things? You use a backslash character, like in almost every programming language, json, etc. http://daringfireball.net/projects/markdown/syntax#backslash Compare \* to $(STAR)
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 12:05:30 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 11:45 AM, Kiith-Sa wrote: > > It's NOT a different variant. It's a different LANGUAGE. > > That's like saying D is a variant of Pascal. > > It's not illegitimate to consider all { } languages as variants of each other. then D is doomed to vanish. nobody needs another C++, but with broken syntax and without libraries. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 7:13 AM, Jacob Carlborg wrote: I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing documentation for code. Not web sites, not books, but documentation for code. Documentation for code winds up on a web site. I find it very handy that the Ddoc embedded in D code, and the Ddoc used for the rest of the web site, all use the same style sheets, the same macro files, etc. And an ebook and pdf can all be generated from the same.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 11:14:50 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 6:29 AM, Jacob Carlborg wrote: > > On 2014-12-30 01:10, Walter Bright wrote: > > > >> It's not a hack. The macro system is designed to work that way. All > >> markup systems require some sort of escape mechanism. Including Markup. > > > > You don't need to escape all the special symbols used in Markdown, only in > > certain place. In Markdown, if you start a line with a star, '*', it will be > > interpreted as the beginning of an unordered list. But if you write a star > > in > > the middle of text it will just output a star, as expected. > > I know that Markdown formatting is context sensitive. > > And what happens if you want to have a * at the beginning of the line of > output? > And a | in a table entry? And so on for each of the context sensitive things? that still will be MUCH better than Ddoc. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 11:59 AM, Anon wrote: A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping? Yeah, the reason that people have added WYSIWYG string literals to languages :-)
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 10:59:32 -0800 Walter Bright via Digitalmars-d wrote: > On 12/31/2014 4:17 AM, Jacob Carlborg wrote: > > On 2014-12-30 02:51, Walter Bright wrote: > > > >> (And actually, the Ddoc macro system very closely resembles the one used > >> by make, as that is a simple and effective one, well known by programmers.) > > > > "make" has to be the worst tool ever created. I not just me that has that > > opinion [1]. That you even consider this as a positive argument is baffling > > me. > > Or rather not, if you like "make" I can see why you like Ddoc. > > You can not like a car's suspension but still like its engine. but 'make' is a failure in every aspect, especially GNU make. bwah, build tool that can't do autoimatic dependency tracking? you must be joking. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 20:05:43 UTC, Walter Bright wrote: On 12/31/2014 11:45 AM, Kiith-Sa wrote: It's NOT a different variant. It's a different LANGUAGE. That's like saying D is a variant of Pascal. It's not illegitimate to consider all { } languages as variants of each other. With that kind of thinking everyone would still be using COBOL and FORTRAN.
Re: Worst Phobos documentation evar!
On 12/31/2014 11:45 AM, Kiith-Sa wrote: It's NOT a different variant. It's a different LANGUAGE. That's like saying D is a variant of Pascal. It's not illegitimate to consider all { } languages as variants of each other.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright wrote: On 12/31/2014 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. Yes, the same only different. Just like DDoc macros and Makefile macros. They're the same, but different. Also, the differences between Markdown implementations are trivial, and do not effect the readability of the source, which is the entire point of Markdown - making the "plain-text" readable, rather than polluting it with HTML (or DDoc) tag noise. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. It's just another variation of it - which is my point. And your point is completely wrong. DDoc and Makefiles both use $(MACROS), does that mean that DDoc is a variation of Make? Yes, *lots* of things use common elements. Because that makes things more easily understood when *reading*, which is the single most important thing for documentation. The macros are fine for when they are needed, but you shouldn't have to use gotos and jumps when all you want is a gorram foreach loop. Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a list. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things? A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping?
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright wrote: On 12/31/2014 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. Yes, the same only different. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. It's just another variation of it - which is my point. It's NOT a different variant. It's a different LANGUAGE. That's like saying D is a variant of Pascal.
Re: Worst Phobos documentation evar!
On 12/31/2014 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. Yes, the same only different. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. It's just another variation of it - which is my point.
Re: Worst Phobos documentation evar!
On 12/31/2014 6:29 AM, Jacob Carlborg wrote: On 2014-12-30 01:10, Walter Bright wrote: It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup. You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things?