www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Better docs for D (WIP)

reply Adam D. Ruppe <destructionator gmail.com> writes:
Last week, I posted in the general forum my dream for better D 
docs. Today, about 4 days of work later, I'm about 1/4 of the way 
there.

Still a long way to go, but I've already come so far.

First, behold my old dpldocs.info site. Yes, it is still up and 
now it ties into my new docs! You can use it to quickly jump to a 
doc given its name:

http://dpldocs.info/

Inspired by the php docs, I also have it able to search direct 
from a URL. Click this:

http://dpldocs.info/findSkip

and it automatically sends you here:

http://dpldocs.info/experimental-docs/std.algorithm.searching.findSkip.html


I haven't run all of Phobos through my generator yet (it still 
crashes on some of it) but I have run a lot of it through so you 
can browse around and get a feel.


I also described why in This Week in D last night: 
http://arsdnet.net/this-week-in-d/dec-27.html



While I'm still probably at least a month away from having this 
really finished, I feel it is already a massive improvement on 
the main docs and wanted to announce it so other people can give 
it a try too.



Once I finish the generator, I'll start writing new articles to 
fill in some of the dummy links there, and perhaps make minor 
changes to Phobos itself (if I can make changes that help me 
without hurting the existing ddoc based site or source 
legibility). The new articles are a big part of the work too!

Finally, when I am happy with this program, I will document the 
doc generator and release it for other people to use too.

But until then, have fun playing with dpldocs.info!
Dec 28 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/28/15 3:15 PM, Adam D. Ruppe wrote:
 http://dpldocs.info/

 Inspired by the php docs, I also have it able to search direct from a
 URL. Click this:

 http://dpldocs.info/findSkip
The signature proper is nice. The formatting of "&&" in the constraint is inconsistent, but I guess that's a matter with the formatting of the code. The vertical spacing post "Parameters" of http://dpldocs.info/findSkip is annoying. So we have a healthy vertical space between the "Parameters" and "haystack" headings - fine - then a dinghy space between "haystack" and the type, then again a large space between the "Type:" and the description. I think types should be massaged with the parameter names. Also the type of the return value should be massaged with the heading "Return Value" and the valign of the return value's description should be the same as for the parameters, so we have: ======== Parameters ((vspace 1)) R1 haystack ((hspace 1))The forward range to search in. ((vspace 2)) R2 needle ((hspace 1))The forward range to search for. ((vspace 2)) Return Value (bool) ((vspace 1)) ((hspace 1))true if the needle was found, in which case haystack is positioned after the end of the first occurrence of needle; otherwise false, leaving haystack untouched. ======== etc. Ideally most of these things would be adjustable via css. Even some of the text (e.g. "Return Value" etc.) would be in a perfect world part of the css (there's that property "before" or something). Essentially it would be fantastic if the docs contained the semantic info and the formatting would be entirely shipped to css. Andrei
Dec 28 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 28 December 2015 at 23:01:05 UTC, Andrei Alexandrescu 
wrote:
 The signature proper is nice. The formatting of "&&" in the 
 constraint is inconsistent, but I guess that's a matter with 
 the formatting of the code.
Yeah, that is a css bug I just forgot about getting in to everything else, fixed now.
 The vertical spacing post "Parameters" of 
 http://dpldocs.info/findSkip is annoying.
In a simple function it may be unnecessary but doesn't really hurt, while in a complex type or a function with a lot of parameters, it improves legibility. A type alone can be a pretty complex beast and can warrant the use of multiple lines. I *might* change my mind on this, Qt puts the types on one line, but the real question is what they look like when I finish the constraint analyzer. I haven't even started implementing it yet, but the type of haystack is not really R1. It is actually "duck-typed forward range", which is gleamed from the constraint. Qt's types are rarely more complex than a class pointer. Sometimes, you might see a QList<QSomething*> or a QMap<QKey, QValue>, but never anything like what Phobos deals in. C++ doesn't have D's const and immutable, it doesn't have the dip 25 ref checker, it doesn't use much design by introspection. Voldemort types both simplify the signature and make the explanation more complex at the same time. So what works for us may be quite different than what works for them. But once I get the constraint analyzer set up and try it on more real world code, if it remains legible in complex cases on one line (which it might, I should be able to simplify stuff like `!isInfinite!Range && isForwardRange!Range` into something like "finite forward range"), I'll revisit this.
 Ideally most of these things would be adjustable via css.
Of course, it is primarily an issue of margins, and I'm mostly using the browser defaults for the semantic tags at this point. But I do want it to be good out of the box and find too much space to be better than too little.
 Essentially it would be fantastic if the docs contained the 
 semantic info and the formatting would be entirely shipped to 
 css.
Yes, I agree, that is one of my goals too.
Dec 28 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
One more note: I salute the initiative of another doc generator and read 
the motivation behind it. Yet I do think it's worth asking ourselves two 
questions:

(a) is the new proposed system differentiated enough to justify its 
existence and motivate others to join in?

(b) are the existent systems reaching hard limits that the proposed 
system overcomes by design?

Last thing we want is the idyllic Balkanic landscape of several "me too" 
documentation systems, neither of which is better and has more of a 
following than others.

This is just musing. Please don't make it into Archduke Ferdinand's 
assassination :o).


Andrei
Dec 28 2015
next sibling parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 29/12/15 12:05 PM, Andrei Alexandrescu wrote:
 One more note: I salute the initiative of another doc generator and read
 the motivation behind it. Yet I do think it's worth asking ourselves two
 questions:

 (a) is the new proposed system differentiated enough to justify its
 existence and motivate others to join in?
It supports comments on manifest enums sorta like as if it was named. The others do not ;) So I'm already very wanting of this solution to say the least.
Dec 28 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Rikki Cattermole <alphaglosined gmail.com> wrote:
 On 29/12/15 12:05 PM, Andrei Alexandrescu wrote:
 One more note: I salute the initiative of another doc generator and read
 the motivation behind it. Yet I do think it's worth asking ourselves two
 questions:
 
 (a) is the new proposed system differentiated enough to justify its
 existence and motivate others to join in?
It supports comments on manifest enums sorta like as if it was named. The others do not ;) So I'm already very wanting of this solution to say the least.
Is this feature unreasonably difficult to integrate within the existing products?
Dec 28 2015
parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 29/12/15 4:08 PM, Andrei Alexandrescu wrote:
 Rikki Cattermole <alphaglosined gmail.com> wrote:
 On 29/12/15 12:05 PM, Andrei Alexandrescu wrote:
 One more note: I salute the initiative of another doc generator and read
 the motivation behind it. Yet I do think it's worth asking ourselves two
 questions:

 (a) is the new proposed system differentiated enough to justify its
 existence and motivate others to join in?
It supports comments on manifest enums sorta like as if it was named. The others do not ;) So I'm already very wanting of this solution to say the least.
Is this feature unreasonably difficult to integrate within the existing products?
From what Adam has said, definitely won't be happening with DDOC. There is simply no symbol to attach the comment to.
Dec 28 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 29 December 2015 at 05:00:48 UTC, Rikki Cattermole 
wrote:
 From what Adam has said, definitely won't be happening with 
 DDOC.
 There is simply no symbol to attach the comment to.
Well, not definitely, it was really easy to do in libdparse (a two line diff) and probably similarly easy in dmd. There is no user-facing name for an anonymous enum, but there is a compiler data structure for it.
Dec 29 2015
parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 30/12/15 3:24 AM, Adam D. Ruppe wrote:
 On Tuesday, 29 December 2015 at 05:00:48 UTC, Rikki Cattermole wrote:
 From what Adam has said, definitely won't be happening with DDOC.
 There is simply no symbol to attach the comment to.
Well, not definitely, it was really easy to do in libdparse (a two line diff) and probably similarly easy in dmd. There is no user-facing name for an anonymous enum, but there is a compiler data structure for it.
Okay, I remember you saying something a bit different on IRC (at least to my understanding).
Dec 29 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 29 December 2015 at 14:26:48 UTC, Rikki Cattermole 
wrote:
 Okay, I remember you saying something a bit different on IRC 
 (at least to my understanding).
Well, I'm still a bit iffy on it, to attach a name I used the first member of the enum which might not pass review muster in dmd itself, but you could also probably just generate a random name for it. Actually, I think dmd *does* generate random names for anonymous enums internally anyway. I know it does for structs and functions etc. dmd could probably get away without a name too, since it doesn't care about SEO and linking, whereas I do. But regardless, I'm sure it is technically possible, I'm just not sure the dmd maintainers wouldn't reject it as a pointless hack in their eyes.
Dec 29 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/2015 10:20 AM, Adam D. Ruppe wrote:
 On Tuesday, 29 December 2015 at 14:26:48 UTC, Rikki Cattermole wrote:
 Okay, I remember you saying something a bit different on IRC (at least
 to my understanding).
Well, I'm still a bit iffy on it, to attach a name I used the first member of the enum which might not pass review muster in dmd itself, but you could also probably just generate a random name for it. Actually, I think dmd *does* generate random names for anonymous enums internally anyway. I know it does for structs and functions etc. dmd could probably get away without a name too, since it doesn't care about SEO and linking, whereas I do.
Then why document it? If it's for SEO, what SEO scenarios woukd be covered by this feature that can't be done with simple workarounds? -- Andrei
Dec 29 2015
next sibling parent Rikki Cattermole <alphaglosined gmail.com> writes:
On 30/12/15 1:32 PM, Andrei Alexandrescu wrote:
 On 12/29/2015 10:20 AM, Adam D. Ruppe wrote:
 On Tuesday, 29 December 2015 at 14:26:48 UTC, Rikki Cattermole wrote:
 Okay, I remember you saying something a bit different on IRC (at least
 to my understanding).
Well, I'm still a bit iffy on it, to attach a name I used the first member of the enum which might not pass review muster in dmd itself, but you could also probably just generate a random name for it. Actually, I think dmd *does* generate random names for anonymous enums internally anyway. I know it does for structs and functions etc. dmd could probably get away without a name too, since it doesn't care about SEO and linking, whereas I do.
Then why document it? If it's for SEO, what SEO scenarios woukd be covered by this feature that can't be done with simple workarounds? -- Andrei
The names are for anchors. E.g. go jump to the comment / enum members.
Dec 29 2015
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 30 December 2015 at 00:32:31 UTC, Andrei 
Alexandrescu wrote:
 Then why document it?
Just on principle, a documentation tool probably shouldn't be limiting the author's ability to document... This might just be a bug in dmd btw. Looking at the ddoc spec page, it says "documentation comments not associated with a declaration are ignored", but it doesn't say the declaration must be named. Perhaps dmd ought to be keeping it but isn't.
 If it's for SEO, what SEO scenarios woukd be covered by this 
 feature that can't be done with simple workarounds? -- Andrei
Putting one item per page is far more important than I even realized before getting into this. I was talking to a friend on Sunday night about his early adventures into D. He's managed to convert one of his work scripts that works with Google Docs to D and is working on transitioning a little web form program too. He consistently found the dlang.org documentation to be undiscoverable and nearly unusable once he did find it. One example he gave as wondering if D had an Array.join function like Javascript. He searched for "dlang array join" and first, of course, got "did you mean golang?". I like to joke about that being Google's bias, but I betcha it is actually more to do with our poor SEO than any nefarious code on their end. The top two results he got were: http://dlang.org/spec/arrays.html which is no help, it talks about arrays but not the join function and http://dlang.org/phobos/std_array.html which he thought was another false positive because it looked generic again. I told him it *is* the right page... but the wrong section. To actually get to the join function, you need to find it again in the table and hit that second link. He spent more time than he should have and thought D didn't have an array.join function because the search engine didn't actually return it. It returned two pages that are vaguely related but not specifically what he wanted, and being used to more relevant search requests, wrote off the ddoc as a false positive despite it being the right page! I asked people in the #d chatroom to repeat this experiment. Nobody even got http://dlang.org/phobos/std_array.html as the top result! Longer time D users did get http://dlang.org/library/std/array/join.html as a top result - good - but nobody actually got the official doc and the ddox only came to those with personalized search that ups the rank score of D related pages. Contrast that to even the primitive results from my dpldocs.info D-specific search. Look for "array join" and get: http://dpldocs.info/search/search2?searchTerm=array+join Whoa, std.array.join is right at the top! And if you click it, you go directly to the relevant function doc. That's huge.
Dec 29 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/2015 09:09 PM, Adam D. Ruppe wrote:
 Putting one item per page is far more important than I even realized
 before getting into this.
We already have that: https://dlang.org/library/std/array/join.html If I search for dlang array join that the third hit on google if I'm logged in, and the SECOND hit if I use an anonymous session that gives google no information about my searching habits. I hope you'll agree that renders the rest of your post moot, for which reason I afforded to snip it. Adam, there's no nice way to put what follows. You can code a great deal, and I think the world of your engineering skills. But there is something to be said about a bias for action at the expense of strategy. I completely understand it's a lot more fun to start a project than to bring it to completion, but as they say in hardware, it's retired instructions that count. I wish you'd consider converting some of your myriad brilliant snippets into completed projects pushed into the standard distribution for prime time, and also (for this case) to consider strengthening the documentation tools we already have. Andrei
Dec 29 2015
next sibling parent reply default0 <Kevin.Labschek gmx.de> writes:
On Wednesday, 30 December 2015 at 04:03:42 UTC, Andrei 
Alexandrescu wrote:
 On 12/29/2015 09:09 PM, Adam D. Ruppe wrote:
 Putting one item per page is far more important than I even 
 realized
 before getting into this.
We already have that: https://dlang.org/library/std/array/join.html If I search for dlang array join that the third hit on google if I'm logged in, and the SECOND hit if I use an anonymous session that gives google no information about my searching habits.
Can confirm these search results. As an aside, the mere formatting of the list of template-constraints on the dlang page made me nope right out of even bothering to figure out how to read them or what the difference between the first and the second overload of join was. Checking dpldocs for proper formatting and spending half a minute making sense of it I figured that the one was for an exactly matched element type and the other one was to allow joining a baseClass[][] with a subClass[] or something along those lines. Plus, it's of course really nice that we have these single pages, but for most things you search in google you still get results that lead you to http://dlang.org/phobos/ with pages that usually make your scrollbar pretty tiny and forcing you to either Ctrl+F-guess your way through the page or figuring out what function out of a list of 10-30 functions might possibly suit your need only to scroll back up again and repeat (or look at another module altogether) if it doesn't. Cumbersome and annoying (ie: slow and unproductive). Also the information that /library even exists is new to me. I have only discovered it through reading this post. So that much for its discoverability (I am new to D, but I did spend probably something like 5-10 hours bugging around phobos documentation by this point and never really knew of /library). Example searches I did: http://puu.sh/mdGTt/e71cc7e459.png (only phobos) http://puu.sh/mdGX8/24250120b1.png (first two results /phobos, third /library) http://puu.sh/mdH5W/31d3a2432a.png (should be https://dlang.org/library/std/base64/base64_impl.decode.html ideally, but the module overview pages have examples, so this is kind of okay) http://puu.sh/mdH8g/42a82217e0.png (none of these results mention that you should simply cast(char[]) and then call validate on the casted array, from what I could tell skimming through them for 5 minutes, I might have missed a mention though, which would simply mean it is not obvious enough) So yeah, we have that, but it should be promoted more, and the documentation still needs lots of love (think the type of formatting and interlinking (even to concepts!) that adams documentation does, and of course the general deal with we need more examples and whatnot).
Dec 30 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 30 December 2015 at 14:25:24 UTC, default0 wrote:
 As an aside, the mere formatting of the list of 
 template-constraints on the dlang page made me nope right out 
 of even bothering to figure out how to read them or what the 
 difference between the first and the second overload of join 
 was.
Aye, it is a complete mess and virtually *nobody* bothers looking at them. (BTW, dmd has the same problem in error messages. I plan to format them eventually too, with some kind of highlighting of passed and failing clauses. I already did a proof of concept for ordinary overloading functions and it wasn't actually that hard. I just wish I didn't have other things to do!) New people are often outright scared away from everything and left with the impression that D is an experts-only language. The Phobos devs know this and have been trying to add more examples - a good, necessary step - but that isn't the whole problem. When users modify the examples and they fail to compile, they need to understand what's going on. The compiler will complain in terms of those ugly constraints, not in terms of fixed, working examples. They need some way of understanding what it is saying. Also: I plan to add a doc section called "diagnostics" with sample error messages and translations. I've actually considered doing this before but was stopped by concerns over vertical space. No kidding, when writing ddoc, I worry about it taking up too much space on the page and will cut content out as a result. If the prototype is compressed, it just leaves a mental bug that says space must matter, use it sparingly.
 Checking dpldocs for proper formatting and spending half a 
 minute making sense of it I figured that the one was for an 
 exactly matched element type and the other one was to allow 
 joining a baseClass[][] with a subClass[] or something along 
 those lines.
The join overloads are basically: #1: array of arrays joined by an array join(["a", "b", "c"], ", "); // the joiner is an array -> "a, b, c" #2: array of arrays joined by an element join(["a", "b", "c"], ' '); // the joiner is an element -> "a b c" There is no example for form #2 in the documentation. (BTW I think the examples should be commented too.) #3: array of arrays joined without anything join(["a", "b", "c"]) -> "abc" Nothing about inheritance in there, the constraints talk about ElementType!RoR which means (conceptually) it is stripping the "[]" off a type, so for "int[]", it returns "int". That should probably just be written in the text. (That's another thing people tell me, they come in with a question and I can give them a quick answer, then they ask "why didn't the docs just put it that simply?" And a few times, I go to open a PR but get stalled by the process somewhere....) But there's a LOT of functions in Phobos so I am trying to automate this because while I can write it for any individual function by hand, writing it for ALL the functions is going to take more time than I have.
 Cumbersome and annoying (ie: slow and unproductive).
absolutely.
 Also the information that /library even exists is new to me. I 
 have only discovered it through reading this post.
Right. New users either don't know about it because it doesn't get linked to much and thus has lower page rank (unless you have already trained Google through D searches to favor D results), or they do find it and are confused as to what version it refers to. There's been a few people who come to this newsgroup saying "these docs look old, what's up with it?" If they hit the disqus comment, it says "recent activity, 2 years ago" which furthers this impression.
 (none of these results mention that you should simply 
 cast(char[]) and then call validate on the casted array, from 
 what I could tell skimming through them for 5 minutes, I might 
 have missed a mention though, which would simply mean it is not 
 obvious enough)
When you mentioned this before, I went to add it to the docs but couldn't find a good place to put it. The vertical space brain bug hurt me on base64 itself, then the question of linking hurt me when thinking of putting it somewhere else like the wiki, then the question of process killed me when I went to add a new page! It was actually this experience that tipped me over the edge and I decided to start working on doc infrastructure myself. (I've spent a good amount of time this year trying to fix ddoc itself - starting with the `code` syntax in January - but ddoc itself is only part of the problem)
Dec 30 2015
parent reply default0 <Kevin.Labschek gmx.de> writes:
On Wednesday, 30 December 2015 at 15:30:05 UTC, Adam D. Ruppe 
wrote:
 On Wednesday, 30 December 2015 at 14:25:24 UTC, default0 wrote:
 Checking dpldocs for proper formatting and spending half a 
 minute making sense of it I figured that the one was for an 
 exactly matched element type and the other one was to allow 
 joining a baseClass[][] with a subClass[] or something along 
 those lines.
The join overloads are basically: #1: array of arrays joined by an array join(["a", "b", "c"], ", "); // the joiner is an array -> "a, b, c" #2: array of arrays joined by an element join(["a", "b", "c"], ' '); // the joiner is an element -> "a b c" There is no example for form #2 in the documentation. (BTW I think the examples should be commented too.) #3: array of arrays joined without anything join(["a", "b", "c"]) -> "abc"
Yeah, I misinterpreted the "E : <stuff>" to mean "E is or inherits from <stuff>", rechecking the argument deduction rules for templates I think this instead means "E should be deduced as <stuff>".
Dec 30 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 30 December 2015 at 15:51:23 UTC, default0 wrote:
 Yeah, I misinterpreted the "E : <stuff>" to mean "E is or 
 inherits from <stuff>", rechecking the argument deduction rules 
 for templates I think this instead means "E should be deduced 
 as <stuff>".
Sort of.. it means "if E can be implicitly converted to <stuff>". All of this stuff: RoR ror, E sep if ( isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && is(E : ElementType!(ElementType!RoR)) ) (doesn't copy paste well, I gotta fix my html a bit) Could be rewritten as "ror is an input ranges of input ranges and sep can be implicitly converted to the type of ror's inner range's elements." Or something like that. So given: join([[1L], [2L]], 1); Constraint clause 1: isInputRange!RoR passes because an array, this is long[][] is an input range. Constraint clause 2: ElementType!RoR is long[] because ElementType basically trips off the outer [] from RoR's type (basically), which is long[][]. Unqual!T trims off qualifiers like const, immutable, etc. Basically it takes the type out of parenthesis. There are none of that here, so long[] is still long[]. Finally, the clause passes because long[] is an input range. Constraint clause 3: asks if E, which in this example is typeof(1), which is `int`, is implicitly convertible to the type of RoR with *two* layers of [] trimmed off. RoR was long[][] so ElementType!ElementType!(long[][]) returns `long`. Since `int` implicitly converts to `long` (every int value is a valid long value too), this constraint passes. If it said is(E == same_stuff), it would fail because int != long. But since it is is(E : stuff), it passes because that allows implicit conversions. I'll be writing an article with content like this that links from the keyword `if` in those prototypes (Currently it links to dlang.org's spec page but that's not as useful to api doc readers IMO). I also plan to put a link to this under a "D Concepts" sub-header in the See Also section. Yes, on every page it is used. If someone lands here from a search engine, they shouldn't be assumed to already know everything! And it is hard to search for "dlang function if"...
Dec 30 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
BTW wouldn't it be great if the compiler's error messages showed 
each level of pass/fail for those constraints? For the docs, I 
don't mind doing a few special case, hand written things, but the 
compiler needs something a bit more generic.

I think the way to code that is whenever the compiler is printing 
an expression that can convert to bool, color it based on the 
result, and do this through the whole tree from the bottom up.

Then the use could tell at a glance which parts succeeded and 
failed when reading the error message.

It'd be kinda nice if it showed the result of non-bool things too 
but that's going to be hard to do on a console without becoming a 
wall of text, even with whitespace formatting...


But the compiler will come later, for now I gotta do docs!
Dec 30 2015
parent default0 <Kevin.Labschek gmx.de> writes:
On Wednesday, 30 December 2015 at 16:41:51 UTC, Adam D. Ruppe 
wrote:
 BTW wouldn't it be great if the compiler's error messages 
 showed each level of pass/fail for those constraints? For the 
 docs, I don't mind doing a few special case, hand written 
 things, but the compiler needs something a bit more generic.

 I think the way to code that is whenever the compiler is 
 printing an expression that can convert to bool, color it based 
 on the result, and do this through the whole tree from the 
 bottom up.

 Then the use could tell at a glance which parts succeeded and 
 failed when reading the error message.

 It'd be kinda nice if it showed the result of non-bool things 
 too but that's going to be hard to do on a console without 
 becoming a wall of text, even with whitespace formatting...


 But the compiler will come later, for now I gotta do docs!
I was personally thinking that it can't be horribly difficult that given a function signature: void foo(T)(T arg) if(constraintA!T && constraintB!T || constraintC!T) That if this cannot be instantiated the compiler prints something like "Candidate foo(T)(T arg) fails with (true && false || false)" I sometimes found myself putting static assert(<copy-pasted-segment-of-constraints-with-my-type>, "Result is blabla") and recompiling just to debug these :/
Dec 30 2015
prev sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Wednesday, 30 December 2015 at 04:03:42 UTC, Andrei 
Alexandrescu wrote:
 On 12/29/2015 09:09 PM, Adam D. Ruppe wrote:
 Putting one item per page is far more important than I even 
 realized
 before getting into this.
We already have that: https://dlang.org/library/std/array/join.html If I search for dlang array join that the third hit on google if I'm logged in, and the SECOND hit if I use an anonymous session that gives google no information about my searching habits. I hope you'll agree that renders the rest of your post moot, for which reason I afforded to snip it.
Which is a pity, because if you had read on you would have seen that Adam is aware of the existence of that separate page as he quoted the very link above in the part you snipped. Frankly, the fact that the Google search taken as an example here returns two different pages on dlang.org, with no visible clues whether any of them is official or experimental, is very confusing to me. I had to search hard to figure out if and how they are linked together. Turns out the one with the separate page is experimental, and has been so for two years now, according to https://dlang.org/library/index.html#comment-1281452140.
 Adam, there's no nice way to put what follows. You can code a 
 great deal, and I think the world of your engineering skills. 
 But there is something to be said about a bias for action at 
 the expense of strategy. I completely understand it's a lot 
 more fun to start a project than to bring it to completion, but 
 as they say in hardware, it's retired instructions that count. 
 I wish you'd consider converting some of your myriad brilliant 
 snippets into completed projects pushed into the standard 
 distribution for prime time, and also (for this case) to 
 consider strengthening the documentation tools we already have.
I greatly appreciate the energy both of you pour into D, but one accusing the other for not finishing projects is in this particular case a bit funny. In my eyes there are three important aspects to quality documentation: 1. Content 2. Usability (legibility, X-ref, list of contents, indices, searching) 3. Maintainability (ease to contribute, legibility in code, intuitive procedures) The official documentation is sub-standard in 2 and 3, and Adam shows to be on a fast track to address these. It is a shame there is too much friction that this be done in the official documentation. But if it is too much for Adam, I am not encouraged to even try... Bastiaan.
Jan 01
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 1 January 2016 at 16:30:44 UTC, Bastiaan Veelo wrote:
 In my eyes there are three important aspects to quality 
 documentation:
Let me summarize the benefits I see in my way for each of these three items:
  1. Content
For content, I'm making edits based on common questions I see. I've answered like 1/4 of all the D support requests in 2015 myself and there's a lot of patterns there. I'm also talking to new users and watching them code to see what problems they have myself. Doing these edits on the status quo keeps getting blocked by the overhead... we have a content problem in part because of the process/infrastructure problem.
  2. Usability (legibility, X-ref, list of contents, indices, 
 searching)
This is what the new generator does by rearranging and formatting the content. There's a new feature: $(REF ), which is a smarter reference than plain text macros allow, and header macros are built-in so the processor understands how to build a table of contents out of them too.
  3. Maintainability (ease to contribute, legibility in code, 
 intuitive procedures)
Ease and intuition: I'm creating a web interface to drop suggestions and to preview your new articles. You don't have to build the whole site (which also requires git phobos and git dmd...), just upload your new file. The final thing will still be a github pull request, but for many cases I can help myself by doing it. Legibility: I'm limiting ddoc macros to keep them simpler to understand. A comprehensive, but limited set of syntax allows you to actually learn it all and use them as you write without worrying about what weird user-defined macros are there or what the difference between XREF and XREF2 is. Most documentation should use this fancy syntax sparingly.
 there is too much friction that this be done in the official 
 documentation. But if it is too much for Adam, I am not 
 encouraged to even try...
Well, remember that I'm extremely lazy. You should still try it yourself to understand what I mean and see if you agree.
Jan 02
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 28 December 2015 at 23:05:28 UTC, Andrei Alexandrescu 
wrote:
 (a) is the new proposed system differentiated enough to justify 
 its existence and motivate others to join in?
I was just watching my newbie friend try to manipulate directories in D. His first instinct was to go to std.path. I decided to edit std.path to add a note in the header "if you want to get path names from a directory, use std.file". Linking to std.file proved to be a huge hassle. Sure, I could just $(LINK2 std_file.html, std.file) like Phobos does in other places, but alas, that breaks ddox. http://dlang.org/library/std/algorithm.html Click the "See also Reference on ranges" there and observe the 404. So I wanted to define a new macro called MREF so you'd write it $(MREF std,file) and it would replace with underscores on ddoc, slashes on ddox (and dots on my docs). Easy, right? Wait, XREF doesn't work right on modules, it expects the second arg to be a function and links break in some places if you leave it blank, and it doesn't work on submodules... can't there just be a REF thing? I guess not, the system is too complicated. Whatever though, I'll make my new MREF, or module reference. (Am I seriously the first one to do this?) Check out $(MREF std,file) and $(MREF std,algorithm,searching)! Macros: MREF_HELPER=_$1$(MREF_HELPER $+) MREF=$1$(MREF_HELPER $+).html Wow, it works! (Well, basically. It doesn't work if the module has only one name, like object.d, but we can special case that one.) But now, where do I put it? I grep for XREF in dlang.org/*.ddoc and find a few candidates then check the wiki http://wiki.dlang.org/Contributing_to_dlang.org#Macro_Definition_Ba teries:_.ddoc_files to see what it says. ...it returned files that aren't listed there... what should I do with them? Oh dear this is taking too much brain power, I just wanted to add a sentence linking people to the other module! BTW this is why my thing separates all the filenames with dots, just like D itself does. Predictable, even without semantic analysis! This huge friction has killed my desire to contribute to Phobos before and it looks like it is again. the difference is this time, I have my own fork so the community doesn't have to lose out.
Dec 30 2015
next sibling parent reply bachmeier <no spam.net> writes:
On Wednesday, 30 December 2015 at 23:05:11 UTC, Adam D. Ruppe 
wrote:
 On Monday, 28 December 2015 at 23:05:28 UTC, Andrei 
 Alexandrescu wrote:
 (a) is the new proposed system differentiated enough to 
 justify its existence and motivate others to join in?
I was just watching my newbie friend try to manipulate directories in D. His first instinct was to go to std.path. I decided to edit std.path to add a note in the header "if you want to get path names from a directory, use std.file". Linking to std.file proved to be a huge hassle. Sure, I could just $(LINK2 std_file.html, std.file) like Phobos does in other places, but alas, that breaks ddox. http://dlang.org/library/std/algorithm.html Click the "See also Reference on ranges" there and observe the 404. So I wanted to define a new macro called MREF so you'd write it $(MREF std,file) and it would replace with underscores on ddoc, slashes on ddox (and dots on my docs). Easy, right? Wait, XREF doesn't work right on modules, it expects the second arg to be a function and links break in some places if you leave it blank, and it doesn't work on submodules... can't there just be a REF thing? I guess not, the system is too complicated. Whatever though, I'll make my new MREF, or module reference. (Am I seriously the first one to do this?) Check out $(MREF std,file) and $(MREF std,algorithm,searching)! Macros: MREF_HELPER=_$1$(MREF_HELPER $+) MREF=$1$(MREF_HELPER $+).html Wow, it works! (Well, basically. It doesn't work if the module has only one name, like object.d, but we can special case that one.) But now, where do I put it? I grep for XREF in dlang.org/*.ddoc and find a few candidates then check the wiki http://wiki.dlang.org/Contributing_to_dlang.org#Macro_Definition_Ba teries:_.ddoc_files to see what it says. ...it returned files that aren't listed there... what should I do with them? Oh dear this is taking too much brain power, I just wanted to add a sentence linking people to the other module! BTW this is why my thing separates all the filenames with dots, just like D itself does. Predictable, even without semantic analysis! This huge friction has killed my desire to contribute to Phobos before and it looks like it is again. the difference is this time, I have my own fork so the community doesn't have to lose out.
Thanks for doing this Adam. The official docs are a mess. Not just what you see when you look at the website, though there are important problems with that. It's the process that requires so much overhead that nobody wants to contribute. I really tried to do so myself, but I'm busy, and it is senseless that 95% (or more) of the time I spend on it is wasted due to a system that is flawed from top to bottom. The only thing that surprises me is that there are any contributions. If you can make it easy to contribute, that is reason enough to push forward, even without the other improvements you are offering. The official docs can die a slow death and eventually Google will send newbies to your site. The only request I make is that you continue to do this yourself in order to keep it out of overhead hell. I'll be using it for sure.
Dec 30 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 31 December 2015 at 00:04:03 UTC, bachmeier wrote:
 It's the process that requires so much overhead that nobody
 wants to contribute. I really tried to do so myself, but I'm 
 busy, and it is senseless that 95% (or more) of the time I 
 spend on it is wasted due to a system that is flawed from top 
 to bottom. The only thing that surprises me is that there are 
 any contributions.
Exactly. I've put my time into ddoc. Let me give you a brief history of my efforts: ~2010: I had just written this awesome dom.d library and wanted to document it and release it to the world. I write stuff like: /// Returns the text in the element. For example, innerText of <span>foo<span> is "foo" (without quotes) string innerText(); And it came out mangled because of ddocs embedded HTML "feature" which doesn't encode the output. I proposed a fix, using ddoc's existing ESCAPES macro, and wrote the patch for dmd. Embedded html would be automatically encoded, but you can still define it in macro definitions, which can be inline with the comment, so it isn't hard to use when you want it. It was rejected. Walter didn't see what the problem was and I was told to just write $(LT)span$(GT)foo$(LT)/span$(GT). Seriously. Well, that was unacceptable so I decided to take matters into my own hands. On Feb 20, 2010, I registered dpldocs.info and started writing my own web service to delver dom.d's docs, encoding the output correctly, getting the docs out of dmd's JSON output, using -D -X. Well, it worked, but it sucked. The JSON output didn't give me enough information to do cross referencing, so I wrote a little search engine to paper over it... and that didn't help much. I moved on to other things, every so often still advocating to fix ddoc's escaping, but mostly just writing my docs such that they were readable in the source code and not bothering with generating them at all. (I'm told my source tends to be fairly readable anyway and I like to narrate my thoughts a bit in the comments including of implementation details so they understand the pros and cons of my decisions.) At some point around here, I wrote a crappy Javascript table of contents for the D website (then hosted at digitalmars.com still) - the infamous "Jump list". This was meant to be a temporary measure until ddoc got proper table of contents support. That sucky Javascript hack is still live today. 2011: We had a proposal for a website redesign. Remember this one? http://arsdnet.net/d-web-site/index.html The jump list hack garnered a lot of hate. It was a blob of text that we couldn't read, but ddoc's design made a user-defined table of contents extremely difficult to implement. A few attempts were started, but none finished. I wrote a program, called improveddoc.d, still on the 'net: http://arsdnet.net/d-web-site/improveddoc.d that post-processed the generated HTML to create a cheat-sheet table. This is what it made of std.algorithm at the time: http://arsdnet.net/d-web-site/std_algorithm.html I offered to integrate it into the website tools... and got my first look at the horror that is that build process. Nevertheless, running a little post process script to run that on the html was doable. It also would read tag macros and use them to organize the content. The idea (and working program) was rejected because the team felt a post-processor was the wrong way to do it. Instead, Andrei manually wrote a std.algorithm cheat sheet and we added a bullet between the links in the jump list hack. Both of these have remained basically unchanged to this day and dmd still cannot generate a table of contents in ddoc. We did get a website redesign after that, d-programming-language.org was launched, and Vladimir's forum got integrated (I wrote one too but his was so much better than mine that I gladly yielded). ddoc, however, barely changed. For the next couple years, despite ddoc being unusable for half my libraries because they are web libs and showing HTML examples was practically impossible, I still was basically on its side, while still working on improving the json support. I had tried the json thing and found the compiler approach to be better, but the json output is good for a few things and Ddoc's syntax isn't all that bad if you aim for source readability and clever use of recursive macros can do some pretty cool things. I put my support behind dmd. With the vibe.d team also pushing for improved json support, a few things happened there... though little of consequence. My opinion of the json output hasn't significantly changed since 2010: cool for a few things, I like that we have it, but it is not a substitute for compiler-integrated ddoc. We got another website redesign in these years, and moved to dlang.org. The build process finally got documented after I and others complained for a while, but it was never actually cleaned up. At the end of 2014, yea, even a year before this writing, people were complaining about ddoc's syntax again and asking for some Markdown variant to be introduced. Seeing an opportunity to revive my old encoding problem and finally write some ddoc for myself, I jumped on the `code` syntax and implemented it, including proper encoding of the output. Finally, I can write `<span>foo</span>` and have it legible to the user! And with it also alleviating the pressure for syntax sugar from the community... this patch was actually accepted this time! For the first time in five years, I was excited about ddoc again. I started using it to write This Week in D (and noticing the limits the macro syntax place on legible prose source...) and wrote at some length about my simpledisplay.d, cgi.d, and others (though not really much on dom.d, ironically. I still haven't gotten around to updating that.) Just a few months ago, I got the simpledisplay docs looking pretty good with ddoc: http://arsdnet.net/arsd/simpledisplay.html 2015 was a good year for ddoc and I, we basically got along, despite its warts. Then, October rolls around. A friend of a friend is looking for work and I say maybe you can help me with some D stuff. Don't know D? Not a problem, it is easy! It wasn't easy. From installation, problems arose. I'd then show how to fix it and explain why. She'd say "I understand now, but why don't the docs just say what you just said?" Good question. I decide to start editing it in... and quickly hit a brick wall that kills my momentum. I couldn't get through the nonsense before having to get back to work. I handle hundreds of D support requests in a year. Sometimes, I spend so much time on the chat, the learn forum, or Stack Overflow that I feel like I'm a full-time D support engineer. Time and time again, people ask things that ought to be pretty easy to find, yet they ask us anyway. Maybe they just don't like searching and ask first. I actually don't mind that - I tell my coworkers that if their attempts at Google don't yield results in one minute, send me an IM or email (and continue looking). There's a good chance I'll have an answer in my brain somewhere, or at least a helpful pointer, and I don't mind the interruptions at all (if I didn't want them, I'd just close the chat client!). Better to ping me than waste hours on a fruitless search. But still, some people say "I tried searching and couldn't find it"... and I totally believe that with D. I used it think it was just because we were young, but it has now been almost SIX YEARS since my first dive into the website issues and it has barely changed. There must be something systemic. Fast-forward to December. We have that base64 question. I go to edit the site and get stopped by the process again. Nevertheless, I blamed the makefile and saw new documentation Andrei wrote on this. Maybe there's still hope. Then another friend of mine tells me he finally started looking at the D Cookbook I gave him last year and is writing some code. I watch him work through a couple problems... and notice that the website was only useful to him insofar as he could copy/paste examples. As soon as he modified them and got an error message or tried to put functions together without pre-written examples, he'd slow way down. He'd get through it but not easily. The D leaders know how important examples are. We are often told adding more is low hanging fruit. I completely agree. But that's not ALL we need. He wants examples to get started, yes, but he also wants understanding to go beyond examples. That's where text helps. That's where understanding the function signatures help. Eventually, when people go to write their own libraries, they might want to do Phobos style genericity. You can't do that without understanding the function signatures... and those blobs of text are not understandable. Shift to the forum. We got talking about website redesign on the forum again a couple weeks ago and I remark how I think just whitespace formatting of the constraints would help a lot and almost went in dmd to implement it. I just got sidetracked doing a quick paragraph fix for Andrei... and then wanted to see how far I could go. I got it working, despite the obstacles that ddoc's freeform macros bring, and surprise, it was rejected. Even the simpler patch that just collapses blank lines sits unanswered. A tool to look for broken links sits unanswered. There's always a call to contributions, but when you do push through the painful process to get the code up (and the tester, the f$^%$^ing tester), nobody seems to care. The combined experience over these last six years tells me that the website sucks and it keeps sucking because changing it sucks even more than using it. A new strategy was required. And here we are. I still need to figure out how I want to add new docs and link them all in, but I guarantee you it won't consist of editing SRCS and MANIFEST and posix.mak and win32.mak and std.ddoc and latex.ddoc and <voice trails off>...
Dec 30 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/2015 08:32 PM, Adam D. Ruppe wrote:
 ~2010: I had just written this awesome dom.d library and wanted to
 document it and release it to the world. I write stuff like:

 /// Returns the text in the element. For example, innerText of
 <span>foo<span> is "foo" (without quotes)
 string innerText();

 And it came out mangled because of ddocs embedded HTML "feature" which
 doesn't encode the output. I proposed a fix, using ddoc's existing
 ESCAPES macro, and wrote the patch for dmd. Embedded html would be
 automatically encoded, but you can still define it in macro definitions,
 which can be inline with the comment, so it isn't hard to use when you
 want it.

 It was rejected. Walter didn't see what the problem was and I was told
 to just write $(LT)span$(GT)foo$(LT)/span$(GT). Seriously.
Could you please post a link to your proposed fix?
 The idea (and working program) was rejected because the team felt a
 post-processor was the wrong way to do it.
Do you have a link to that proposal and discussion?
 We got another website redesign in these years, and moved to dlang.org.
 The build process finally got documented after I and others complained
 for a while, but it was never actually cleaned up.
What steps do we need to take to clean the build process up?
 I just got sidetracked doing a quick paragraph fix for Andrei... and
 then wanted to see how far I could go. I got it working, despite the
 obstacles that ddoc's freeform macros bring, and surprise, it was
 rejected.
For reference: https://github.com/D-Programming-Language/dmd/pull/5319. I don't think it should have been accepted. It's not a good PR.
 Even the simpler patch that just collapses blank lines sits
 unanswered.
Sorry, the holiday period is not very productive what with the kids on vacation and whatnot. I'll pull your PR to my patch and will move forward with it. Thanks. Or did you work that into something standalone that I've missed?
 A tool to look for broken links sits unanswered. There's
 always a call to contributions, but when you do push through the painful
 process to get the code up (and the tester, the f$^%$^ing tester),
 nobody seems to care.
I agree and I'm sorry we're not moving faster with reviews, but really that's not ddo(c|x)'s fault.
 The combined experience over these last six years tells me that the
 website sucks and it keeps sucking because changing it sucks even more
 than using it. A new strategy was required.

 And here we are.
I hear your frustration, and for a good part I agree with it. Again: all I want is to make sure you have the right motivation and that you are fully informed of what's currently going on. Andrei
Dec 30 2015
parent reply bachmeier <no spam.net> writes:
On Thursday, 31 December 2015 at 02:40:17 UTC, Andrei 
Alexandrescu wrote:
 I agree and I'm sorry we're not moving faster with reviews, but 
 really that's not ddo(c|x)'s fault.
Any chance you can respond to this question that I posted two days ago? http://forum.dlang.org/post/pdjfvsmvdewwtjoicsam forum.dlang.org It doesn't require a review and only needs an answer of "yes" or "no". One of the nice things about Adam's site is that it has his email address on the front page.
Dec 30 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/2015 10:07 PM, bachmeier wrote:
 On Thursday, 31 December 2015 at 02:40:17 UTC, Andrei Alexandrescu wrote:
 I agree and I'm sorry we're not moving faster with reviews, but really
 that's not ddo(c|x)'s fault.
Any chance you can respond to this question that I posted two days ago? http://forum.dlang.org/post/pdjfvsmvdewwtjoicsam forum.dlang.org It doesn't require a review and only needs an answer of "yes" or "no". One of the nice things about Adam's site is that it has his email address on the front page.
Yes, linking from the official site to the wiki is perfectly fine and recommended. Thanks! -- Andrei
Dec 31 2015
prev sibling next sibling parent reply Israel <tl12000 live.com> writes:
On Thursday, 31 December 2015 at 01:32:56 UTC, Adam D. Ruppe 
wrote:

 The D leaders know how important examples are. We are often 
 told adding more is low hanging fruit. I completely agree. But 
 that's not ALL we need. He wants examples to get started, yes, 
 but he also wants understanding to go beyond examples. That's 
 where text helps. That's where understanding the function 
 signatures help. Eventually, when people go to write their own 
 libraries, they might want to do Phobos style genericity. You 
 can't do that without understanding the function signatures... 
 and those blobs of text are not understandable.
This is what hits me the most. Thats why we suggested "user contributed examples". PHP docs is the only place ive seen this. What is your stance on this and if you agree, how would you implement it? How would it work?
Dec 30 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 31 December 2015 at 06:39:27 UTC, Israel wrote:
 This is what hits me the most. Thats why we suggested "user 
 contributed examples". PHP docs is the only place ive seen 
 this. What is your stance on this and if you agree, how would 
 you implement it? How would it work?
I do not agree with comments, but I do agree with making user submissions easy. What I am envisioning right now is a kind of suggestion box thing on an individual page, where you can write up a bug report, an example, a comment, whatever, and have it emailed to me for further consideration. I'll do a quick fact-check editing then add it to the page. Of course, you can also continue to submit pull requests through github (and I'd encourage this for bigger contributors), but just emailing your thoughts to me has a lower barrier of entry. If we do a good job with the actual docs, you won't need comments. And better yet, you won't have to read through dozens of old ones to find the thing you need. On PHP, I find the comments list is too long and of too low of an average quality to be worth reading most the time. The other important thing is being able to add new pages with ease. I just dreamed up this plan while in bed last night: a new page would be a D file with a huge leading comment and a bunch of documented unit tests. (Why a regular D file? Because then we can reference it by its name, it can be listed in the package listing automatically, and you can actually compile it to test the code without any extra extraction work!) A comment at the top of "// just docs: Some Page Title" tells the generator to format it as a page rather than a normal module (this means the title in the comment will be used instead of the module name and it will have a table of contents of text sections instead of D classes, structs, and other members.) I'll make a web service where you can upload your .d file and get an instant preview. This way, you can render it without needing to figure out how to install my doc generator and build the website on your own computer. Just submit the form. Then, if you like it, you can either email the file to me and I'll take it from there, or submit a pull request to add your file. The PR will only need to do: git checkout -b my_new_file git add my_new_file.d git commit my_new_file.d -m 'add my new file!' git push No need to edit other macro files, build files, TOC files, whatever. My infrastructure takes care of that automatically. (via build **/*.d. It isn't rocket science and it baffles me that the official D system is so convoluted.) What do the files look like? Well, I'm still working on nailing this down, but it is basically a hybrid of markdown and ddoc, but it does NOT support ddoc's custom macros. First off, I think they are a mess with everyone defining the same all over (look at Phobos, it gets confusing) and secondly it makes doing semantic analysis of the text harder since a ddoc macro is freeform. With unlimited macros, any $ or comma in the text might be significant syntax! That's a pain. And it leads to bugs. Take a look at the References section here: http://dlang.org/phobos/std_base64.html It says "RFC 4648 - The Base16". The title is actually longer than that... it just had a comma in it and ddoc thought that meant end of argument. There *are* ways to handle this in ddoc, of course, and they aren't even really hard. I deal with it every week in the TWID source. But it is just one little example of a bigger problem that limits how much automatic processing we can do. Not worth it. Anyway, this is what contributed article file might look like. It continues to the end of this email: // just docs: Introduction to my new doc system /++ This is the intro line. An intro paragraph. This is seen on the article listing too. Then leave two blank lines gap for the table of contents. Now you start writing details. You can have headers, code examples, and so on like in any other doc. $(H2 The headers look like ddoc macros) They translate to the corresponding HTML and are parsed to form a table of contents which is automatically inserted in the blank area you left above. $(H3 You can descend in with headers) This section would be a sub-section of the H2 above. $(H2 References and code) You reference items with $(REF std.xml) and write code with `markdown style` or --- ddoc style --- More to come as it develops. +/ module mydocs.intro; // you give it a D name to refer to in refs /// you can also include documented unittests as full examples /// that will be attached. I need to think of some way to /// reference them in the text. If only D had named unittests! unittest { // this code can actually be compiled with dmd -unittest // right out of the box to keep your examples working well. } // all done.
Dec 31 2015
prev sibling parent Nick Sabalausky <SeeWebsiteToContactMe semitwist.com> writes:
On 12/30/2015 08:32 PM, Adam D. Ruppe wrote:
 It was rejected. Walter didn't see what the problem was and I was told
 to just write $(LT)span$(GT)foo$(LT)/span$(GT). Seriously.
[...]
 The idea (and working program) was rejected because the team felt a
 post-processor was the wrong way to do it.
That's been quite possibly THE biggest thorn in my side discouraging me from contributions. I've seen, and personally run into, plenty of cases where a non-existent ideal implementation becomes the mortal enemy of progress that already exists. I could ramble off a whole list of cases. It's sooo much easier to just do my own thing and "get it done" than waste effort on politics and playing the "is this worthwhile?" game with people who prefer wasting their time defending stagnation over stepping back and allowing others to just get problems fixed, even if not in an perfectly ideal way. I'll take a temporarily imperfect solution over vaporware ideals any day.
Jan 31
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/2015 06:05 PM, Adam D. Ruppe wrote:
 the difference is this time, I have my own fork so the community doesn't
 have to lose out.
All I want is to make sure you know your reasons and assumptions. The assumption there isn't a Phobos documentation with item-per-page was wrong. It seems to me referencing another module is trivial to fix as well. Andrei
Dec 30 2015
prev sibling parent reply JohnCK <j j.com> writes:
On Wednesday, 30 December 2015 at 23:05:11 UTC, Adam D. Ruppe 
wrote:
 This huge friction has killed my desire to contribute to Phobos 
 before and it looks like it is again.

 the difference is this time, I have my own fork so the 
 community doesn't have to lose out.
Please keep the good work. The current documentation is a mess, but the "heads" can't see it. I have a lot a free time, I'd already pointed out the error links you gave on the other response, but in fact I'd like to fix by myself, but then I see how hard is the current process that I couldn't go with it. But currently I'm looking to your project and maybe I could help there. JohnCK.
Jan 02
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 2 January 2016 at 19:31:24 UTC, JohnCK wrote:
 But currently I'm looking to your project and maybe I could 
 help there.
Well, the generator core is almost stable now, so pretty soon we'll be moving on to the other things. If I can keep up my vacation pace, this would be set in two more weeks, but since I have to go back to real work soon, we're probably more realistically looking at about two months to beta quality. (Though I do feel it is already a lot better than the status quo! It's not like ddoc does inheritance tree walking either.... though one huge advantage of being in dmd is it pretty easily could...) Here's my todo list: * link the attributes to explanation pages * add type class tag to navbar * fix contract formatting * show invariants for structs and classes * parse old-style aliases * create a package listing * cross-linking, including inherited members * implement the "// just docs" thing * a few syntax changes * table of contents when inner sections are detected * UI - auto-scan a directory (currently it loops over args[1..$]) * Template constraint analyzer * I don't like the module list view yet. I'm surprisingly pretty happy with the overall look though, it is prettier than I expected coming out of me. (It helps that I stole ideas from elsewhere tho.) Known bugs: * Throws: section isn't implemented yet * REF isn't as smart as it could be * the inline code scanner doesn't run inside macros * the code is ugly as sin * DDOC_PSYMBOL ruins my life. * Overloading of templates with different constraints isn't recognized * nav doesn't recognize when you are looking at an overload Ecosystem todo: * write all the other linked documents explaining language features. I have like a dozen of these linked. * make the search better * "introduced in Phobos version" detection * Auto-link See Also docs for C functions * The suggestion box and preview uploader. Third party libs can contribute too - we can have a single place to browse D library documentation kinda like Ruby does (except Ruby's docs are horribly awful, we should try to do better). * Make it obvious how people can contribute * Package the code for others to use (it will be GPL'd btw, it uses some GPL components) * Improve Phobos docs to the max using the new system.
Jan 02
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 2 January 2016 at 21:06:19 UTC, Adam D. Ruppe wrote:
 * cross-linking, including inherited members
I got this working in simple cases... which happens to include Phobos' std.socket! http://dpldocs.info/experimental-docs-2/std.socket.UdpSocket.html I did a major refactoring of the code today to enable moving forward past the block I hit over the weekend. The code is still bad... but not embarrassingly so anymore, and it makes it a LOT easier to work with. I did step backward a few steps though (the var FIXME in the output is the result of that), but forward many more. ddox makes an attempt at inheritance linking, but I'm trying to go further. If I'm successful in my dream, it will list overridden methods in the docs nicely too. But that's still a ways away. First, I need to re-add the features I dropped in the refactoring (compare the above with this: http://dpldocs.info/experimental-docs/std.socket.UdpSocket.html )
Jan 04
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-05 01:23, Adam D. Ruppe wrote:

 ddox makes an attempt at inheritance linking, but I'm trying to go
 further. If I'm successful in my dream, it will list overridden methods
 in the docs nicely too. But that's still a ways away.
I suggest showing only links to inherited members, not the docs for them. I think that the Eclipse Java documentation is pretty good [1], except for its crappy UI surrounding the docs. It actually looks better with JavaScript disabled. Anyway, it shows inherited fields and methods. For classes it shows known subclasses and for interfaces known implementations. The Scala docs [2] are pretty good as well. Separates abstract and concrete methods. Separate sections for the different protection levels and so on. [1] http://help.eclipse.org/luna/topic/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/core/dom/Expression.html [2] http://www.scala-lang.org/api/current/#scala.collection.Map -- /Jacob Carlborg
Jan 05
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 January 2016 at 08:12:56 UTC, Jacob Carlborg wrote:
 I suggest showing only links to inherited members, not the docs 
 for them.
What I want to show is the links plus just the first excerpt of the docs, so you have an idea what it is aside from the name without taking up a lot of space. My thing doesn't quite cut out the excerpt right yet though (really because so many of the Phobos docs don't follow a sane convention... I need to go back and rewrite a few of the summaries myself.)
 Anyway, it shows inherited fields and methods. For classes it 
 shows known subclasses and for interfaces known implementations.
Yeah, "known" is good because then it demos that there can be more. I like that.
 The Scala docs [2] are pretty good as well. Separates abstract 
 and concrete methods. Separate sections for the different 
 protection levels and so on.
Interesting. Separating abstract is definitely a good idea since you kinda need to know that to implement. There's so much potential for class docs! Pity Phobos doesn't use them much though :(
Jan 05
parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-05 15:16, Adam D. Ruppe wrote:

 Interesting. Separating abstract is definitely a good idea since you
 kinda need to know that to implement.
I would really like to be able to write documentation for private methods as well, but hide them by default. I think it can be good when one is working on the implementation of a library.
 There's so much potential for class docs! Pity Phobos doesn't use them
 much though :(
Hehe, yeah. -- /Jacob Carlborg
Jan 05
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 January 2016 at 16:06:17 UTC, Jacob Carlborg wrote:
 I would really like to be able to write documentation for 
 private methods as well, but hide them by default. I think it 
 can be good when one is working on the implementation of a 
 library.
Right. In my thing, it is controlled by a flag when you run the generator. Same with undocumented methods, I sometimes like seeing them in the listing, so that's a flag too. I'm almost happy enough with this code to post it btw, so you all can play with it yourselves soon. It was embarrassingly bad in its first week, I just hacked quickly but I refactored yesterday and it is starting to look like it wasn't written by letting my cat dance on the keyboard. (Yes, I get embarrassed posting excessively ugly code to the Internet. I often don't like posting things until it it at least semi-stable alpha quality.)
Jan 05
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-05 01:23, Adam D. Ruppe wrote:

 First, I need to re-add the features I dropped in the refactoring
 (compare the above with this:
 http://dpldocs.info/experimental-docs/std.socket.UdpSocket.html )
"Address" not being cross-linked here [1] while "SocketOSException" is. [1] http://dpldocs.info/experimental-docs/std.socket.getAddress.html -- /Jacob Carlborg
Jan 05
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 January 2016 at 08:31:55 UTC, Jacob Carlborg wrote:
 "Address" not being cross-linked here [1] while 
 "SocketOSException" is.
thanks! That's one I missed in the Phobos source code.
Jan 05
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/2/16 2:31 PM, JohnCK wrote:
 On Wednesday, 30 December 2015 at 23:05:11 UTC, Adam D. Ruppe wrote:
 This huge friction has killed my desire to contribute to Phobos before
 and it looks like it is again.

 the difference is this time, I have my own fork so the community
 doesn't have to lose out.
Please keep the good work. The current documentation is a mess, but the "heads" can't see it. I have a lot a free time, I'd already pointed out the error links you gave on the other response, but in fact I'd like to fix by myself, but then I see how hard is the current process that I couldn't go with it. But currently I'm looking to your project and maybe I could help there.
A few follow-up questions, all serious: Do the projected advantages of Adam's project do not include ease of contribution? If so, how? Would it be productive to reduce friction to contribute to the current two documentation systems we have, instead of coming with a third system that is likely to have its own issues? What are the exact difficulties of improving the documentation that you just cannot push past in spite of having time and willingness to contribute? Andrei
Jan 03
next sibling parent JohnCK <j j.com> writes:
On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu 
wrote:
 A few follow-up questions, all serious:
Fair enough... but most of the points you're asking they already have been discussed all over the forums, and some in this topic, like those exposed by Adam. Like I said currently I have free time and sometimes when I find small problems I just say to myself, look I could help on this... but then I remember all the friction. And again I'm just talking about small things like fixing wrong URLs or add more examples to the functions and so on but the current process isn't easy. You may think this is another whining but you know that while DDoc's is a great tool for a problem with docs that you had in the past, maybe need to be re-evaluated now. I'm not saying to stop using tomorrow, but finding ways to make things easy, that anyone could help easily with less friction. JohnCK.
Jan 04
prev sibling next sibling parent JohnCK <j j.com> writes:
On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu 
wrote:
 A few follow-up questions, all serious:
Sorry, I just forgot an important thing. Somewhere in the beginning of this topic, you had advised Adam to put his efforts into another thing, right? So imagine this with: D vs C++ where someone comes to you and says: Andrei why are you doing this new language, instead, go back to C++ and put these ideas there. You know many see D as language that has the power/speed C++ but is simpler, right? Maybe the same thing is happening here. I think you should reflect about this. JohnCK.
Jan 04
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
FYI, even now, I hesitate to change links in my Phobos fork 
because I kinda want to remain ddoc compatible... and I can never 
remember what macro it is. And I've been kinda deep in this the 
whole last week.


Anyway, let's get into this:


On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu 
wrote:
 Do the projected advantages of Adam's project do not include 
 ease of contribution? If so, how?
1) a massively simplified build. Indeed, I'll make a web form so you don't even have to have dmd installed to make some docs. This got posted today: https://issues.dlang.org/show_bug.cgi?id=15516#c2 Two people whose names I recognize who have been with D for a long time didn't know how to add a page to the website. And what they did figure out was a multi step process. My system already runs a single file or an entire directory and just works. It will never forget a file because you didn't add it to mak/DOCS of win32.mak or anything else. I'll also make a web form to upload new pages and probably entire projects for automatic processing too. 2) My linking system already works better than ddoc allows. You can reference with a single macro: $(REF some.name). I also keep MREF, XREF, and a few others for legacy phobos+ddoc compatibility, but the user doesn't have to know a hundred obscure macros. (There's about a half-dozen simple ones instead, plus a few thin wrappers over HTML which I might kill but might not since they don't really bother me.) Combined with the ease of adding all new files, contributors can just link new articles they write to go in depth without worrying about process. 3) I'm also going to make a dynamic webpage once I declare this beta where viewers will be given random pages and asked to eyeball it for me. If they flag it as buggy - with a single click on the page, no bugzilla signups - it'll contact me and I'll work on the bug. If they want to contribute to content, I can pull up the existing comment source code and present it right there, again likely emailed to me for integration, or the source location can be opened in Phobos for a traditional pull request. This will encourage crowd sourcing doc bug fixes. 4) I'll never complain about spaces vs tabs, line length, or any other trivial nonsense. If I don't like that stuff, I'll just fix it myself instead of letting the PR wither and die while letting the contributor feel undervalued.
Jan 04
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/05/2016 12:09 AM, Adam D. Ruppe wrote:
 1) a massively simplified build. Indeed, I'll make a web form so you
 don't even have to have dmd installed to make some docs.
Nice. The web forms sound like a great idea.
 This got posted today:
 https://issues.dlang.org/show_bug.cgi?id=15516#c2

 Two people whose names I recognize who have been with D for a long time
 didn't know how to add a page to the website. And what they did figure
 out was a multi step process.

 My system already runs a single file or an entire directory and just
 works. It will never forget a file because you didn't add it to mak/DOCS
 of win32.mak or anything else.
There's been a recent discussion with Walter and Martin about using wildcards in makefiles (which would obviate the necessity of being explicit about files). My understanding is that build scripts (including makefiles) are recommended to include a manifest list of files that are part of the project, as opposed to picking up files with wildcards. That way there's less likelihood to pick up litter along with the legitimate files, or to produce incomplete builds if some files are missing by mistake. The underlying thesis is that that's a good kind of redundancy. That said, in a git-controlled directory things aren't that bad. "git clean -dfx" removes uncontrolled files and "git checkout" makes sure all files are present. Would you recommend switching to wildcards in our makefiles and assume people use git to keep their directories in good shape? Regarding the makefile complications. I think it stands to reason that in the dlang.org repo, the command "make" will produce the entire website. There are quite a few pieces to that: * The druntime and phobos docs must be built as well. * For these there are the docs as per last release and also the docs in the current HEAD, which are distinct. * Each library version must be built with the same compiler version. The appropriate compiler version might be missing, so it needs to be downloaded, installed, and run on the side without affecting any existing installation. * There are ancillary things to be build, such as the vibe docs and the language reference (ebook, pdf, chm). The ebook has ranked #26 among most downloaded files on dlang.org, the pdf is #40, and the chm is apparently not in the top 256. The most popular ddox file is http://dlang.org/library, ranking at #96. My understanding is that your system does not do any of these things. If such functionality were to be integrated, either the system would increase in complexity correspondingly, or it would become a part of a larger build script. The script https://github.com/D-Programming-Language/dlang.org/blob/master/posix.mak stands at 498 lines. What ways there are to make it considerably simpler and smaller?
 I'll also make a web form to upload new pages and probably entire
 projects for automatic processing too.
Indeed the web forms sound like a great idea. Would you want to work on such for the mainline website as well? It's not a contest; the better everything is, the better off everybody is.
 2) My linking system already works better than ddoc allows. You can
 reference with a single macro: $(REF some.name). I also keep MREF, XREF,
 and a few others for legacy phobos+ddoc compatibility, but the user
 doesn't have to know a hundred obscure macros. (There's about a
 half-dozen simple ones instead, plus a few thin wrappers over HTML which
 I might kill but might not since they don't really bother me.)
Nice. What could we do in ddoc and ddox to have a similar improvement?
 Combined with the ease of adding all new files, contributors can just
 link new articles they write to go in depth without worrying about process.



 3) I'm also going to make a dynamic webpage once I declare this beta
 where viewers will be given random pages and asked to eyeball it for me.
 If they flag it as buggy - with a single click on the page, no bugzilla
 signups - it'll contact me and I'll work on the bug.
How do you envision scaling it up as the system becomes more successful and you get more requests than you can handle reasonably quick? Would you be willing to set up such a system for dlang.org as well? It would be absolutely fantastic.
 If they want to contribute to content, I can pull up the existing
 comment source code and present it right there, again likely emailed to
 me for integration, or the source location can be opened in Phobos for a
 traditional pull request.

 This will encourage crowd sourcing doc bug fixes.
My understanding is a lot of it hinges on you being on top of things (and the bottleneck thereof). I think it's awesome that you're able and willing to do this; the same kind of enthusiasm and dedication would definitely help fix a lot of the existing issues with ddoc and ddox.
 4) I'll never complain about spaces vs tabs, line length, or any other
 trivial nonsense. If I don't like that stuff, I'll just fix it myself
 instead of letting the PR wither and die while letting the contributor
 feel undervalued.
Anyone could do the same today for all pull requests - just fetch them, fix them, and resubmit with credit. Additionally, team members could just pull the PR, fix it, and make an additional commit. Regarding PRs that are not looked at, we currently have 18 PRs at https://github.com/D-Programming-Language/dlang.org/pulls, and 16 folks who have the rights to pull them (https://github.com/orgs/D-Programming-Language/teams/team-dlang-org). I'll take a look at them after this (some look really trivial); it's a bummer they aren't looked at more regularly. I'll note that you are already a member of that team so you already had the rights to exact quite a few of the improvements you intend to make going forward. Would you please join me in taking a look at older PRs (oldest is from 2014) and pull them in? Overall my understanding of your message is "My system would be better not for a fundamental technical reason, but because I am willing to pour in it time and talent." This is the kind of argument I have a lot of respect for. Thanks, Andrei
Jan 05
next sibling parent reply bachmeier <no spam.com> writes:
On Tuesday, 5 January 2016 at 14:18:32 UTC, Andrei Alexandrescu 
wrote:

 Overall my understanding of your message is "My system would be 
 better not for a fundamental technical reason, but because I am 
 willing to pour in it time and talent." This is the kind of 
 argument I have a lot of respect for.
IMO it's not just his willingness to put in the time that is different. There are some critical technical differences: - There is one person making the decision. - You don't have to worry about unstated (and sometimes arbitrary) rules. The current system feels like your dealing with the Soup Nazi. - You don't have to mess with Git. For me, that's a big one, because I've never used Git for a large project like this. - You don't have to build the whole website. You don't have to do Phobos unit tests to change a broken link. I'll give you an example. Not by coincidence, this was the last contribution I attempted to make. I read the documentation for schwartzSort, and finding that it conveyed no information, I wanted to suggest something better. A discussion forum or email message would be the ideal way to do so, but knowing that's not how things are done here, I decided to submit a PR. After at least a couple hours (it may have been more) looking at other documentation to find ideas for how to do it better, doing several revisions to get to something I found satisfactory, checking for no trailing spaces and making sure the syntax was consistent with the other documentation, battling with Git, and battling to get the full site to build, I submitted this: https://github.com/D-Programming-Language/phobos/pull/3831 One person reviewed it and didn't like my change, because he felt the existing documentation was better. Later, someone commented that he liked my version. And now it's sitting there. It's not going to be accepted and because nobody's in charge of the documentation it won't be closed either. The problem is not that my PR was (for practical purposes) rejected. As an academic I deal with both sides of peer review all the time. The problem is that I was forced to put so much time into it just to make a suggestion. With Adam's project, I can send him an email with a suggested change, and he can do as he wishes with it. It will take two minutes of my time.
Jan 05
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/05/2016 10:15 AM, bachmeier wrote:
 There are some critical technical differences:

 - There is one person making the decision.
Not technical. -- Andrei
Jan 05
next sibling parent bachmeier <no spam.com> writes:
On Tuesday, 5 January 2016 at 15:32:52 UTC, Andrei Alexandrescu 
wrote:
 On 01/05/2016 10:15 AM, bachmeier wrote:
 There are some critical technical differences:

 - There is one person making the decision.
Not technical. -- Andrei
http://www.snopes.com/humor/letters/miriam.asp
Jan 05
prev sibling parent JohnCK <j j.com> writes:
On Tuesday, 5 January 2016 at 15:32:52 UTC, Andrei Alexandrescu 
wrote:
 On 01/05/2016 10:15 AM, bachmeier wrote:
 There are some critical technical differences:

 - There is one person making the decision.
Not technical. -- Andrei
Indeed but on the other hand is impacting the technical stuff. JohnCK.
Jan 05
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/05/2016 10:15 AM, bachmeier wrote:
 I read the documentation for schwartzSort, and finding that it conveyed
 no information, I wanted to suggest something better. A discussion forum
 or email message would be the ideal way to do so, but knowing that's not
 how things are done here, I decided to submit a PR. After at least a
 couple hours (it may have been more) looking at other documentation to
 find ideas for how to do it better, doing several revisions to get to
 something I found satisfactory, checking for no trailing spaces and
 making sure the syntax was consistent with the other documentation,
 battling with Git, and battling to get the full site to build, I
 submitted this:

 https://github.com/D-Programming-Language/phobos/pull/3831

 One person reviewed it and didn't like my change, because he felt the
 existing documentation was better. Later, someone commented that he
 liked my version. And now it's sitting there. It's not going to be
 accepted and because nobody's in charge of the documentation it won't be
 closed either.
Thanks for submitting. The way I see it is that PR needs improvement. The bar is low seeing as pretty much any addition to the documentation is good. So all you need to do is make sure the addition is of good quality. So the proposed final text is: ============ Returns the same output as an equivalent call to $(D sort), but it will be faster when the sort comparison requires an expensive computation. $(D schwartzSort) allocates a temporary array to cache the sort keys. It can therefore be slower than $(D sort) in other cases. Sorts a range using an algorithm akin to the $(WEB wikipedia.org/wiki/Schwartzian_transform, Schwartzian transform), also known as the decorate-sort-undecorate pattern in Python and Lisp. The complexity is the same as that of the corresponding $(D sort), but $(D schwartzSort) evaluates $(D transform) only $(D r.length) times (less than half when compared to regular sorting). The usage can be best illustrated with an example. ============= The text is imprecise, e.g. an equivalent call to `sort` really is `sort!((a, b) => less(transform(a), transform(b))`. All that detail needn't be present in the first paragraph, so there's a bit of an art in how you formulate simple sentences that are at the same time correct and informative. The second paragraph used to be the first (and only) one. Now it doesn't flow from the first one, it's jarring. Here's a possible improved text (feel free to copy, paste, adapt etc): ============ Alternative sorting method that should be used when comparing keys involves an expensive computation. Instead of using `less(a, b)` for comparing elements, `schwartzSort` uses `less(transform(a), transform(b)`. The values of the `transform` function are precomputed in a temporary array, thus saving on repeatedly computing it. Conversely, if the cost of `transform` is small compared to the cost of allocating and filling the precomputed array, `sort` may be faster and therefore preferable. This approach to sorting is akin to the $(WEB wikipedia.org/wiki/Schwartzian_transform, Schwartzian transform), also known as the decorate-sort-undecorate pattern in Python and Lisp. The complexity is the same as that of the corresponding $(D sort), but $(D schwartzSort) evaluates $(D transform) only $(D r.length) times (less than half when compared to regular sorting). The usage can be best illustrated with an example. =============
 The problem is not that my PR was (for practical purposes) rejected. As
 an academic I deal with both sides of peer review all the time. The
 problem is that I was forced to put so much time into it just to make a
 suggestion. With Adam's project, I can send him an email with a
 suggested change, and he can do as he wishes with it. It will take two
 minutes of my time.
I agree that the best aspect of Adam's system is Adam. Andrei
Jan 05
next sibling parent reply default0 <Kevin.Labschek gmx.de> writes:
On Tuesday, 5 January 2016 at 15:54:24 UTC, Andrei Alexandrescu 
wrote:
 On 01/05/2016 10:15 AM, bachmeier wrote:
 The problem is not that my PR was (for practical purposes) 
 rejected. As
 an academic I deal with both sides of peer review all the 
 time. The
 problem is that I was forced to put so much time into it just 
 to make a
 suggestion. With Adam's project, I can send him an email with a
 suggested change, and he can do as he wishes with it. It will 
 take two
 minutes of my time.
I agree that the best aspect of Adam's system is Adam. Andrei
Yes, and because its lots of effort flowing into something that D is usually very fond of: Simplicity. I remember looking at a part of the documentation and wanting to suggest a change of wording in a few sentences, since I felt like they didn't convey information clear enough, but after seeing that I would have to somehow best-guess my way through tons of macro syntax without clear indication on where to look for explanations of anything I bailed. Not about to spend half a day or a day to suggest changing three sentences and be told that they were fine as is. Sending Adam an E-Mail is something I totally would've done though :-)
Jan 05
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/05/2016 11:35 AM, default0 wrote:
 Yes, and because its lots of effort flowing into something that D is
 usually very fond of: Simplicity.
I'll be curious how the simplicity theme keeps when needed features get added. dlang.org started very simple and grew by accretion.
 I remember looking at a part of the documentation and wanting to suggest
 a change of wording in a few sentences, since I felt like they didn't
 convey information clear enough, but after seeing that I would have to
 somehow best-guess my way through tons of macro syntax without clear
 indication on where to look for explanations of anything I bailed. Not
 about to spend half a day or a day to suggest changing three sentences
 and be told that they were fine as is.
Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along the lines of what you need? What other sort of documentation would you find useful?
 Sending Adam an E-Mail is
 something I totally would've done though :-)
Again this goes back to Adam. Let's say we had a contributor Eve who'd gladly take emailed questions and suggestions and integrate them. Would that be as nice? Andrei
Jan 05
next sibling parent reply JohnCK <j j.com> writes:
On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
wrote:
 Is the recent http://wiki.dlang.org/Contributing_to_dlang.org 
 along the lines of what you need? What other sort of 
 documentation would you find useful?
I took a look at that link, and you know what would be (at least for me) more useful? A "Let's write a doc example", for example: Creating a sample function and documented it, step by step. I really think that would be many times more useful and you see that pattern a lot not only for docs, but explain things, currently we saw this in another topic about writing a scalable chat using vibe.d! JohnCK.
Jan 05
next sibling parent John Colvin <john.loughran.colvin gmail.com> writes:
On Tuesday, 5 January 2016 at 18:34:20 UTC, JohnCK wrote:
 On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
 wrote:
 Is the recent http://wiki.dlang.org/Contributing_to_dlang.org 
 along the lines of what you need? What other sort of 
 documentation would you find useful?
I took a look at that link, and you know what would be (at least for me) more useful? A "Let's write a doc example", for example: Creating a sample function and documented it, step by step. I really think that would be many times more useful and you see that pattern a lot not only for docs, but explain things, currently we saw this in another topic about writing a scalable chat using vibe.d! JohnCK.
+1 That wiki article is a great reference, but it's pretty daunting when someone just wants to make a small change.
Jan 05
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/05/2016 01:34 PM, JohnCK wrote:
 On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu wrote:
 Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along
 the lines of what you need? What other sort of documentation would you
 find useful?
I took a look at that link, and you know what would be (at least for me) more useful? A "Let's write a doc example", for example: Creating a sample function and documented it, step by step. I really think that would be many times more useful and you see that pattern a lot not only for docs, but explain things, currently we saw this in another topic about writing a scalable chat using vibe.d!
Thanks, that's a neat idea - will keep in mind! -- Andrei
Jan 06
prev sibling next sibling parent Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
wrote:
 Again this goes back to Adam. Let's say we had a contributor 
 Eve who'd gladly take emailed questions and suggestions and 
 integrate them. Would that be as nice?
Ohoh... Keep Eve out of it, she's got an Apple.
Jan 05
prev sibling next sibling parent bachmeier <no spam.com> writes:
On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
wrote:

 Again this goes back to Adam. Let's say we had a contributor 
 Eve who'd gladly take emailed questions and suggestions and 
 integrate them. Would that be as nice?
Yes. But I would also be happy with something simpler. If there was a person not named Andrei or Walter in charge of the docs, and I could email them to propose a change, and they'd say, "I don't think that is an improvement so don't bother" or "Okay, but you need to do this for it to be accepted" I would be willing to create the PR myself. I would even be willing to help Eve by creating PR's once she has decided what needs to be done when others email with suggestions.
Jan 05
prev sibling next sibling parent reply default0 <schneider.cedric gmx.de> writes:
On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
wrote:
 On 01/05/2016 11:35 AM, default0 wrote:
 Yes, and because its lots of effort flowing into something 
 that D is
 usually very fond of: Simplicity.
I'll be curious how the simplicity theme keeps when needed features get added. dlang.org started very simple and grew by accretion.
From Adam's responses it would seem he is going to ignore most of the features the original dlang.org has in favor of focussing on HTML documentation.
 I remember looking at a part of the documentation and wanting 
 to suggest
 a change of wording in a few sentences, since I felt like they 
 didn't
 convey information clear enough, but after seeing that I would 
 have to
 somehow best-guess my way through tons of macro syntax without 
 clear
 indication on where to look for explanations of anything I 
 bailed. Not
 about to spend half a day or a day to suggest changing three 
 sentences
 and be told that they were fine as is.
Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along the lines of what you need? What other sort of documentation would you find useful?
Yes, this is helpful in providing background on how to make changes. That said, the amount of content on this page is telling that it'll be an involved process to set stuff up, especially if at some point in my setup I get errors that are neither explained nor straightforward to track down. So while this is helpful, it also makes it clear that there's a not-low barrier to entry if I do want to introduce a change - which is fine, except if it's documentation that barrier to entry should be actually formulating coherent, understandable and thorough documentation rather than a build system.
 Sending Adam an E-Mail is
 something I totally would've done though :-)
Again this goes back to Adam. Let's say we had a contributor Eve who'd gladly take emailed questions and suggestions and integrate them. Would that be as nice? Andrei
Much nicer than reading a somewhat long page on how to set up a new development environment and fiddling with it until it does what I want, followed by trying to guess what macros I need to invoke for displaying what things, followed by checking if it renders as expected or if I accidentally used a "," incorrectly somewhere instead of just formulating a documentation text that is hopefully an improvement over what existed prior to it (or filling a void that used to be there) :-) In the end most of this comes down to a lack of motivation: I'm fine trying to improve documentation text if I see an issue about it, but if that entails stopping what I was originally doing for so long that I will possibly forget what I was originally doing (ie requires me to read documentation on how to set up a whole new development environment), I will usually decide that nah, it isn't THAT important. While I could obviously reuse the setup after I did it once, I'm not keen on doing it once, I do happen to be a really lazy person about setting things up (not so much doing actual work on something that is already set up, though) because I tend to get really weird errors for really weird reasons when trying to (not in particular with D - I just always seem to be doing everything wrong when setting anything up).
Jan 05
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/16 1:54 AM, default0 wrote:
 In the end most of this comes down to a lack of motivation: I'm fine
 trying to improve documentation text if I see an issue about it, but if
 that entails stopping what I was originally doing for so long that I
 will possibly forget what I was originally doing (ie requires me to read
 documentation on how to set up a whole new development environment), I
 will usually decide that nah, it isn't THAT important.
Yeah, I empathize a lot. Adam's idea for using web forms for fixes is great. Here's a simple idea we can implement rather quickly. Say a user is browsing https://dlang.org/builtin.html and find a typo. They press a button labeled "Fix typo". That opens https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd. From there people can edit the source file to fix the typo and create a PR, all without leaving the browser or building the documentation. If this is too heavy-handed, I think Adam's idea of web forms for simple changes is great. We could devise a simple web form in e.g. errata format a la "Replace this" ... "With this". Would this improve the state of affairs? Creating the "Fix Typo" button is an easy project. Andrei
Jan 07
next sibling parent reply anonymous <anonymous example.com> writes:
On 07.01.2016 14:31, Andrei Alexandrescu wrote:
 Here's a simple idea we can implement rather quickly. Say a user is
 browsing https://dlang.org/builtin.html and find a typo. They press a
 button labeled "Fix typo". That opens
 https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd.
 From there people can edit the source file to fix the typo and create a
 PR, all without leaving the browser or building the documentation.
We have this already. Top right corner, "Improve this page". People are using the feature occasionally.
Jan 07
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/7/16 8:38 AM, anonymous wrote:
 On 07.01.2016 14:31, Andrei Alexandrescu wrote:
 Here's a simple idea we can implement rather quickly. Say a user is
 browsing https://dlang.org/builtin.html and find a typo. They press a
 button labeled "Fix typo". That opens
 https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd.

 From there people can edit the source file to fix the typo and create a
 PR, all without leaving the browser or building the documentation.
We have this already. Top right corner, "Improve this page". People are using the feature occasionally.
Yes, in fact, core developers use this too. It's actually quite a bit more convenient than doing stuff locally. -Steve
Jan 07
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/07/2016 09:05 AM, Steven Schveighoffer wrote:
 On 1/7/16 8:38 AM, anonymous wrote:
 On 07.01.2016 14:31, Andrei Alexandrescu wrote:
 Here's a simple idea we can implement rather quickly. Say a user is
 browsing https://dlang.org/builtin.html and find a typo. They press a
 button labeled "Fix typo". That opens
 https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd.


 From there people can edit the source file to fix the typo and create a
 PR, all without leaving the browser or building the documentation.
We have this already. Top right corner, "Improve this page". People are using the feature occasionally.
Yes, in fact, core developers use this too. It's actually quite a bit more convenient than doing stuff locally.
Ah, sorry. I knew "Improve this page" existed but thought it goes through a more elaborate process. Shame on me I didn't bother to try it before posting... Would it be a good idea to make that button more prominent? Andrei
Jan 07
prev sibling parent lobo <swamplobo gmail.com> writes:
On Thursday, 7 January 2016 at 14:05:27 UTC, Steven Schveighoffer 
wrote:
 On 1/7/16 8:38 AM, anonymous wrote:
 On 07.01.2016 14:31, Andrei Alexandrescu wrote:
 Here's a simple idea we can implement rather quickly. Say a 
 user is
 browsing https://dlang.org/builtin.html and find a typo. They 
 press a
 button labeled "Fix typo". That opens
 https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd.

 From there people can edit the source file to fix the typo 
 and create a
 PR, all without leaving the browser or building the 
 documentation.
We have this already. Top right corner, "Improve this page". People are using the feature occasionally.
Yes, in fact, core developers use this too. It's actually quite a bit more convenient than doing stuff locally. -Steve
I'm a D user and forum lurker, not a contributor. I have used this feature several times in the past and it was seamless and easy each time. For small typos/one-liners it takes <5 minutes to edit changes and submit the PR. Cheers, lobo
Jan 07
prev sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Thursday, 7 January 2016 at 13:38:20 UTC, anonymous wrote:
 We have this already. Top right corner, "Improve this page". 
 People are using the feature occasionally.
My first experience with this: 1) Seems to work well enough initially, if you can do without a preview. 2) Then the request comes to rebase to stable [1]. There is no web interface for that, so I followed friendly instructions from the reviewer and created a new PR by hand by clicking through github and redoing the changes. Not so smooth but doable if you have been on github before. 3) Then the PR needs to be rebased again because of merge conflicts, introduced by another PR [2]. Reluctant to close the PR and correcting the mistakes a third time in a new PR, I decided to download a local clone and merge locally. Git not being part of my daily routines, that was as smooth as I feared it would be (not at all). Fixing these small documentation errors took more than an hour of my time. I just hope the PR can be merged before it needs rebasing again ;-) [1] https://github.com/D-Programming-Language/phobos/pull/3907 [2] https://github.com/D-Programming-Language/phobos/pull/3908 Bastiaan.
Jan 07
parent anonymous <anonymous example.com> writes:
On 08.01.2016 00:13, Bastiaan Veelo wrote:
 My first experience with this:
[...]
 Fixing these small documentation errors took more than an hour of my
 time. I just hope the PR can be merged before it needs rebasing again ;-)
The master plan here is to get you invested in D. You just spent a non-trivial amount of time on improving it. You may think that has been annoying, but at the same time you don't want to see the effort go to waste. You want D to succeed now. You're one of us now. One of us. One of us. ;) More seriously, maybe someone more experienced should just take over in such cases. I think people don't do that, because * it's not common practice, * they have more than enough on their plate already, * they want to encourage the newbie to become familiar with the system so that they'll be able to make larger contributions in the future, * they don't want to steal the newbie's credit, * they'd have to wait for another staff member to review it while they can just pull it themselves when the newbie perseveres (not sure if that one's accurate). But you can totally say that it's too much trouble for you, and that you'd like someone else to take over, of course. Also, a tip: After rebasing, leave a message stating that you did. Reviewers are not notified of rebases by GitHub.
Jan 07
prev sibling parent default0 <Kevin.Labschek gmx.de> writes:
On Thursday, 7 January 2016 at 13:31:57 UTC, Andrei Alexandrescu 
wrote:
 On 1/6/16 1:54 AM, default0 wrote:
 In the end most of this comes down to a lack of motivation: 
 I'm fine
 trying to improve documentation text if I see an issue about 
 it, but if
 that entails stopping what I was originally doing for so long 
 that I
 will possibly forget what I was originally doing (ie requires 
 me to read
 documentation on how to set up a whole new development 
 environment), I
 will usually decide that nah, it isn't THAT important.
Yeah, I empathize a lot. Adam's idea for using web forms for fixes is great. Here's a simple idea we can implement rather quickly. Say a user is browsing https://dlang.org/builtin.html and find a typo. They press a button labeled "Fix typo". That opens https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd. From there people can edit the source file to fix the typo and create a PR, all without leaving the browser or building the documentation. If this is too heavy-handed, I think Adam's idea of web forms for simple changes is great. We could devise a simple web form in e.g. errata format a la "Replace this" ... "With this". Would this improve the state of affairs? Creating the "Fix Typo" button is an easy project. Andrei
Something along those lines would certainly be very encouraging for making small changes here or there, as it removes much of the learning curve if all I want to do is suggest to change something. That being said, the improvement would be marginal if most of these PRs end up not getting much attention. For instance, if what I'm doing is not fixing a typo but rephrasing two sentences, then the mentality of someone reviewing the PR should not be to simply say yes or no to the change, but to take it as a suggestion that ought to be thought about and possibly improved upon (with or without involvement of the original PR-creator). That is, the line of thinking should be "someone thought what was here originally could be phrased better/wasn't obvious enough about a certain aspect, why and how can we improve it?" given that his rephrasing is not satisfactory or up to quality standards. All that aside, something small like this while being helpful does not address the issues of the documentation as a whole that Adam is also tackling (layout, navigation, inter-linking(!), pages to explain idioms/commonly used concepts) and having two "official" documentations (one being experimental, I take it) is also less than helpful for navigating around and with regards to these, I would defer to Adams reasoning behind why he chose to not improve on this as opposed to starting over since I am by no means involved enough with this to have my own opinion about how difficult it is to make these types of changes.
Jan 07
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu 
wrote:
 Again this goes back to Adam.
It occurs to me, looking at the status quo, that a single point of failure is more robust than several points of failure in series. /library/ depends on the dlang.org, Phobos, and ddox. dlang.org depends on.... nobody really knows who owns it, but it seems to be you. Phobos depends on a few different people, making it the most reliable in the group, but it is still practically coupled to dmd. ddox depends on Sonke and dmd (practically). dmd depends on Walter. Any any person in that component drops the ball, the /library/ code gets stalled. The fix might get into ddox but not on the website. It might depend on something in Phobos. It might need dmd's output to change. With my system, it is all under my control. As supreme god-emperor of my domain, my server, my phobos fork, my generator, my parser fork, and my work process, yes, you'd be in a bit of trouble if I went away (though pretty soon you'll just be able to fork it yourselves in that event). But at least I'm never blocked by someone else's problems.
 Let's say we had a contributor Eve who'd gladly take emailed 
 questions and suggestions and integrate them. Would that be as 
 nice?
Poor Eve, on the other hand, would be often blocked by somebody else outside her control.
Jan 06
prev sibling parent bachmeier <no spam.com> writes:
On Tuesday, 5 January 2016 at 15:54:24 UTC, Andrei Alexandrescu 
wrote:

 The text is imprecise, e.g. an equivalent call to `sort` really 
 is `sort!((a, b) => less(transform(a), transform(b))`. All that 
 detail needn't be present in the first paragraph, so there's a 
 bit of an art in how you formulate simple sentences that are at 
 the same time correct and informative.
That explanation is better than what I had.
 The second paragraph used to be the first (and only) one. Now 
 it doesn't flow from the first one, it's jarring.
I left as much of the previous text as possible. I assumed that would create the least resistance to my changes. Thanks for the review. I will make these changes when I have a lengthy block of free time.
Jan 05
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2016-01-05 15:18, Andrei Alexandrescu wrote:

 That said, in a git-controlled directory things aren't that bad. "git
 clean -dfx" removes uncontrolled files and "git checkout" makes sure all
 files are present. Would you recommend switching to wildcards in our
 makefiles and assume people use git to keep their directories in good
 shape?
I would recommend against doing any form of cleaning. We don't want to remove untracked files that the user has added, for whatever reason. Instead "git ls-files" can be used. That will list all files tracked by git. Then of course adding wildcards, like *.d, where appropriate. Scoping to a single directory should also minimize unwanted files. -- /Jacob Carlborg
Jan 05
prev sibling next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 January 2016 at 14:18:32 UTC, Andrei Alexandrescu 
wrote:
 There's been a recent discussion with Walter and Martin about 
 using wildcards in makefiles (which would obviate the necessity 
 of being explicit about files).
I actually do NOT use wildcards in most of my own makefiles for exactly these reasons, I tend to keep dead files around. But I also list the file once and only once. There's no separate SRC, MANIFEST, DOCS, whatever. I don't even know what the difference is between each of those. However, that's for building code which is separate from building documentation. Building code needs a bit more care because it has to actually compile. Docs don't, it can make a few extra html files without lots of worry. This is one of ddoc's fundamental technical flaws, by the way, being integrated with the compiler. The compiler *needs* everything set up right to function properly. You can't compile code without the proper conditional compilation settings, for example. You can't compile a program with two main()'s. But docs are different. You don't want a function not to appear just because it is under a version(cool_feature) block. Notice I said "fundamental" rather than "fatal" because we have a workaround: the version(D_DDOC) thing. But that sucks. You now have to write the whole function prototype again to show up in the docs and if it happens to be different on the other platforms, well, you might as well just write the docs by hand. You've lost all benefits of auto-generation now. Oh yeah, and the website also has a navbar that is manually maintained, and an index page which is often neglected, probably because people don't expect to have SIX different places to add a new file! (The makefile parts, these macros, and, of course, the git add to the filesystem.) My nav bar is automatic. Click around std.socket to see what I did with it today: http://dpldocs.info/experimental-docs-2/std.socket.Socket.setOption.4.html
 to produce incomplete builds if some files are missing by 
 mistake.
That would surely be caught by the compiler itself (module file not found) or the test runner. In the case of documentation, a bunch of broken links would be detected. For druntime, the Phobos build would fail, etc.
 Would you recommend switching to wildcards in our makefiles and 
 assume people use git to keep their directories in good shape?
It'd probably work fine in git; worth an exploration. Especially for doc building which wants everything in /import, without a doubt. Phobos isn't as clear cut because it builds right from /src and has some internal files in there, but still, a wildcard that excludes the internals beats one that is wrong in the common case.
 * Each library version must be built with the same compiler 
 version. The appropriate compiler version might be missing, so 
 it needs to be downloaded, installed, and run on the side 
 without affecting any existing installation.
And this is again because everything is so strongly coupled to dmd. I'm not even convinced Phobos ought to be this closely coupled (my libs outside Phobos are compatible with at least a year of previous versions, sometimes more, and my users find this very valuable for stability against the fear of regressions), but the documentation certainly shouldn't be. With an external doc generator, you can get much broader version compatibility since it isn't responsible for actually compiling the entire language like dmd. It just needs to parse enough of it to get useful information to attach to comments, and understand just enough to attach some useful text. For example, my doc generator (built on Brian Schott's libdparse btw) knows that " safe" is worth pointing out to the user. But it doesn't need to know what it actually means. It doesn't run that level of semantic analysis and is thus isolated by changes in the safed spec. dmd doesn't have that luxury.
 My understanding is that your system does not do any of these 
 things.
I ask you to consider the importance of compromising website quality in favor of those things from a strategic viewpoint. If the pdf is really popular enough that its continuance is warranted (tbh, I can't understand why it would be, it is equivalent to or inferior to even the current website in almost every way), you should find a way to do it that doesn't hurt the main site. I certainly won't be concerning myself with it. I do care about offline viewing, and have a simple solution: I can offer a zip/tarball of the website html files. They will just work without a network connection as well. BTW: generating those other formats from html is also pretty easy and can be done after the fact.
 The script 
 https://github.com/D-Programming-Language/dlang.org/blob/master/posix.mak
stands at 498 lines. What ways there are to make it considerably simpler and
smaller?
I've looked at this before and didn't even understand what it is trying to do, much less why it is doing that. I don't feel comfortable modifying code that I don't understand. And frankly, I have zero interest in dealing with complicated build systems. My view is if they aren't nearly invisible, they have failed me. And I deal with failing subordinates in a similar manner to Darth Vader: https://www.youtube.com/watch?v=aV2DLkDPwM8&feature=youtu.be&t=33s
 Indeed the web forms sound like a great idea. Would you want to 
 work on such for the mainline website as well? It's not a 
 contest; the better everything is, the better off everybody is.
It's not the web form that's difficult though, it is getting the new file integrated with the build and actually running it. The existing site makes that exceedingly difficult.
 Nice. What could we do in ddoc and ddox to have a similar 
 improvement?
I implemented it as a magic macro, they could do the same. This kind of expansion cannot be implemented as a ddoc macro itself because it needs more info than text expansion (and mine has an if statement if name lookup fails), but it is fairly easy to express in D.
 How do you envision scaling it up as the system becomes more 
 successful and you get more requests than you can handle 
 reasonably quick?
I'll cross that bridge when I get to it. Let's not let tomorrow's potential hurdle be today's showstopper.
 Would you be willing to set up such a system for dlang.org as 
 well? It would be absolutely fantastic.
People can (and often do) email me all kinds of things. But I'm not the god-emperor of dlang.org so what I can easily do there is limited.
 Anyone could do the same today for all pull requests - just 
 fetch them, fix them, and resubmit with credit. Additionally, 
 team members could just pull the PR, fix it, and make an 
 additional commit.
Indeed, that's not a technical barrier. But it is a cultural barrier - the D PR process (which btw is strongly encouraged by the GitHub UI, it isn't just us) has more emphasis on leaving comments than on fixing it yourself.
 I'll note that you are already a member of that team so you 
 already had the rights to exact quite a few of the improvements 
 you intend to make going forward. Would you please join me in 
 taking a look at older PRs (oldest is from 2014) and pull them 
 in?
The technical access and the feeling of ownership are two different things. If you gave me a key to your house, would it be fine for me to do in some day when you're not home and start remodeling it? That's the problem with the "lieutenant" thing that's been discussed before. Lieutenants are junior officers who just keep things running according to regulation while the captain is busy elsewhere. If anything extraordinary happens, they report it up the chain of command. What we need is a greater amount of delegation. Lieutenant-generals perhaps: individuals who have full authorization and broad autonomy to run an entire sector of operations as they see fit.
 Overall my understanding of your message is "My system would be 
 better not for a fundamental technical reason, but because I am 
 willing to pour in it time and talent." This is the kind of 
 argument I have a lot of respect for.
Well, there are technical reasons too. Tying ddoc to dmd was a short-term win, it got to reuse the compiler to do hard work at a time when there were no realistic alternatives. But, today, it is limiting. Sharing code with the compiler means ddoc is subject to the compiler's trade-offs.... which, given a choice that strengthens code or strengths docs, code is going to win every time. As it should, that's the compiler's job. Moving ddoc to a separate path will result in code duplication at best, so at that point, you don't gain much from staying in dmd anymore. Ddoc's text macro system, while an elegant implementation and good enough for many things, is also a fundamentally limiting factor (and now tied up a bit due to backward-compatibility with arbitrary user-defined extensions), and prone to complications. It puts a limit on how much analysis of the source text we can realistically do because anything could expand to anything else. It is a mistake. (The missing word there btw is $1, disappeared because ddoc mistakes it for syntax and just erases it. Seriously, try it.) Ddoc's total failure to understand what it is generating means it cannot automatically link. And since it lacks conditionals, you can't even program it to link to user-defined things. (And no, I am not suggesting we add $(IF). We don't need yet another programming language... nobody wants to write their documentation in uncommon Lisp. We want it to just work.) Fixing these will mean breaking backward compatibility. If you're willing to do that, great! I've been writing a ddoc 2.0 generator :P
Jan 05
parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-06 05:29, Adam D. Ruppe wrote:

 I actually do NOT use wildcards in most of my own makefiles for exactly
 these reasons, I tend to keep dead files around.
"git ls-files" should take care of that. -- /Jacob Carlborg
Jan 06
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/06/2016 07:27 AM, Jacob Carlborg wrote:
 On 2016-01-06 05:29, Adam D. Ruppe wrote:

 I actually do NOT use wildcards in most of my own makefiles for exactly
 these reasons, I tend to keep dead files around.
"git ls-files" should take care of that.
Thanks, Jacob I think this is a great idea. If anyone would like to initiate replacing some uses of file lists with git ls-files, please go ahead. And it should work on Windows, too. The remaining issue is that that makes the makefile assume git is installed. Is that reasonable? Andrei
Jan 06
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2016-01-06 17:37, Andrei Alexandrescu wrote:

 The remaining issue is that that makes the makefile assume git is
 installed. Is that reasonable?
I think so at least. -- /Jacob Carlborg
Jan 06
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 6 January 2016 at 16:37:24 UTC, Andrei Alexandrescu 
wrote:
 The remaining issue is that that makes the makefile assume git 
 is installed. Is that reasonable?
I hate to be the one to say this, but I don't think it is reasonable in the packaged release. In the dev version, absolutely, but the packaged release is not a git repository, but still includes the makefile... However, let's not let the release compromise the development. The release generation script can run git ls-files itself and do some string replacement in the relevant files.
Jan 06
prev sibling next sibling parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 5 January 2016 at 14:18:32 UTC, Andrei Alexandrescu 
wrote:
 Regarding PRs that are not looked at, we currently have 18 PRs 
 at https://github.com/D-Programming-Language/dlang.org/pulls, 
 and 16 folks who have the rights to pull them 
 (https://github.com/orgs/D-Programming-Language/teams/team-dlang-org). I'll
take a look at them after this (some look really trivial); it's a bummer they
aren't looked at more regularly.
I'm usually subscribed to the dlang.org GitHub repo and merge PRs or work with PR contributors into getting their PR into merge-able state. However, I'm currently abroad so not very responsive. PRs which affect the language specification are labeled as such and need to be reviewed/merged by someone more familiar with the subject, though. I'll throw another idea into the discussion based on the potatoes from my side of the table. Digger can already build the website documentation with one command, albeit only on Posix. How would it sound to expand that to Windows, and to make it easier to contribute to D via Digger without having to touch Git (e.g. using a new "digger pull-request" command)? This would only make sense if Digger was promoted as a primary means of building D, rather than one of the alternatives / last-resorts as it is currently.
Jan 05
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-05 15:18, Andrei Alexandrescu wrote:

 There's been a recent discussion with Walter and Martin about using
 wildcards in makefiles (which would obviate the necessity of being
 explicit about files).

 My understanding is that build scripts (including makefiles) are
 recommended to include a manifest list of files that are part of the
 project, as opposed to picking up files with wildcards. That way there's
 less likelihood to pick up litter along with the legitimate files, or to
 produce incomplete builds if some files are missing by mistake. The
 underlying thesis is that that's a good kind of redundancy.
druntime already uses wildcards [1], if I read the makefile correctly, in some places. [1] https://github.com/D-Programming-Language/druntime/blob/master/posix.mak#L147-L159 -- /Jacob Carlborg
Jan 06
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 01/06/2016 08:50 AM, Jacob Carlborg wrote:
 druntime already uses wildcards [1], if I read the makefile correctly,
 in some places.
Yes, it recently caused Walter some headache because he had a stray file. I think your git ls-files idea would work a lot better. -- Andrei
Jan 06
prev sibling next sibling parent reply =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Monday, 28 December 2015 at 20:15:30 UTC, Adam D. Ruppe wrote:
 Last week, I posted in the general forum my dream for better D 
 docs. Today, about 4 days of work later, I'm about 1/4 of the 
 way there.

 Still a long way to go, but I've already come so far.

 First, behold my old dpldocs.info site. Yes, it is still up and 
 now it ties into my new docs! You can use it to quickly jump to 
 a doc given its name:

 http://dpldocs.info/
This is awesome! I warmly welcome this approach. I just got a comment from a newbie D developer fellow who commented on the current unpleasant doc formatting of templated headers.
Jan 05
parent reply =?UTF-8?B?Tm9yZGzDtnc=?= <per.nordlow gmail.com> writes:
On Tuesday, 5 January 2016 at 15:43:30 UTC, Nordlöw wrote:
 This is awesome! I warmly welcome this approach. I just got a 
 comment from a newbie D developer fellow who commented on the 
 current unpleasant doc formatting of templated headers.
The mouse-over behaviour of CT- and RT-parameters is just really really cool! Thanks!
Jan 05
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 5 January 2016 at 15:51:56 UTC, Nordlöw wrote:
 The mouse-over behaviour of CT- and RT-parameters is just 
 really really cool! Thanks!
Awesome! That's just a little javascript but I feel it kinda adds a fourth dimension (the other three being width, height, and *color* on a website) that we can utilize. Now that my refactor is almost complete, I'll be able to make this smarter too. The current highlighting is done by the javascript plus the code formatter, of all things, which is the wrong level to do smart lookups. Now that I have clean classes instead of spaghetti strings, the next steps are open to me! On the listing, I'm using "simplified" prototypes and on the details page, I can start filling in the clickable things and recognize constraint patterns to translate them too.
Jan 05
prev sibling next sibling parent reply Martin Nowak <code dawg.eu> writes:
On Monday, 28 December 2015 at 20:15:30 UTC, Adam D. Ruppe wrote:
 http://dpldocs.info/findSkip
We already have a nice and powerful documentation generator called ddox. https://github.com/rejectedsoftware/ddox It also contains an experimental libdparse based input (rather than relying on dmd's json ouput). It is flexible enough to be templated/styled very differently, see https://dlang.org/library/index.html, https://vibed.org/api/, https://github.com/MartinNowak/scod (martinnowak.github.io/bloom/bloom.html). Its behavior can be customized, the project is actively maintained, ddox compatible tools can easily be integrated with dub, and whatever you want to change for template constraints should be easy to achieve.
Jan 06
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 6 January 2016 at 10:25:50 UTC, Martin Nowak wrote:
 We already have a nice and powerful documentation generator 
 called ddox.
You say that like I've never hard of it before, when I've spent quite a few words over the last ten days writing up my critiques of it, including both bugs and questioning its fundamental approach. I guess I'll write more about it. I really wish you guys would actually read the arguments you're replying to though before posting. This is very frustrating and contrary to popular belief, I'm not a saint with infinite patience.
 https://github.com/rejectedsoftware/ddox
 It also contains an experimental libdparse based input (rather 
 than relying on dmd's json ouput).
I confess I didn't actually know it had that (it has zero mention... anywhere outside the source)... though the fact that it is there actually strengthens my position! Look at the ddox issues list, marked external. Those are from dmd... but they aren't all bugs. The JSON isn't just for docs, and when there's a trade off between doc and whatever else people use the json for, the doc side often loses. e.g.: https://github.com/rejectedsoftware/ddox/issues/19 Apparently, the ddox team agrees with me that being wed to dmd is a flawed approach. Though, looking at its source, it doesn't actually use libdparse for much beyond the basics - just getting enough to feed into the existing core, which reflects its preference for the inferior json, and it appears to be stalled there. It is still limited by its initial decision of going down the dmd route.
 It is flexible enough to be templated/styled very differently
That's trivial. Even the worst html file is flexible enough to be templated/styled very differently because that's part of html's core nature.
 the project is actively maintained
With about 1/3 of its github bugs still open, including about half its open bugs more than one year old. About half its D bugzilla bugs are still open, including ones over 2 1/2 years old. I know projects get bugs open when they are used, but ddox is a one-person project and that one person doesn't seem terribly active in it. https://github.com/rejectedsoftware/ddox/graphs/contributors Looking at the bug list, lol: https://issues.dlang.org/show_bug.cgi?id=14608 It was open for six months without so much as a comment. The thing Andrei is asking for and Sonke agrees is a good model... is exactly the way I did mine the first time. http://dpldocs.info/experimental-docs-2/std.algorithm.searching.OpenRight.html And yes, yes, I'm sure if I spent 60 hours on ddox over this Christmas instead of on my new system, some of those bugs would be closed. But I betcha I would have hit some annoying wall and instead spent the time on my paying job or something (I do have a big tax bill looming and probably should be doing paying work!), so that's all hypothetical. And when I did open a pull request, it'd probably sit there for over two months without comment like the other ones that are open right now. I'd have to fork the site anyway to get any changes live!
 ddox compatible tools can easily be integrated with dub, and 
 whatever you want to change for template constraints should be 
 easy to achieve.
The template constraint formatting is just the beginning.
Jan 06
parent reply Martin Nowak <code dawg.eu> writes:
On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:
 I know projects get bugs open when they are used, but ddox is a 
 one-person project and that one person doesn't seem terribly 
 active in it.
I'm another user of ddox and fix things when they annoy me. I don't have many problems with it though. It you'd joined we'd already be 3.
 https://github.com/rejectedsoftware/ddox/graphs/contributors
The main reasons why work has stalled is that the future of dpl-docs is unclear. Instead of fixing the remaining issues w/ ddox people have spend a huge amount of time to improve ddoc output, so b/c of this weird course Söhnke stopped working on dpl-docs for now. The other reason is that the existing tool already does most things you want from a documentation system. The styling sucked so I wrote scod, but most of the remaining issues are minor problems that will eventually be addressed. And even if you don't agree w/ some aspect of it, working on a common documentation engine/library makes more sense than having everyone write it's own, in particular if you're arguing about limited time.
Jan 06
next sibling parent reply Rory McGuire via Digitalmars-d-announce writes:
On Wed, Jan 6, 2016 at 10:01 PM, Martin Nowak via Digitalmars-d-announce <
digitalmars-d-announce puremagic.com> wrote:

 On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:

 I know projects get bugs open when they are used, but ddox is a
 one-person project and that one person doesn't seem terribly active in i=
t.

 I'm another user of ddox and fix things when they annoy me.
 I don't have many problems with it though.
 It you'd joined we'd already be 3.

 https://github.com/rejectedsoftware/ddox/graphs/contributors

 The main reasons why work has stalled is that the future of dpl-docs is
 unclear. Instead of fixing the remaining issues w/ ddox people have spend=
a
 huge amount of time to improve ddoc output, so b/c of this weird course
 S=C3=B6hnke stopped working on dpl-docs for now.
 The other reason is that the existing tool already does most things you
 want from a documentation system. The styling sucked so I wrote scod, but
 most of the remaining issues are minor problems that will eventually be
 addressed. And even if you don't agree w/ some aspect of it, working on a
 common documentation engine/library makes more sense than having everyone
 write it's own, in particular if you're arguing about limited time.
I like our current documentation. The only real barrier to entry for non D devs is the weird symbols names we've used for the standard library. They are good names, but they are "sciency". It would be great if people could "tag" symbols in the current documentation website. That way anyone could put things like "go:Dial" in the tags for Socket's " safe this(Address connectTo);" and "js:contains" in the tags for canFind(). All the symbols in std.algorithm.setops could use some less "sciency" tags. If not a tagging system then at least adding synonyms would be great. The documentation on Google Developers is excellent for api discovery, our docs are quite similar I think. (In our company even sales and lead gen use the Google Developers docs to check if something is possible.
Jan 06
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 7 January 2016 at 06:30:28 UTC, Rory McGuire wrote:
 If not a tagging system then at least adding synonyms would be 
 great.
dpldocs.info actually had this in its first version, way back in 2010, because so many people would ask me these kinds of things. In the first draft, I did it as a separate database. In the new one, I will add a "Tags:" section to my ddoc parser that will figure them all out. The search engine will use it definitely, and perhaps the See Also referencer too, though I'm not sure about how that'd look. I need to flesh things out a bit more. I'm also thinking about adding a "category" thing too but submodules or aggregates in the source code are usually better there, so I'll probably stop at tags. In the ddoc source code, the section would look like: /++ Some explanation See_Also: * $(REF indexOf) * $(REF findSplit) Tags: contains, in +/ .... canFind()... That is, the tags is just a comma-separated list of keywords in the source.
Jan 07
prev sibling parent reply Rory McGuire via Digitalmars-d-announce writes:
I wonder; would it be possible to make the website inline editable and then
it automatically creates github pull requests that update the docs in
github as D comments?

On Thu, Jan 7, 2016 at 8:30 AM, Rory McGuire <rjmcguire gmail.com> wrote:

 On Wed, Jan 6, 2016 at 10:01 PM, Martin Nowak via Digitalmars-d-announce =
<
 digitalmars-d-announce puremagic.com> wrote:

 On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:

 I know projects get bugs open when they are used, but ddox is a
 one-person project and that one person doesn't seem terribly active in =
it.

 I'm another user of ddox and fix things when they annoy me.
 I don't have many problems with it though.
 It you'd joined we'd already be 3.

 https://github.com/rejectedsoftware/ddox/graphs/contributors

 The main reasons why work has stalled is that the future of dpl-docs is
 unclear. Instead of fixing the remaining issues w/ ddox people have spen=
d a
 huge amount of time to improve ddoc output, so b/c of this weird course
 S=C3=B6hnke stopped working on dpl-docs for now.
 The other reason is that the existing tool already does most things you
 want from a documentation system. The styling sucked so I wrote scod, bu=
t
 most of the remaining issues are minor problems that will eventually be
 addressed. And even if you don't agree w/ some aspect of it, working on =
a
 common documentation engine/library makes more sense than having everyon=
e
 write it's own, in particular if you're arguing about limited time.
I like our current documentation. The only real barrier to entry for non =
D
 devs is the weird symbols names we've used for the standard library. They
 are good names, but they are "sciency". It would be great if people could
 "tag" symbols in the current documentation website. That way anyone could
 put things like "go:Dial" in the tags for Socket's " safe this(Address
 connectTo);" and "js:contains" in the tags for canFind(). All the symbols
 in std.algorithm.setops could use some less "sciency" tags.

 If not a tagging system then at least adding synonyms would be great.

 The documentation on Google Developers is excellent for api discovery, ou=
r
 docs are quite similar I think. (In our company even sales and lead gen u=
se
 the Google Developers docs to check if something is possible.
Jan 06
next sibling parent Sebastiaan Koppe <mail skoppe.eu> writes:
On Thursday, 7 January 2016 at 07:14:01 UTC, Rory McGuire wrote:
 I wonder; would it be possible to make the website inline 
 editable and then it automatically creates github pull requests 
 that update the docs in github as D comments?
That is a cool idea. The hard part is backtracking elements in the html so you know what line of code generated that markup. You could infer it from surrounding elements but that will be hairy and brittle. Better to have ddoc emit file and line numbers in the html (as comments or ids or data-attributes, etc.). Also you would need to know on what commit to base the changes on.
Jan 07
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/16 2:14 AM, Rory McGuire via Digitalmars-d-announce wrote:
 I wonder; would it be possible to make the website inline editable and
 then it automatically creates github pull requests that update the docs
 in github as D comments?
Ha. I just posted about that! -- Andrei
Jan 07
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-28 21:15, Adam D. Ruppe wrote:
 Last week, I posted in the general forum my dream for better D docs.
 Today, about 4 days of work later, I'm about 1/4 of the way there.

 Still a long way to go, but I've already come so far.

 First, behold my old dpldocs.info site. Yes, it is still up and now it
 ties into my new docs! You can use it to quickly jump to a doc given its
 name:

 http://dpldocs.info/
BTW, do you know of Harbored [1] and a fork of it [2]? It's documentation generator for D by Brian that uses libdparse. [1] https://github.com/economicmodeling/harbored [2] https://github.com/kiith-sa/harbored-mod -- /Jacob Carlborg
Jan 06
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 6 January 2016 at 17:10:01 UTC, Jacob Carlborg 
wrote:
 BTW, do you know of Harbored [1]
Yes, I wrote about it in the TWiD link in the snipped section of the parent post. In fact, until Monday, my generator actually imported a few modules directly from Harbored to handle things like documented unittests and attributes listing. (I have since refactored it, which happened to remove that dependency. That actually wasn't my goal; it was just a nice side effect of the simplified code. I still use the copy/pasted attributes code from harbored though, and still give Brian Schott huge credit for making my thing possible.)
 and a fork of it [2]?
I did not know about that fork though. Looking at it, it falls in the same category to me though: good, but not great. I want something great.
Jan 06
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Just want to update y'all that my better docs continue to improve 
with each passing week.

I just did a style facelift on the members section:

http://dpldocs.info/experimental-docs/std.algorithm.setops.html

(and yes, that's mostly css style! I did a minor change to the 
html, you can see the old here: 
http://dpldocs.info/experimental-docs/std.stdio.html (well, at 
least until I rebuild the docs of all of Phobos again), but the 
css is the big thing. It is nice having semantic markup.)


So I hope that is more readable. The sidebar is also new over the 
last couple weeks, giving a sorted list of sibling names - 
including package listings.

If you go into a thing: 
http://dpldocs.info/experimental-docs/std.stdio.write.html you 
can see how the sidebar shows the immediate siblings only, which 
makes the list a lot more managable than trying to cram 
everything everywhere. I find the Phobos official sidebar to be 
useless because there's just too much there.

BTW the recent push that makes constraints small and grey, check 
this out for example:

http://dlang.org/phobos/std_algorithm_sorting.html#completeSort

I feel is no help. The readability is still poor and it doesn't 
help with navigation. In my new members thing, I used a small, 
hoverable prototype... but just on the index. Once you click 
through, I still have the full details, formatted for legibility.

This reform is not appeasing my revolution....



Anyway, I feel that this is really starting to come together 
now... pretty soon, I'll promote it to "alpha" from its current 
state of "pre-alpha". Just gotta write the new search engine 
first!
Jan 30
next sibling parent reply Chris Wright <dhasenan gmail.com> writes:
On Sat, 30 Jan 2016 20:58:44 +0000, Adam D. Ruppe wrote:

 Just want to update y'all that my better docs continue to improve with
 each passing week.
 
 I just did a style facelift on the members section:
 
 http://dpldocs.info/experimental-docs/std.algorithm.setops.html
Oh god, that's lovely. It works even with outrageously strict security policies in the browser. You probably know about this, but some of the source code formatting is a little off (and allowing javascript / cross-site requests doesn't help). Example: http://ikeran.org/images/std.range.enumerate.png The initial part is more readable than the original source code, but the in contract is a bit messy. Even with that, this is a lot easier and more approachable than the dlang.org docs. Thanks!
Jan 30
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 30 January 2016 at 21:22:02 UTC, Chris Wright wrote:
 You probably know about this, but some of the source code 
 formatting is a
 little off (and allowing javascript / cross-site requests 
 doesn't help).
Right, the contract formatter is something I started a while ago but not finished yet. And actually, a lot of the contracts are ugly anyway, even if nicely formatted (that is, the code is more implementation-focused than presentable as documentation), so I'm not sure trying to print them is actually a good idea. This is the original source of your picture: in { static if (hasLength!Range) { // TODO: core.checkedint supports mixed signedness yet? import core.checkedint : adds, addu; import std.conv : ConvException, to; alias LengthType = typeof(range.length); bool overflow; static if(isSigned!Enumerator && isSigned!LengthType) auto result = adds(start, range.length, overflow); else static if(isSigned!Enumerator) { Largest!(Enumerator, Signed!LengthType) signedLength; try signedLength = to!(typeof(signedLength))(range.length); catch(ConvException) overflow = true; catch(Exception) assert(false); auto result = adds(start, signedLength, overflow); } else { static if(isSigned!LengthType) assert(range.length >= 0); auto result = addu(start, range.length, overflow); } assert(!overflow && result <= Enumerator.max); } } It is certainly nicer when correctly formatted... but still, what is that actually saying?
 The initial part is more readable than the original source 
 code, but the in contract is  a bit messy.
aye, that's where I spent all the time.
 Even with that, this is a lot easier and more approachable than 
 the dlang.org docs. Thanks!
awesome
Jan 30
prev sibling next sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Saturday, 30 January 2016 at 20:58:44 UTC, Adam D. Ruppe wrote:
 In my new members thing, I used a small, hoverable prototype...
Nice. Slight layout problem: when the browser width is set less than the max line width, hovering will add a white bar to the right of the page, maybe 20px wide. It doesn't show, but it makes a horizontal slider appear. It disappears on focus-out. The horizontal slider also causes a resize on the vertical slider, so it is quite a nervous flicker when moving the mouse across the page. Safari 9.0.3.
Jan 30
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 30 January 2016 at 22:08:55 UTC, Bastiaan Veelo 
wrote:
 Nice. Slight layout problem: when the browser width is set less 
 than the max line width, hovering will add a white bar to the 
 right of the page, maybe 20px wide.
Yeah, I know. I want it to be the width of the container's container, but don't know how to express that in CSS. So the document layout is basically: <dl> <dt> <a>name</a> <div>prototype</div> </dt> <dd> description </dd> </dl> The dt has a fixed width set to a fraction of the dl. The dl is a normal block element. The prototype is normally clipped to the width of the dt, but on hover, I want it to break free and take the width of the dl, while staying in the same place otherwise. I know quite a few css tricks... but I don't think I can actually do this without adding a script or something, so I just put an arbitrary fixed width on hover for now.
Jan 30
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 30 January 2016 at 22:37:18 UTC, Adam D. Ruppe wrote:
 I know quite a few css tricks... but I don't think I can 
 actually do this without adding a script or something, so I 
 just put an arbitrary fixed width on hover for now.
Meh, I just did it with JavaScript, so if you enable script, you should be free of that now (and if not, the fixed width fallback is still there.) (specifically, the script just edits the html of a special dynamic <style> element)
Jan 30
prev sibling parent reply Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
On Saturday, 30 January 2016 at 22:37:18 UTC, Adam D. Ruppe wrote:
 I know quite a few css tricks... but I don't think I can 
 actually do this without adding a script or something, so I 
 just put an arbitrary fixed width on hover for now.
One trick is to set the width and clipping on "dt > *" instead of "dt", and use "calc(...)" for dynamic sizes.
Jan 30
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 31 January 2016 at 07:40:49 UTC, Ola Fosheim Grøstad 
wrote:
 One trick is to set the width and clipping on "dt > *" instead 
 of "dt", and use "calc(...)" for dynamic sizes.
I considered that too, but since I wanted the dt to float, the width had to be set there.
Jan 31
prev sibling next sibling parent reply Rory McGuire via Digitalmars-d-announce writes:
On Sat, Jan 30, 2016 at 10:58 PM, Adam D. Ruppe via Digitalmars-d-announce <
digitalmars-d-announce puremagic.com> wrote:

 Just want to update y'all that my better docs continue to improve with
 each passing week.

 I just did a style facelift on the members section:

 http://dpldocs.info/experimental-docs/std.algorithm.setops.html

 (and yes, that's mostly css style! I did a minor change to the html, you
 can see the old here: http://dpldocs.info/experimental-docs/std.stdio.html
 (well, at least until I rebuild the docs of all of Phobos again), but the
 css is the big thing. It is nice having semantic markup.)


 So I hope that is more readable. The sidebar is also new over the last
 couple weeks, giving a sorted list of sibling names - including package
 listings.

 If you go into a thing:
 http://dpldocs.info/experimental-docs/std.stdio.write.html you can see
 how the sidebar shows the immediate siblings only, which makes the list a
 lot more managable than trying to cram everything everywhere. I find the
 Phobos official sidebar to be useless because there's just too much there.

 BTW the recent push that makes constraints small and grey, check this out
 for example:

 http://dlang.org/phobos/std_algorithm_sorting.html#completeSort

 I feel is no help. The readability is still poor and it doesn't help with
 navigation. In my new members thing, I used a small, hoverable prototype...
 but just on the index. Once you click through, I still have the full
 details, formatted for legibility.

 This reform is not appeasing my revolution....



 Anyway, I feel that this is really starting to come together now... pretty
 soon, I'll promote it to "alpha" from its current state of "pre-alpha".
 Just gotta write the new search engine first!
If you don't get a cease and desist letter from the D Foundation soon I'd be surprised. Your matter of fact insulting of our official docs (which are leaps and bounds better than the new stuff you are making) is destructive to our community. Having a different kind of search and having a different layout that is more succinct is "Super Awesome" and you are doing it, but you have absolutely no reason to constantly insult the work on the main site. _Creating division in such a small community is not helpful_. Having competing designs can be very helpful, (e.g. your layout could be nice for Google search results), official docs are nice because you don't have to constantly jump around the site while working.
Jan 31
next sibling parent reply Chris Wright <dhasenan gmail.com> writes:
On Sun, 31 Jan 2016 13:14:08 +0200, Rory McGuire via
Digitalmars-d-announce wrote:

 If you don't get a cease and desist letter from the D Foundation soon
 I'd be surprised.
A cease and desist for making Boost-licensed documentation available in another medium. Kind of violates the spirit of being an open source project, no? The only grounds potentially available for a C&D letter are based in trademarks. For the D Foundation to succeed with this sort of thing in general, they'd need to start an explicit trademark licensing system and assiduously go after people who use the trademark without a license. (Non- enforcement is grounds for losing trademark status.) That's probably not going to happen. Too much work and too much negative publicity. And you appear to be recommending this as a punitive measure for comments in another forum. Can you imagine the reaction? Every time anyone posted an article about D, the comments would be full of "hope you don't get sued". You're issuing a threat that you have no standing to fulfill, where those who do have standing have every incentive not to fulfill it and no particular reason to listen to you.
 Your matter of fact insulting of our official docs
 (which are leaps and bounds better than the new stuff you are making) is
 destructive to our community.
I've seen far nastier comments than Adam Ruppe's on this forum (it's a huge stretch to call his "nasty"), and nastier than yours, and unproductive to boot, and nobody objected to them. Seeing a person threatening someone for trying to help and providing specific feedback, while worse goes unnoted, is demoralizing and probably worse for the community.
 Having a different kind of search and having a different layout that is
 more succinct is "Super Awesome" and you are doing it, but you have
 absolutely no reason to constantly insult the work on the main site.
 
 _Creating division in such a small community is not helpful_.
It's not a division. It's a documentation mirror with a different layout.
 Having
 competing designs can be very helpful, (e.g. your layout could be nice
 for Google search results), official docs are nice because you don't
 have to constantly jump around the site while working.
There's pretty much no advantage to having three hundred declarations on the same page with no cross-references and only top-level declarations indexed. Cross-references plus all-in-one-page might be okay, but then you'd be comparing Adam Ruppe's work with a hypothetical evolution of dlang.org docs.
 <div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sat,
Please, disable HTML mail for this list.
Jan 31
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 31 January 2016 at 17:54:41 UTC, Chris Wright wrote:
 It's not a division. It's a documentation mirror with a 
 different layout.
Well, there are a few content changes too. You can see my diff as it develops here: https://github.com/D-Programming-Language/phobos/pull/3895 (I'll rebase and squash commits and all that jazz some other time. I'm editing files as I notice problems or opportunities for improvement, so it is kinda random rather than a thematic set of atomic changes.) I'm also working on writing wholly original articles and tutorials to link throughout. Lastly, the site also includes docs for several of my libraries (e.g. http://dpldocs.info/experimental-docs/simpledisplay.html or http://dpldocs.info/experimental-docs/arsd.cgi.html, and I plan to open it up to third party projects as well (maybe even automatically scraping code.dlang.org), so everything can be searched in one place. So it is a bit more than just a mirror with a new layout :)
Jan 31
prev sibling parent reply Rory McGuire via Digitalmars-d-announce writes:
On Sun, Jan 31, 2016 at 7:54 PM, Chris Wright via
Digitalmars-d-announce <digitalmars-d-announce puremagic.com> wrote:
 On Sun, 31 Jan 2016 13:14:08 +0200, Rory McGuire via
 Digitalmars-d-announce wrote:

 If you don't get a cease and desist letter from the D Foundation soon
 I'd be surprised.
A cease and desist for making Boost-licensed documentation available in another medium. Kind of violates the spirit of being an open source project, no? The only grounds potentially available for a C&D letter are based in trademarks. For the D Foundation to succeed with this sort of thing in general, they'd need to start an explicit trademark licensing system and assiduously go after people who use the trademark without a license. (Non- enforcement is grounds for losing trademark status.) That's probably not going to happen. Too much work and too much negative publicity. And you appear to be recommending this as a punitive measure for comments in another forum. Can you imagine the reaction? Every time anyone posted an article about D, the comments would be full of "hope you don't get sued".
The problem is the D logo etc at the top of his docs mixed with Adam's resentment. Your email validates what I was suggesting he should avoid.
 You're issuing a threat that you have no standing to fulfill, where those
 who do have standing have every incentive not to fulfill it and no
 particular reason to listen to you.

 Your matter of fact insulting of our official docs
 (which are leaps and bounds better than the new stuff you are making) is
 destructive to our community.
I've seen far nastier comments than Adam Ruppe's on this forum (it's a huge stretch to call his "nasty"), and nastier than yours, and unproductive to boot, and nobody objected to them. Seeing a person threatening someone for trying to help and providing specific feedback, while worse goes unnoted, is demoralizing and probably worse for the community.
 Having a different kind of search and having a different layout that is
 more succinct is "Super Awesome" and you are doing it, but you have
 absolutely no reason to constantly insult the work on the main site.

 _Creating division in such a small community is not helpful_.
It's not a division. It's a documentation mirror with a different layout.
Did you read my mail at all?
 Having
 competing designs can be very helpful, (e.g. your layout could be nice
 for Google search results), official docs are nice because you don't
 have to constantly jump around the site while working.
There's pretty much no advantage to having three hundred declarations on the same page with no cross-references and only top-level declarations indexed.
 Cross-references plus all-in-one-page might be okay, but then you'd be
 comparing Adam Ruppe's work with a hypothetical evolution of dlang.org
 docs.

 <div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sat,
Please, disable HTML mail for this list.
Feb 01
parent reply Chris Wright <dhasenan gmail.com> writes:
On Mon, 01 Feb 2016 10:03:25 +0200, Rory McGuire via
Digitalmars-d-announce wrote:

 The problem is the D logo etc at the top of his docs mixed with Adam's
 resentment. Your email validates what I was suggesting he should avoid.
My newsreader's history doesn't support your memory of events. The problem you cited was "insulting our official docs" and (nonexistent) community splits resulting from the insults. Your predicted / recommended response to that problem was "a cease and desist letter from the D Foundation". There's no evidence that you considered trademark issues at all until I brought them up. If I'd cited copyright infringement instead, I'm betting you would have jumped on that, even though the docs are Boost-licensed. What I would actually expect, instead of a C&D letter, is a set of guidelines for using the D logo and other trademarked material. That's pretty standard for open source projects. And if those guidelines forbad using the D logo for a documentation mirror, that would be a problem. An airtight set of guidelines probably requires a trademark lawyer, which probably costs more than the D Foundation has in its coffers. We might see a preliminary set of guidelines coming out in the next year or so. I don't see how a criticism of the official documentation (even one you believe is insulting) fragments the community. Most people around here think D's documentation is a problem. Adam Ruppe provided both specific feedback and an implemented alternative, which is much more constructive than average. He's got a pull request for content changes that he's made, too, which is the opposite of fragmentation.
Feb 01
next sibling parent reply Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
On Monday, 1 February 2016 at 20:01:11 UTC, Chris Wright wrote:
 What I would actually expect, instead of a C&D letter, is a set 
 of guidelines for using the D logo and other trademarked 
 material. That's pretty standard for open source projects. And 
 if those guidelines forbad using the D logo for a documentation 
 mirror, that would be a problem.
The last time this was discussed it came up that the creator of the logo has not transferred the rights, so you would have to ask the creator of the logo for usage that goes beyond the website. Unless this has changed there is no way for "D Foundation" to register the design as a trademark. And the letter "D" itself cannot be used as a trademark, so if you want to trademark a "D" logo it has to be very specific.
Feb 01
parent Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
On Monday, 1 February 2016 at 20:14:42 UTC, Ola Fosheim Grøstad 
wrote:
 On Monday, 1 February 2016 at 20:01:11 UTC, Chris Wright wrote:
 What I would actually expect, instead of a C&D letter, is a 
 set of guidelines for using the D logo and other trademarked 
 material. That's pretty standard for open source projects. And 
 if those guidelines forbad using the D logo for a 
 documentation mirror, that would be a problem.
The last time this was discussed it came up that the creator of the logo has not transferred the rights, so you would have to ask the creator of the logo for usage that goes beyond the website. Unless this has changed there is no way for "D Foundation" to register the design as a trademark. And the letter "D" itself cannot be used as a trademark, so if you want to trademark a "D" logo it has to be very specific.
Here is the relevant link: http://media.sukimashita.com/d/ Please note: «The following pictures are ideas for different styles as an effort to create a common logo for the D programming language community.» «COPYRIGHT © SUKIMASHITA 2006 ALL FREE TO USE. ONLY SELLING THESE IMAGES IS PROHIBITED.» So clearly, Adam and anyone else can use these images, at least unmodified. The version he is using is a derived work so he probably should clear that with the original author.
Feb 01
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 1 February 2016 at 20:01:11 UTC, Chris Wright wrote:
 My newsreader's history doesn't support your memory of events.
I don't think this is worth arguing over...
Feb 01
prev sibling parent Rory McGuire via Digitalmars-d-announce writes:
On Mon, Feb 1, 2016 at 10:01 PM, Chris Wright via
Digitalmars-d-announce <digitalmars-d-announce puremagic.com> wrote:
 On Mon, 01 Feb 2016 10:03:25 +0200, Rory McGuire via
 Digitalmars-d-announce wrote:

 The problem is the D logo etc at the top of his docs mixed with Adam's
 resentment. Your email validates what I was suggesting he should avoid.
My newsreader's history doesn't support your memory of events. The problem you cited was "insulting our official docs" and (nonexistent) community splits resulting from the insults. Your predicted / recommended response to that problem was "a cease and desist letter from the D Foundation". There's no evidence that you considered trademark issues at all until I brought them up. If I'd cited copyright infringement instead, I'm betting you would have jumped on that, even though the docs are Boost-licensed.
Are you trying to understand me, or alienate me? I'm unsure what your motivation is for undermining my trying to explain myself in more words.
 What I would actually expect, instead of a C&D letter, is a set of
 guidelines for using the D logo and other trademarked material. That's
 pretty standard for open source projects. And if those guidelines forbad
 using the D logo for a documentation mirror, that would be a problem.

 An airtight set of guidelines probably requires a trademark lawyer, which
 probably costs more than the D Foundation has in its coffers. We might
 see a preliminary set of guidelines coming out in the next year or so.

 I don't see how a criticism of the official documentation (even one you
 believe is insulting) fragments the community. Most people around here
 think D's documentation is a problem. Adam Ruppe provided both specific
 feedback and an implemented alternative, which is much more constructive
 than average. He's got a pull request for content changes that he's made,
 too, which is the opposite of fragmentation.
Feb 01
prev sibling next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 31 January 2016 at 11:14:08 UTC, Rory McGuire wrote:
 If you don't get a cease and desist letter from the D 
 Foundation soon I'd be surprised.
http://forum.dlang.org/post/n5sf7o$mu1$2 digitalmars.com Andrei isn't exactly enthusiastic (though later on, he softens a bit), but I'm convinced we need to change course anyway. Of course, if they did try more harsh measures, I'd fight it, and then we'd see a far more problematic division in the community.
 but you have absolutely no reason to constantly insult
 the work on the main site.
I see a distinction between insults and technical criticism. A navigation bar that is difficult to navigate is a technical problem - and there's a technical solution. Changing the color of template constraints is like shoving toys under the bed when your mother is about to inspect your room. It might fool her for about two seconds, but she's going to see it anyway and will not be pleased. And more importantly, it doesn't actually clean up the dust, or organize the toys, or discover the dirty laundry that got mixed in to the floor. It is an easy "solution" that you can quickly do without a lot of work, but it isn't actually fixing anything. It is solving the unreadable mess problem by shoving half of it under the rug instead of actually making it readable. (And putting the text "Constraint:" before is silly too. Anyone who knows what that means also knows what if() means in this context, and anybody who doesn't isn't going to learn anything from it.) If dlang.org fixed these problems, I'll set my site to redirect to their site again like it used to do. But, as I've described before, I don't think it will change in that direction without a major, multi-faceted overhaul. I'm doing that overhaul now. And my content changes are available for upstream: https://github.com/D-Programming-Language/phobos/pull/3895 Minor content so far, but lots of cross referencing, fixing missing comments, organizing, etc. though some of it also relies on the generator changes, so it isn't something they can just merge and forget about...
 _Creating division in such a small community is not helpful_.
It might be such a small community because of the weakness in its documentation. I've interviewed a LOT of new and prospective D users over the last several months and every one of them, without exception, expressed difficulty to me in navigating the official site. Several of them just went elsewhere and didn't look back.
Jan 31
parent Rory McGuire via Digitalmars-d-announce writes:
On Sun, Jan 31, 2016 at 9:06 PM, Adam D. Ruppe via
Digitalmars-d-announce <digitalmars-d-announce puremagic.com> wrote:
 On Sunday, 31 January 2016 at 11:14:08 UTC, Rory McGuire wrote:
 If you don't get a cease and desist letter from the D Foundation soon I'd
 be surprised.
http://forum.dlang.org/post/n5sf7o$mu1$2 digitalmars.com Andrei isn't exactly enthusiastic (though later on, he softens a bit), but I'm convinced we need to change course anyway. Of course, if they did try more harsh measures, I'd fight it, and then we'd see a far more problematic division in the community.
 but you have absolutely no reason to constantly insult
 the work on the main site.
I see a distinction between insults and technical criticism. A navigation bar that is difficult to navigate is a technical problem - and there's a technical solution. Changing the color of template constraints is like shoving toys under the bed when your mother is about to inspect your room. It might fool her for about two seconds, but she's going to see it anyway and will not be pleased. And more importantly, it doesn't actually clean up the dust, or organize the toys, or discover the dirty laundry that got mixed in to the floor. It is an easy "solution" that you can quickly do without a lot of work, but it isn't actually fixing anything. It is solving the unreadable mess problem by shoving half of it under the rug instead of actually making it readable. (And putting the text "Constraint:" before is silly too. Anyone who knows what that means also knows what if() means in this context, and anybody who doesn't isn't going to learn anything from it.) If dlang.org fixed these problems, I'll set my site to redirect to their site again like it used to do. But, as I've described before, I don't think it will change in that direction without a major, multi-faceted overhaul. I'm doing that overhaul now. And my content changes are available for upstream: https://github.com/D-Programming-Language/phobos/pull/3895 Minor content so far, but lots of cross referencing, fixing missing comments, organizing, etc. though some of it also relies on the generator changes, so it isn't something they can just merge and forget about...
 _Creating division in such a small community is not helpful_.
It might be such a small community because of the weakness in its documentation. I've interviewed a LOT of new and prospective D users over the last several months and every one of them, without exception, expressed difficulty to me in navigating the official site. Several of them just went elsewhere and didn't look back.
100% bro, I'm not referring to making a separate implementation or anything like that I'm saying: "As a 'important user' in our community your voice counts for something and be careful what you say". Surely everyone can agree on that?
Feb 01
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/31/16 6:14 AM, Rory McGuire via Digitalmars-d-announce wrote:
 If you don't get a cease and desist letter from the D Foundation soon
 I'd be surprised.
Please. Let's take this a notch or three down. -- Andrei
Feb 02
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-30 21:58, Adam D. Ruppe wrote:

 If you go into a thing:
 http://dpldocs.info/experimental-docs/std.stdio.write.html
"extern (C) nothrow" is repeated a couple of times. -- /Jacob Carlborg
Jan 31
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 31 January 2016 at 13:11:54 UTC, Jacob Carlborg wrote:
 "extern (C) nothrow" is repeated a couple of times.
Yeah, those shouldn't be there at all on this function. I probably bugged the removal of attributes when moving up a scope or something.
Jan 31