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.