www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - How do I submit documentation...

reply Chad J <chadjoan __spam.is.bad__gmail.com> writes:
...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 

(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?
Jun 23 2012
next sibling parent reply "Jesse Phillips" <jessekphillips+D gmail.com> writes:
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.
Jun 23 2012
parent reply Chad J <chadjoan __spam.is.bad__gmail.com> writes:
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.
Jun 23 2012
parent reply "Jesse Phillips" <jessekphillips+D gmail.com> writes:
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.
Jun 24 2012
parent Chad J <chadjoan __spam.is.bad__gmail.com> writes:
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).
Jun 24 2012
prev sibling next sibling parent reply "Tobias Pankrath" <tobias pankrath.net> writes:
 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.
Jun 24 2012
next sibling parent Chad J <chadjoan __spam.is.bad__gmail.com> writes:
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!
Jun 24 2012
prev sibling parent reply Brad Anderson <eco gnuk.net> writes:
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
Jun 24 2012
next sibling parent Chad J <chadjoan __spam.is.bad__gmail.com> writes:
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.
Jun 24 2012
prev sibling parent reply Chad J <chadjoan __spam.is.bad__gmail.com> writes:
On 06/24/2012 03:27 PM, Brad Anderson wrote:

 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.


Where's the autotester?
Jun 24 2012
parent Brad Anderson <eco gnuk.net> writes:
On Sun, Jun 24, 2012 at 2:23 PM, Chad J
<chadjoan __spam.is.bad__gmail.com>wrote:


 On 06/24/2012 03:27 PM, Brad Anderson wrote:


 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.


 Where's the autotester?


http://d.puremagic.com/test-results/pulls.ghtml

You can even get Greasemonkey scripts for Firefox/Chrome that display the
test results on the Github pull request page.  It's very nice.

Regards,
Brad Anderson
Jun 24 2012
prev sibling parent Chad J <chadjoan __spam.is.bad__gmail.com> writes:
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.
Jun 24 2012