On 1/21/2011 11:03 PM, Jonathan M Davis wrote:
> On Friday 21 January 2011 22:46:24 Andrei Alexandrescu wrote:
>> On 1/22/11 12:36 AM, Brad Roberts wrote:
>>> the problem is here:
>>>
>>> # Set DDOC, the documentation generator
>>> ifeq ($(OS),linux)
>>>
>>>      DDOC=wine dmd
>>>
>>> else
>>>
>>>      DDOC=dmd
>>>
>>> endif
>>>
>>> I can 'fix' this for now by overriding DDOC when invoking make.
>>
>> Yah, please do. Since Jonathan's changes we're migrating towards a platform-independent html build. I had to use wine just to make sure I match the dox that Walter was generating on Windows.
> 
> I think that it's great to be able to build the windows docs using wine, but I think that that should only be when building with OS=win32wine and that otherwise, they should be built natively. But since so much of the documentation has been Windows-only, I can see why you would have just made it use wine all the time.
> 
> - Jonathan M Davis

Ok, overriding DDOC when invoking make is working and I've got the 64 bit build building the docs and uploading them.  I've linked the output to the test results page right there at the top:

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

It's not ideal, but it's as much effort as I feel like investing in the docs building right now.  I'll be happy to change the tester scripts should someone change the make files to be less odd.

Also, I'm only running it on one of the 3 builds right now.  I can expand that to the rest, if there's value in it.  The win32 one is likely the most value since it's the most 'real' from the sounds of it.

Later,
Brad

On 1/21/2011 11:14 PM, Brad Roberts wrote:
> On 1/21/2011 11:03 PM, Jonathan M Davis wrote:
>> On Friday 21 January 2011 22:46:24 Andrei Alexandrescu wrote:
>>> On 1/22/11 12:36 AM, Brad Roberts wrote:
>>>> the problem is here:
>>>>
>>>> # Set DDOC, the documentation generator
>>>> ifeq ($(OS),linux)
>>>>
>>>>      DDOC=wine dmd
>>>>
>>>> else
>>>>
>>>>      DDOC=dmd
>>>>
>>>> endif
>>>>
>>>> I can 'fix' this for now by overriding DDOC when invoking make.
>>>
>>> Yah, please do. Since Jonathan's changes we're migrating towards a platform-independent html build. I had to use wine just to make sure I match the dox that Walter was generating on Windows.
>>
>> I think that it's great to be able to build the windows docs using wine, but I think that that should only be when building with OS=win32wine and that otherwise, they should be built natively. But since so much of the documentation has been Windows-only, I can see why you would have just made it use wine all the time.
>>
>> - Jonathan M Davis
> 
> Ok, overriding DDOC when invoking make is working and I've got the 64 bit build building the docs and uploading them.  I've linked the output to the test results page right there at the top:
> 
>     http://d.puremagic.com/test-results/
> 
> It's not ideal, but it's as much effort as I feel like investing in the docs building right now.  I'll be happy to change the tester scripts should someone change the make files to be less odd.
> 
> Also, I'm only running it on one of the 3 builds right now.  I can expand that to the rest, if there's value in it.  The win32 one is likely the most value since it's the most 'real' from the sounds of it.
> 
> Later,
> Brad

Scratch that last part, since we're seeing differences between the platforms, I went ahead and extended it to all three builds.  The windows one, as expected, is failing right now.  It matches what SHOO reported earlier tonight.

The three doc links across the top of the results page are only for the most recently completed build.  If the most recent build fails, the link will only show what docs it made it through, if any.

On 01/22/2011 04:48 AM, Andrei Alexandrescu wrote:
> I'd love to have a minimal stylistic checker upon checkin. For one thing, I don't find any reason for two empty lines and I don't plan to rearrange the monitor sideways for more vertical space.

Thought I was the only one caring for vertical space...

Denis
_________________
vita es estrany
spir.wikidot.com

On Saturday 22 January 2011 02:26:42 spir wrote:
> On 01/22/2011 04:48 AM, Andrei Alexandrescu wrote:
> > I'd love to have a minimal stylistic checker upon checkin. For one thing, I don't find any reason for two empty lines and I don't plan to rearrange the monitor sideways for more vertical space.
> 
> Thought I was the only one caring for vertical space...

You can find just about as many preferences as programmers. Some programmers like lots of extra space (presumably so that the code is easier to read), whereas as others want as little extra space as posible (presumably seeing it as a waste of space and disliking the fact that they can then fit less code on the screen). Some programmers like to put spaces around parens. Some like to put them only on the inside of parens. Others don't like _any_ spaces around parens. Some programmers like opening braces on the same line as the preceding statement, whereas as others always want braces on their own line. Some programmers prefere camelcased variable names; others prefer names with embedded underscores.

I'm sure that there are styles which could be consider essentially objectively bad (such as putting 1000 spaces wherever you can legally put whitespace or never using any more whitespace then you have to, putting all of the code on a single line). However, generally-speaking, it's purely subjective and everyone is going to have their own opinion and preferences on the matter.

- Jonathan M Davis

On Friday 21 January 2011 19:48:09 Andrei Alexandrescu wrote:
> On 1/21/11 8:56 PM, Brad Roberts wrote:
> > <snip not-broken style issues -- not that I disagree, just partitioning the discussion>.
> 
> I'd love to have a minimal stylistic checker upon checkin. For one thing, I don't find any reason for two empty lines and I don't plan to rearrange the monitor sideways for more vertical space.

By the way, the D style guide currently posted on the main site specifically says that you're _supposed_ to put two blank lines between function bodies. It also claims that all submissions to Phobos are supposed to follow those guidelines.

So, if you _really_ don't want two blank spaces between function bodies, then that page should probably be updated. I confess that I prefer that there be two blank lines between functions, and I'm not sure that that page quite matches the style that we want in Phobos anyway (though glancing at it, it looks pretty much correct), but we might want to make sure that that page actually reflects what we're actually trying to do in Phobos. At minimum, specifically testing with a stylistic checker that something is _not_ done in code when the style page on the main site says that it's _supposed_ to be in code wouldn't really look good (not to mention, it would be confusing to anyone who actually paid attention to both). I confess that I only noticed though, because someone on D.Learn was wondering why various enums in Phobos don't follow the style guide - such as Endian.BigEndian and FunctionAttributes.NOTHROW.

- Jonathan M Davis

FWIW that style guide is useless.

It's simplest to do what the existing code does. It's okay to adapt one to a specific style inside of a library, but mixing styles inside the same file is not very pleasant. For example, does it kill whoever likes this:

if(expression)

to insert one space between the if and the paren? Now we have 1% of all ifs different from all others. What good does that do?

Then we have of course

if( expression )

which accounts for about 10% of all ifs (looks like Sean and Don are using that one) and finally the oddest of all:

if( expression)

I'd say at least if making small edits for one module it's common courtesy to keep whatever style the module already had instead of debating (and inconsistently inserting) the relative merits of different styles.


Andrei

On 01/22/2011 10:16 PM, Jonathan M Davis wrote:
> On Friday 21 January 2011 19:48:09 Andrei Alexandrescu wrote:
>> On 1/21/11 8:56 PM, Brad Roberts wrote:
>>> <snip not-broken style issues -- not that I disagree, just partitioning the discussion>.
>>
>> I'd love to have a minimal stylistic checker upon checkin. For one thing, I don't find any reason for two empty lines and I don't plan to rearrange the monitor sideways for more vertical space.
>
> By the way, the D style guide currently posted on the main site specifically says that you're _supposed_ to put two blank lines between function bodies. It also claims that all submissions to Phobos are supposed to follow those guidelines.
>
> So, if you _really_ don't want two blank spaces between function bodies, then that page should probably be updated. I confess that I prefer that there be two blank lines between functions, and I'm not sure that that page quite matches the style that we want in Phobos anyway (though glancing at it, it looks pretty much correct), but we might want to make sure that that page actually reflects what we're actually trying to do in Phobos. At minimum, specifically testing with a stylistic checker that something is _not_ done in code when the style page on the main site says that it's _supposed_ to be in code wouldn't really look good (not to mention, it would be confusing to anyone who actually paid attention to both). I confess that I only noticed though, because someone on D.Learn was wondering why various enums in Phobos don't follow the style guide - such as Endian.BigEndian and FunctionAttributes.NOTHROW.
>
> - Jonathan M Davis
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos

On Saturday 22 January 2011 20:28:32 Andrei Alexandrescu wrote:
> FWIW that style guide is useless.
> 
> It's simplest to do what the existing code does. It's okay to adapt one to a specific style inside of a library, but mixing styles inside the same file is not very pleasant. For example, does it kill whoever likes this:
> 
> if(expression)
> 
> to insert one space between the if and the paren? Now we have 1% of all ifs different from all others. What good does that do?
> 
> Then we have of course
> 
> if( expression )
> 
> which accounts for about 10% of all ifs (looks like Sean and Don are using that one) and finally the oddest of all:
> 
> if( expression)
> 
> I'd say at least if making small edits for one module it's common courtesy to keep whatever style the module already had instead of debating (and inconsistently inserting) the relative merits of different styles.

Well, I would point out that the style guide doesn't actually say anything about where braces or parens go or anything like that. It's pretty short, and a good chunk of it is just naming conventions. I pointed out the blank line thing because you were advocating something which was in contradiction to the style guide, and the style guide claims that that's what submissions to Phobos are supposed to use. So, if we're really trying to follow that style guide, we either need to update the style guide or change what we're doing to match it. Or we can change it to not say that that's what Phobos requires. There _are_ people who look at the style guide and then wonder why Phobos doesn't match it. It _is_ primarily a naming convention issue though - particularly because the guide does _not_ say anythingc about where you put braces or parens.

So, I'm not really advocating that we push a single style throughout Phobos beyond naming conventions (since that _does_ affect the API). I'm just pointing out that it looks bad when the style guide says one thing, and we do another - particularly when the style guide claims that it's what Phobos does. It's fine with me if someone puts one blank lines betwen functions (though I'd prefer to be able to use two). If someone wants to put extra spaces around their parens, I don't like it, but I'm not going to complain about it and insist that we try and be stylistically consistent.

All I was trying to do was point out that what you were suggesting that we check with a style checker was contradicted the style guide that the official site claims that we follow. And if there's something that we really want to do which doesn't match the style guide, then we should either change the style guide to match (unfortunately, there _are_ people who read it and expect us to follow it and complain about it when we don't) or change it so that it doesn't claim that Phobos uses it.

Personally, I think what really matters stylistically is how we name things in the public API. It would be nice if certain things are common in code in the D community in general (such as the declaration style putting the * next to the type, not the variable name), but what really matters is the public API. And we have been doing work to make it so that Phobos' public API is consistent - in particular some of the changes that you've been making to std.string of late.

- Jonathan M Davis

On 1/22/11 11:21 PM, Jonathan M Davis wrote:
> Well, I would point out that the style guide doesn't actually say anything about where braces or parens go or anything like that. It's pretty short, and a good chunk of it is just naming conventions. I pointed out the blank line thing because you were advocating something which was in contradiction to the style guide, and the style guide claims that that's what submissions to Phobos are supposed to use. So, if we're really trying to follow that style guide, we either need to update the style guide or change what we're doing to match it.

We should update it.

Andrei

On 01/23/2011 06:35 AM, Andrei Alexandrescu wrote:
> On 1/22/11 11:21 PM, Jonathan M Davis wrote:
>> Well, I would point out that the style guide doesn't actually say anything about where braces or parens go or anything like that. It's pretty short, and a good chunk of it is just naming conventions. I pointed out the blank line thing because you were advocating something which was in contradiction to the style guide, and the style guide claims that that's what submissions to Phobos are supposed to use. So, if we're really trying to follow that style guide, we either need to update the style guide or change what we're doing to match it.
>
> We should update it.
>
> Andrei

...and update the language accordingly ;-)

Denis
_________________
vita es estrany
spir.wikidot.com