Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Chris Wright via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Ola Fosheim Grøstad via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Ola Fosheim Grøstad via Digitalmars-d-announce]

On Monday, 1 February 2016 at 20:01:11 UTC, Chris Wright wrote:
What I would actually expect, instead of a C 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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

On Sun, Jan 31, 2016 at 7:54 PM, Chris Wright via
Digitalmars-d-announce  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 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.
>
> > On Sat,
>
> Please, disable HTML mail for this list.

Re: Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

On Sun, Jan 31, 2016 at 9:06 PM, Adam D. Ruppe via
Digitalmars-d-announce  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?

Re: Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

On Mon, Feb 1, 2016 at 10:01 PM, Chris Wright via
Digitalmars-d-announce  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 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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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 :)

Re: Better docs for D (WIP)

[Nick Sabalausky via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Chris Wright via Digitalmars-d-announce]

On Sat, 30 Jan 2016 20:58:44 +, 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!

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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 

Re: Better docs for D (WIP)

[Ola Fosheim Grøstad via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Bastiaan Veelo via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[anonymous via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[default0 via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

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

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.

Re: Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Martin Nowak via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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 :(

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

On 01/05/2016 12:09 AM, Adam D. Ruppe wrote:

1) a massively simplified build. Indeed, I'll make a web form so you
don't even have to have dmd installed to make some docs.


Nice. The web forms sound like a great idea.


This got posted today:
https://issues.dlang.org/show_bug.cgi?id=15516#c2

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

My system already runs a single file or an entire directory and just
works. It will never forget a file because you didn't add it to mak/DOCS
of win32.mak or anything else.


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


My understanding is that build scripts (including makefiles) are 
recommended to include a manifest list of files that are part of the 
project, as opposed to picking up files with wildcards. That way there's 
less likelihood to pick up litter along with the legitimate files, or to 
produce incomplete builds if some files are missing by mistake. The 
underlying thesis is that that's a good kind of redundancy.


That said, in a git-controlled directory things aren't that bad. "git 
clean -dfx" removes uncontrolled files and "git checkout" makes sure all 
files are present. Would you recommend switching to wildcards in our 
makefiles and assume people use git to keep their directories in good shape?


Regarding the makefile complications. I think it stands to reason that 
in the dlang.org repo, the command "make" will produce the entire 
website. There are quite a few pieces to that:


* The druntime and phobos docs must be built as well.

* For these there are the docs as per last release and also the docs in 
the current HEAD, which are distinct.


* Each library version must be built with the same compiler version. The 
appropriate compiler version might be missing, so it needs to be 
downloaded, installed, and run on the side without affecting any 
existing installation.


* There are ancillary things to be build, such as the vibe docs and the 
language reference (ebook, pdf, chm). The ebook has ranked #26 among 
most downloaded files on dlang.org, the pdf is #40, and the chm is 
apparently not in the top 256. The most popular ddox file is 
http://dlang.org/library, ranking at #96.


My understanding is that your system does not do any of these things. If 
such functionality were to be integrated, either the system would 
increase in complexity correspondingly, or it would become a part of a 
larger build script.


The script 
https://github.com/D-Programming-Language/dlang.org/blob/master/posix.mak stands 
at 498 lines. What ways there are to make it considerably simpler and 
smaller?



I'll also make a web form to upload new pages and probably entire
projects for automatic processing too.


Indeed the web forms sound like a great idea. Would you want to work on 
such for the mainline website as well? It's not a contest; the better 
everything is, the better off everybody is.



2) My linking system already works better than ddoc allows. You can
reference with a single macro: $(REF some.name). I also keep MREF, XREF,
and a few others for legacy phobos+ddoc compatibility, but the user
doesn't have to know a hundred obscure macros. (There's about a
half-dozen simple ones instead, plus a few thin wrappers over HTML which
I might kill but might not since they don't really bother me.)


Nice. What could we do in ddoc and ddox to have a similar improvement?


Combined with the ease of adding all new files, contributors can just
link new articles they write to go in depth without worrying about process.



3) I'm also going to make a dynamic webpage once I declare this beta
where viewers will be given random pages and asked to eyeball it for me.
If they flag it as buggy - with a single click on the page, no bugzilla
signups - it'll contact me and I'll work on the bug.


How do you envision scaling it up as the system becomes more successful 
and you get more requests than you can handle reasonably quick?


Would you be willing to set up such a system for dlang.org as well? It 
would be absolutely fantastic.



If they want to contribute to content, I can pull up the existing
comment source code and present it right there, again likely emailed to
me for integration, or the source location can be opened in Phobos for a
traditional pull request.

This will encourage crowd sourcing doc bug fixes.


My understanding is a lot of it hinges on you being on top of things 
(and the bottleneck thereof). I think it's awesome that you're able and 
willing to do this; the same kind of enthusiasm and dedication would 
definitely help fix a lot of the existing issues with ddoc and ddox.



4) I'll never complain about spaces vs tabs, line length, or any other
trivial nonsense. If I don't like that stuff, I'll just fix it myself

Re: Better docs for D (WIP)

[default0 via Digitalmars-d-announce]

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 :-)

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Jacob Carlborg via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[JohnCK via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Nordlöw via Digitalmars-d-announce]

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!

Re: Better docs for D (WIP)

[Nordlöw via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[John Colvin via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Ola Fosheim Grøstad via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[JohnCK via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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 

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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 )

Re: Better docs for D (WIP)

[JohnCK via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[JohnCK via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[JohnCK via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Bastiaan Veelo via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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/pdjfvsmvdewwtjoic...@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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

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/pdjfvsmvdewwtjoic...@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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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!

Re: Better docs for D (WIP)

[default0 via Digitalmars-d-announce]

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(, "Result 
is blabla") and recompiling just to debug these :/

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Wednesday, 30 December 2015 at 15:51:23 UTC, default0 wrote:
Yeah, I misinterpreted the "E : " to mean "E is or 
inherits from ", rechecking the argument deduction rules 
for templates I think this instead means "E should be deduced 
as ".


Sort of.. it means "if E can be implicitly converted to ".

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

Re: Better docs for D (WIP)

[bachmeier via Digitalmars-d-announce]

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_Batteries:_.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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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_Batteries:_.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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Israel via Digitalmars-d-announce]

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?

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Wednesday, 30 December 2015 at 14:25:24 UTC, default0 wrote:
As an aside, the mere formatting of the list of 
template-constraints on the dlang page made me nope right out 
of even bothering to figure out how to read them or what the 
difference between the first and the second overload of join 
was.


Aye, it is a complete mess and virtually *nobody* bothers looking 
at them. (BTW, dmd has the same problem in error messages. I plan 
to format them eventually too, with some kind of highlighting of 
passed and failing clauses. I already did a proof of concept for 
ordinary overloading functions and it wasn't actually that hard. 
I just wish I didn't have other things to do!)


New people are often outright scared away from everything and 
left with the impression that D is an experts-only language. The 
Phobos devs know this and have been trying to add more examples - 
a good, necessary step - but that isn't the whole problem.


When users modify the examples and they fail to compile, they 
need to understand what's going on. The compiler will complain in 
terms of those ugly constraints, not in terms of fixed, working 
examples. They need some way of understanding what it is saying.



Also: I plan to add a doc section called "diagnostics" with 
sample error messages and translations. I've actually considered 
doing this before but was stopped by concerns over vertical space.


No kidding, when writing ddoc, I worry about it taking up too 
much space on the page and will cut content out as a result. If 
the prototype is compressed, it just leaves a mental bug that 
says space must matter, use it sparingly.



Checking dpldocs for proper formatting and spending half a 
minute making sense of it I figured that the one was for an 
exactly matched element type and the other one was to allow 
joining a baseClass[][] with a subClass[] or something along 
those lines.



The join overloads are basically:

#1: array of arrays joined by an array
   join(["a", "b", "c"], ", "); // the joiner is an array
 -> "a, b, c"

#2: array of arrays joined by an element
   join(["a", "b", "c"], ' '); // the joiner is an element
 -> "a b c"

There is no example for form #2 in the documentation. (BTW I 
think the examples should be commented too.)


#3: array of arrays joined without anything
   join(["a", "b", "c"])
-> "abc"


Nothing about inheritance in there, the constraints talk about 
ElementType!RoR which means (conceptually) it is stripping the 
"[]" off a type, so for "int[]", it returns "int".



That should probably just be written in the text. (That's another 
thing people tell me, they come in with a question and I can give 
them a quick answer, then they ask "why didn't the docs just put 
it that simply?" And a few times, I go to open a PR but get 
stalled by the process somewhere)


But there's a LOT of functions in Phobos so I am trying to 
automate this because while I can write it for any individual 
function by hand, writing it for ALL the functions is going to 
take more time than I have.



Cumbersome and annoying (ie: slow and unproductive).


absolutely.

Also the information that /library even exists is new to me. I 
have only discovered it through reading this post.


Right. New users either don't know about it because it doesn't 
get linked to much and thus has lower page rank (unless you have 
already trained Google through D searches to favor D results), or 
they do find it and are confused as to what version it refers to.


There's been a few people who come to this newsgroup saying 
"these docs look old, what's up with it?" If they hit the disqus 
comment, it says "recent activity, 2 years ago" which furthers 
this impression.


(none of these results mention that you should simply 
cast(char[]) and then call validate on the casted array, from 
what I could tell skimming through them for 5 minutes, I might 
have missed a mention though, which would simply mean it is not 
obvious enough)


When you mentioned this before, I went to add it to the docs but 
couldn't find a good place to put it. The vertical space brain 
bug hurt me on base64 itself, then the question of linking hurt 
me when thinking of putting it somewhere else like the wiki, then 
the question of process killed me when I went to add a new page!


It was actually this experience that tipped me over the edge and 
I decided to start working on doc infrastructure myself. (I've 
spent a good amount of time this year trying to fix ddoc itself - 
starting with the `code` syntax in January - but ddoc itself is 
only part of the problem)

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Rikki Cattermole via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Rikki Cattermole via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

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 or a QMap, 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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

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

Re: Better docs for D (WIP)

[Rikki Cattermole via Digitalmars-d-announce]

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.

Re: Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

Rikki Cattermole  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?