View mode: basic / threaded / horizontal-split · Log in · Help
June 24, 2012
How do I submit documentation...
...without wanting to slit my wrists?

I see that https://github.com/D-Programming-Language still has a bunch 
of the core D projects huddled together, but no single repository that 
binds it all together.

This is immensely frustrating if I want to do any contributions to DMD, 
Phobos, or the documentation.  Right now I'd like to contribute to 
documentation mostly.  I haven't done so because there is an annoying 
barrier to entry: I better be able to download and compile everything so 
that I can write unittests so that I can write documentation.  I really 
want to be able to download /one single repository/ and then type "make 
all" and have it /just work/.  But no, I have to download each of these 
things individually and figure out where each of them goes in some kind 
of canonical directory structure that everyone except me knows.  Oh, the 
me from a few months ago knew where to put things.  The me from now will 
need to be told again -- or do a grindy search over old emails.

If I'm going to make a pull request for every few words I edit or every 
example/unittest I want to add, then the {pull->edit->make docs->test 
with browser->push} cycle has to be very fast.  Right now, it would 
probably be a few hours before I even have things setup well enough that 
I can even /start/ editing.

I know it takes a while to mess with this stuff because I've done it 
some months ago.  It was thanks to bug #5278 
(http://d.puremagic.com/issues/show_bug.cgi?id=5278) which makes it so I 
can't use DMD without applying my own patch and building from source. 
I've done it a couple other times when I wanted to mess with DMD/phobos 
internals too.  Every time it takes hours of completely unproductive 
wasted time to build from source.

This is in stark contrast to wikis and the like where there's a button 
to /just edit the page dammit/.  I understand that this would be way too 
unmoderated for D's central projects, but it would be very nice if we 
had something closer to that.  At this point though I'd settle for just 
being able to build dmd/phobos/docs easily because it seems like a 
reasonable thing to ask for.

So how about it, all-encompassing D git repo and buildscripts please?
June 24, 2012
Re: How do I submit documentation...
On Sunday, 24 June 2012 at 00:40:08 UTC, Chad J wrote:

> So how about it, all-encompassing D git repo and buildscripts 
> please?

The problem is, the documentation/website is built from the 
source code. The source code doesn't rely on the website, though 
you may need the in development dmd to build Phobos. dmd does not 
need Phobos. So while, better, you'd still just end up with a 
single repository with three submodules which would need 
downloaded. Or two repositories, on for the Phobos/dmd dependency 
then another for the website/phobos/dmd dependency.

Directory structure.

cwd: /path/to/some/place

d-programming-language.org/
phobos
dmd

dmd actually doesn't matter, you'll have to convince your 
environment to use the one you build though.
June 24, 2012
Re: How do I submit documentation...
On 06/23/2012 08:59 PM, Jesse Phillips wrote:
> On Sunday, 24 June 2012 at 00:40:08 UTC, Chad J wrote:
>
>> So how about it, all-encompassing D git repo and buildscripts please?
>
> The problem is, the documentation/website is built from the source code.
> The source code doesn't rely on the website, though you may need the in
> development dmd to build Phobos. dmd does not need Phobos. So while,
> better, you'd still just end up with a single repository with three
> submodules which would need downloaded. Or two repositories, on for the
> Phobos/dmd dependency then another for the website/phobos/dmd dependency.
>
> Directory structure.
>
> cwd: /path/to/some/place
>
> d-programming-language.org/
> phobos
> dmd
>
> dmd actually doesn't matter, you'll have to convince your environment to
> use the one you build though.

No way it is that easy.  My situation called for this:

src/web
src/phobos
src/druntime
dmd
linux/bin64/dmd -> ../../dmd/src/dmd
linux/bin64/dmd.conf  (Copy this from a released zip file.)
linux/lib64/libphobos2.a ->
  ../../src/phobos/generated/linux/debug/32/libphobos2.a
linux/lib64/libdruntime.a ->
  ../../src/druntime/lib/libdruntime.a

dmd.conf may need editing.

I am also left wondering if that is incomplete.  I probably forgot 
something.

(Noooo, you made me look!)

I don't like how much harder it is to find versions of DMD that compile 
versions of phobos.  Because they are in different repositories, there 
is no easy way to figure out which commits are in sync with which 
commits in the other repo.  I remember some amount of time recompiling 
while searching for commit versions that line up.
June 24, 2012
Re: How do I submit documentation...
> This is in stark contrast to wikis and the like where there's a 
> button to /just edit the page dammit/.  I understand that this 
> would be way too unmoderated for D's central projects,

Github can do this. Just use the "Edit this file"-Button for 
minor changes.
June 24, 2012
Re: How do I submit documentation...
On 06/24/2012 03:35 AM, Tobias Pankrath wrote:
>> This is in stark contrast to wikis and the like where there's a button
>> to /just edit the page dammit/. I understand that this would be way
>> too unmoderated for D's central projects,
>
> Github can do this. Just use the "Edit this file"-Button for minor changes.
>
>

Hey, I missed that.  That looks very handy.  Thanks!
June 24, 2012
Re: How do I submit documentation...
On 06/23/2012 08:39 PM, Chad J wrote:
> ...

As I reread this a day later I realize it is unreasonably harsh.  I am 
sorry for that.  I was frustrated.

I still have stuff I want to contribute eventually.  Please Walter, 
Andrei, and Co., help me help you.
June 24, 2012
Re: How do I submit documentation...
On Sunday, 24 June 2012 at 01:30:14 UTC, Chad J wrote:

> No way it is that easy.  My situation called for this:
>
> src/web
> src/phobos
> src/druntime

I was and am not in Linux to look at my setup so I may have 
gotten the names wrong but I know I don't have them start with 
src/ (hmmm, maybe it has changed). The name for phobos didn't 
matter since that is where you build from, and the make file did 
mention d-programming-language.org as a directory so I just 
assumed. web I'm pretty sure is created by building the docs, and 
I completely forgot to mention druntime.

> dmd
> linux/bin64/dmd -> ../../dmd/src/dmd
> linux/bin64/dmd.conf  (Copy this from a released zip file.)
> linux/lib64/libphobos2.a ->
>   ../../src/phobos/generated/linux/debug/32/libphobos2.a
> linux/lib64/libdruntime.a ->
>   ../../src/druntime/lib/libdruntime.a
>
> dmd.conf may need editing.

This was all hidden under the "you'll have to convince your
environment to use the one you build though" I created a bash 
file to call DMD providing the proper libraries. I've had issues 
with it though, but hopefully I've convinced it to stop grabbing 
the system libraries I have installed.

This really isn't a problem with the repositories though. The 
setup is pretty simple, but ld will be looking in your system 
libraries first and the repositories cannot mess with your 
environment.
June 24, 2012
Re: How do I submit documentation...
On 06/24/2012 01:33 PM, Jesse Phillips wrote:
> On Sunday, 24 June 2012 at 01:30:14 UTC, Chad J wrote:
>
>> No way it is that easy. My situation called for this:
>>
>> src/web
>> src/phobos
>> src/druntime
>
> I was and am not in Linux to look at my setup so I may have gotten the
> names wrong but I know I don't have them start with src/ (hmmm, maybe it
> has changed). The name for phobos didn't matter since that is where you
> build from, and the make file did mention d-programming-language.org as
> a directory so I just assumed. web I'm pretty sure is created by
> building the docs, and I completely forgot to mention druntime.
>
>> dmd
>> linux/bin64/dmd -> ../../dmd/src/dmd
>> linux/bin64/dmd.conf (Copy this from a released zip file.)
>> linux/lib64/libphobos2.a ->
>> ../../src/phobos/generated/linux/debug/32/libphobos2.a
>> linux/lib64/libdruntime.a ->
>> ../../src/druntime/lib/libdruntime.a
>>
>> dmd.conf may need editing.
>
> This was all hidden under the "you'll have to convince your
> environment to use the one you build though" I created a bash file to
> call DMD providing the proper libraries. I've had issues with it though,
> but hopefully I've convinced it to stop grabbing the system libraries I
> have installed.
>
> This really isn't a problem with the repositories though. The setup is
> pretty simple, but ld will be looking in your system libraries first and
> the repositories cannot mess with your environment.

Oh, but I think it is.

If you have all of the repositories tracked by a single repository that 
cements the directory structure of a D distribution, then you can 
streamline the build process.  The makefile in the ./dmd/src should be 
able to place the compiler executable into ./<platform>/bin<arch>/dmd. 
Also, druntime and phobos makefiles should place their library files 
into ./<platform>/lib<arch>/*.*.  dmd.conf and any other release 
requirements should also be included in this meta-repository.  I should 
be able to sit at the toplevel of this meta-repository (./ that is) and 
type "make all" and end up with all of the contents that end up in a zip 
file in all of the places they end up in the zip file, plus website 
things.  It should be everything needed to make a D release, minus the 
secret keys to actually write to the digitalmars.com website.  With a 
setup like this, it would require /zero/ time to convince things to use 
the correct paths (aside from maybe editing your PATH variable once or 
running the installer that is hopefully also included in the meta-repo).
June 24, 2012
Re: How do I submit documentation...
On Sun, Jun 24, 2012 at 1:35 AM, Tobias Pankrath <tobias@pankrath.net>wrote:

> This is in stark contrast to wikis and the like where there's a button to
>> /just edit the page dammit/.  I understand that this would be way too
>> unmoderated for D's central projects,
>>
>
> Github can do this. Just use the "Edit this file"-Button for minor changes.
>
>
>
We've actually made it even easier than this.  Click the "Improve this
page" button on the top-right of any dlang.org page.  You could make use of
the autotester to add unit tests but it's probably easier if you have a
complicated edit to just do it locally.

Regards,
Brad Anderson
June 24, 2012
Re: How do I submit documentation...
On 06/24/2012 03:27 PM, Brad Anderson wrote:
> On Sun, Jun 24, 2012 at 1:35 AM, Tobias Pankrath <tobias@pankrath.net
> <mailto:tobias@pankrath.net>> wrote:
>
>         This is in stark contrast to wikis and the like where there's a
>         button to /just edit the page dammit/.  I understand that this
>         would be way too unmoderated for D's central projects,
>
>
>     Github can do this. Just use the "Edit this file"-Button for minor
>     changes.
>
>
>
> We've actually made it even easier than this.  Click the "Improve this
> page" button on the top-right of any dlang.org <http://dlang.org> page.
>   You could make use of the autotester to add unit tests but it's
> probably easier if you have a complicated edit to just do it locally.
>
> Regards,
> Brad Anderson

Yes!  That is cool.
« First   ‹ Prev
1 2
Top | Discussion index | About this forum | D home