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:


    join(["a", "b", "c"], ", "); // the joiner is an array
      -> "a, b, c"


    join(["a", "b", "c"], ' '); // the joiner is an element
      -> "a b c"


think the examples should be commented too.)


    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:


    join(["a", "b", "c"], ", "); // the joiner is an array
      -> "a, b, c"


    join(["a", "b", "c"], ' '); // the joiner is an element
      -> "a b c"


 think the examples should be commented too.)


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


apparently not in the top 256. The most popular ddox file is 


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



  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 2016



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 2016



 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 2016



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 2016



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 2016



  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 2016



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 2016



 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 2016



  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 2016



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 2016



  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 2016



 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 2016



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 2016



  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 2016



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 2016



 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 2016



 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 2016



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 2016



  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 2016



 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 2016



  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 2016



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 2016



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 2016



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 2016



  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 2016



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 2016



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 2016



  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 2016