www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - new documentation format for std.algorithm

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Following ideas and advice from this newsgroup, I have a draft at

http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

There are two tables, one with just the names and the other with names 
and a brief description. Let me know of any feedback. Thanks!


Andrei
Feb 02 2011
next sibling parent reply BlazingWhitester <max.klyga gmail.com> writes:
On 2011-02-02 10:45:59 +0200, Andrei Alexandrescu said:

 Following ideas and advice from this newsgroup, I have a draft at
 
 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html
 
 There are two tables, one with just the names and the other with names 
 and a brief description. Let me know of any feedback. Thanks!
 
 
 Andrei

It looks realy nice! But brief description table could use some spacing between descriptions. It's a lilttle hard to read.
Feb 02 2011
next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Content-Type: text/plain

BlazingWhitester:

 It looks realy nice!

I agree, it's a clear improvement.
 But brief description table could use some spacing between 
 descriptions. It's a lilttle hard to read.

Instead of that I suggest to give an alternating white - light cyan background to every adjacent group in the first table and every row in the second table. Like in this page: http://www.digitalmars.com/webnews/newsgroups.php?renew=1 Replacing <tr> with <tr bgcolor="#F9F9F9"> or <tr bgcolor="#EAF6FF">. In attach (I hope) a modified version for show. Bye, bearophile
Feb 02 2011
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 6:47 AM, spir wrote:
 On 02/02/2011 11:08 AM, bearophile wrote:
 BlazingWhitester:

 It looks realy nice!

I agree, it's a clear improvement.
 But brief description table could use some spacing between
 descriptions. It's a lilttle hard to read.

Instead of that I suggest to give an alternating white - light cyan background to every adjacent group in the first table and every row in the second table. Like in this page: http://www.digitalmars.com/webnews/newsgroups.php?renew=1 Replacing<tr> with<tr bgcolor="#F9F9F9"> or<tr bgcolor="#EAF6FF">. In attach (I hope) a modified version for show.

Should /not/ be done (*): a web-designer should no more impose (background) colors to users, than font sizes or any other rendering style element. And certainly not white backgrounds, please (make my eyes cry). The site's design is supposed to just-work without any custom style; proposed style is a 'plus'. Denis (*) Works not by me, anyway: I cannot stand white background, highly painful after 1/4 hour. To avoid this, I set my own background color in firefox (as well as other elements like fonts & sizes). Thus, your trick is invisible by people like me.

I guess this makes the alternating backgrounds tenuous. For now I added some subtle horizontal lines, let me know how that works. http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html Andrei
Feb 02 2011
prev sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 04:58 PM, Andrei Alexandrescu wrote:
 On 2/2/11 6:47 AM, spir wrote:
 On 02/02/2011 11:08 AM, bearophile wrote:
 BlazingWhitester:

 It looks realy nice!

I agree, it's a clear improvement.
 But brief description table could use some spacing between
 descriptions. It's a lilttle hard to read.

Instead of that I suggest to give an alternating white - light cyan background to every adjacent group in the first table and every row in the second table. Like in this page: http://www.digitalmars.com/webnews/newsgroups.php?renew=1 Replacing<tr> with<tr bgcolor="#F9F9F9"> or<tr bgcolor="#EAF6FF">. In attach (I hope) a modified version for show.

Should /not/ be done (*): a web-designer should no more impose (background) colors to users, than font sizes or any other rendering style element. And certainly not white backgrounds, please (make my eyes cry). The site's design is supposed to just-work without any custom style; proposed style is a 'plus'. Denis (*) Works not by me, anyway: I cannot stand white background, highly painful after 1/4 hour. To avoid this, I set my own background color in firefox (as well as other elements like fonts & sizes). Thus, your trick is invisible by people like me.

I guess this makes the alternating backgrounds tenuous. For now I added some subtle horizontal lines, let me know how that works. http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

Does the job. For a question of taste I don't like that at all, but indeed others may disagree. (I prefere slight vertical spacing.) Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 11:08 AM, bearophile wrote:
 BlazingWhitester:

 It looks realy nice!

I agree, it's a clear improvement.
 But brief description table could use some spacing between
 descriptions. It's a lilttle hard to read.

Instead of that I suggest to give an alternating white - light cyan background to every adjacent group in the first table and every row in the second table. Like in this page: http://www.digitalmars.com/webnews/newsgroups.php?renew=1 Replacing<tr> with<tr bgcolor="#F9F9F9"> or<tr bgcolor="#EAF6FF">. In attach (I hope) a modified version for show.

Should /not/ be done (*): a web-designer should no more impose (background) colors to users, than font sizes or any other rendering style element. And certainly not white backgrounds, please (make my eyes cry). The site's design is supposed to just-work without any custom style; proposed style is a 'plus'. Denis (*) Works not by me, anyway: I cannot stand white background, highly painful after 1/4 hour. To avoid this, I set my own background color in firefox (as well as other elements like fonts & sizes). Thus, your trick is invisible by people like me. -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent reply Dmitry Olshansky <dmitry.olsh gmail.com> writes:
On 02.02.2011 11:45, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names 
 and a brief description. Let me know of any feedback. Thanks!

general is just plain great. And I like this simple list of mini-examples - sort of cheat-sheet you may have around in printed form. Now some issues: All in all I was frustrated with enum names listed along functions. And, yeah, Levenstain Distance related EditOp.remove is a nice catcha, and it's still there. I mean, clicking on remove in 'Mutation' table brings you to this enum description, even though there *is* remove which I can find using browser string find. Also remove is missing in mini-examples which is odd, and given the above problem newbies may conclude that there is no remove in std.algorithm ;) -- Dmitry Olshansky
Feb 02 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 4:00 AM, Dmitry Olshansky wrote:
 On 02.02.2011 11:45, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!

general is just plain great. And I like this simple list of mini-examples - sort of cheat-sheet you may have around in printed form. Now some issues: All in all I was frustrated with enum names listed along functions. And, yeah, Levenstain Distance related EditOp.remove is a nice catcha, and it's still there. I mean, clicking on remove in 'Mutation' table brings you to this enum description, even though there *is* remove which I can find using browser string find. Also remove is missing in mini-examples which is odd, and given the above problem newbies may conclude that there is no remove in std.algorithm ;)

Hmmm, this wrong jumping is a problem. I'll look into it. Offhand I don't know how to distinguish in the generated doc between an enum value and a function, but Adam did it. Adam? Andrei
Feb 02 2011
parent reply Adam Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu:
 Hmmm, this wrong jumping is a problem. I'll look into it. Offhand I
 don't know how to distinguish in the generated doc between an enum value
 and a function, but Adam did it. Adam?

My method is to track the level of nesting. The more <dl> tags above you in the tag tree, the further down you are. The generated html puts everything in a <dl> html tag. It goes: <dl> <dt>Function <u>name</u> and prototype</dt> <dd>Information about it</dd> </dl> For enums (and probably structs/class methods too, but I haven't confirmed yet), the sub-members are in that dd, like so: <dl> <dt>Enum Name</dt> <dd>Enum description <dl> <dt>Member #1 name</dt> <dd>Member #1 description</dd> </dl> </dd> </dl> So, if you keep track of how many <dl>'s are above you in the tree, you know what your parent is - are you a top level function or a member of another object? If you're a member of another object, you go up the tree a couple levels (get past your <dl>, then past the enclosing <dd>) and find the <dt> that is the last sibling to your grandparent. That holds the name of the enum. Here's my javascript implementation: function getParentTerm(e) { while(e) { if(e.tagName == "DD") return e; e = e.parentNode; } // we have the definition, gotta get the term right above it if(e == null) return null; // has no parent var r; var arr = e.parentNode.childNodes; for(var p = 0; p < arr.length; p++) { var a = arr[p]; if(a.tagName == "DT") r = a; // store the last term we saw... if(a == e) // if we're back to ourselves... return r; // ... the last term is the answer } //assert(0); } Since the actual function names are underlined, you can get a full name by searching the returned term for a <u> tag and pulling it out. While parent !is null, name = parent.name ~ "." ~ name, done. If you found the child a[name] elements and replaced the name attribute with the result from above, the links would all work too. I have an almost working D implementation too, but the HTML isn't well formed xml so my library butchers it a bit on output. That needs to be fixed before ditching the javascript. Then, I figure, we can add the helper program in between dmd itself and the live site. Anyway, I know what's wrong and how to fix it, but haven't written the last pieces of code to actually do it yet... after that, we just have some presentation issues to finalize and we're set.
Feb 02 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 10:06 AM, Adam Ruppe wrote:
 Andrei Alexandrescu:
 Hmmm, this wrong jumping is a problem. I'll look into it. Offhand I
 don't know how to distinguish in the generated doc between an enum value
 and a function, but Adam did it. Adam?

My method is to track the level of nesting. The more<dl> tags above you in the tag tree, the further down you are. The generated html puts everything in a<dl> html tag. It goes: <dl> <dt>Function<u>name</u> and prototype</dt> <dd>Information about it</dd> </dl> For enums (and probably structs/class methods too, but I haven't confirmed yet), the sub-members are in that dd, like so: <dl> <dt>Enum Name</dt> <dd>Enum description <dl> <dt>Member #1 name</dt> <dd>Member #1 description</dd> </dl> </dd> </dl> So, if you keep track of how many<dl>'s are above you in the tree, you know what your parent is - are you a top level function or a member of another object? If you're a member of another object, you go up the tree a couple levels (get past your<dl>, then past the enclosing<dd>) and find the<dt> that is the last sibling to your grandparent. That holds the name of the enum. Here's my javascript implementation: function getParentTerm(e) { while(e) { if(e.tagName == "DD") return e; e = e.parentNode; } // we have the definition, gotta get the term right above it if(e == null) return null; // has no parent var r; var arr = e.parentNode.childNodes; for(var p = 0; p< arr.length; p++) { var a = arr[p]; if(a.tagName == "DT") r = a; // store the last term we saw... if(a == e) // if we're back to ourselves... return r; // ... the last term is the answer } //assert(0); } Since the actual function names are underlined, you can get a full name by searching the returned term for a<u> tag and pulling it out. While parent !is null, name = parent.name ~ "." ~ name, done. If you found the child a[name] elements and replaced the name attribute with the result from above, the links would all work too. I have an almost working D implementation too, but the HTML isn't well formed xml so my library butchers it a bit on output. That needs to be fixed before ditching the javascript. Then, I figure, we can add the helper program in between dmd itself and the live site. Anyway, I know what's wrong and how to fix it, but haven't written the last pieces of code to actually do it yet... after that, we just have some presentation issues to finalize and we're set.

Got it, thanks. Perhaps indeed a ddoc change would make this easier. Andrei
Feb 02 2011
prev sibling next sibling parent reply Magnus Lie Hetland <magnus hetland.org> writes:
I think perhaps some adjustments could be made to the layout, to make 
it more suitable to narrow(ish) browser windows (c.f., the discussio 
about 80 columns -- without starting a huge thread like that again ;)

For one thing, in narrow(ish) columns, ragged-right might be 
preferable. Then again, it may be that the way it looks on my end isn't 
what's intended:

  http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

-- 
Magnus Lie Hetland
http://hetland.org
Feb 02 2011
next sibling parent reply "Denis Koroskin" <2korden gmail.com> writes:
On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland  
<magnus hetland.org> wrote:

 I think perhaps some adjustments could be made to the layout, to make it  
 more suitable to narrow(ish) browser windows (c.f., the discussio about  
 80 columns -- without starting a huge thread like that again ;)

 For one thing, in narrow(ish) columns, ragged-right might be preferable.  
 Then again, it may be that the way it looks on my end isn't what's  
 intended:

   http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

Left menu, Category and Function Name tables do take up about 800 pixels in width, leaving very little space for Description on small resolution displays, mostly because of the large font size used and identifiers as long as "largestPartialIntersectionWeighted". While there is little we can do with identifier names, I believe font size could be reduced by about 30% without sacrificing readability. At least in Opera the page looks well even at 70% scale.
Feb 02 2011
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Denis Koroskin" <2korden gmail.com> wrote in message 
news:op.vp9wmrreo7cclz korden-pc...
 On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland 
 <magnus hetland.org> wrote:

 I think perhaps some adjustments could be made to the layout, to make it 
 more suitable to narrow(ish) browser windows (c.f., the discussio about 
 80 columns -- without starting a huge thread like that again ;)

 For one thing, in narrow(ish) columns, ragged-right might be preferable. 
 Then again, it may be that the way it looks on my end isn't what's 
 intended:

   http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

Left menu, Category and Function Name tables do take up about 800 pixels in width, leaving very little space for Description on small resolution displays, mostly because of the large font size used and identifiers as long as "largestPartialIntersectionWeighted". While there is little we can do with identifier names, I believe font size could be reduced by about 30% without sacrificing readability. At least in Opera the page looks well even at 70% scale.

Actually, I think a smaller font improves the readability on that page. Left as it is, I would always hit "decrease font" two or three times in my browser before reading. (And that's even not counting the layout problems the current font size causes.) I also agree with what others said about needing a better visual boundary between the different descriptions. Only other thing I could bring up is that I'm really not as much a fan of justified text as Andrei. But I can live with it fine, of course, just as I've been doing (and I don't want to start a "left-aligned" vs "justified" bikeshed war). But other than those things, I think it looks great.
Feb 02 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 6:06 AM, Nick Sabalausky wrote:
 "Denis Koroskin"<2korden gmail.com>  wrote in message
 news:op.vp9wmrreo7cclz korden-pc...
 On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland
 <magnus hetland.org>  wrote:

 I think perhaps some adjustments could be made to the layout, to make it
 more suitable to narrow(ish) browser windows (c.f., the discussio about
 80 columns -- without starting a huge thread like that again ;)

 For one thing, in narrow(ish) columns, ragged-right might be preferable.
 Then again, it may be that the way it looks on my end isn't what's
 intended:

    http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

Left menu, Category and Function Name tables do take up about 800 pixels in width, leaving very little space for Description on small resolution displays, mostly because of the large font size used and identifiers as long as "largestPartialIntersectionWeighted". While there is little we can do with identifier names, I believe font size could be reduced by about 30% without sacrificing readability. At least in Opera the page looks well even at 70% scale.

Actually, I think a smaller font improves the readability on that page. Left as it is, I would always hit "decrease font" two or three times in my browser before reading. (And that's even not counting the layout problems the current font size causes.)

OK, for now I removed everything fixing the font size from the css. Take a look.
 I also agree with what others said about needing a better visual boundary
 between the different descriptions.

I'll look into this. I saw arguments against alternating colors. Also, horizontal lines throughout would be ugly. More ideas would be welcome.
 Only other thing I could bring up is that I'm really not as much a fan of
 justified text as Andrei. But I can live with it fine, of course, just as
 I've been doing (and I don't want to start a "left-aligned" vs "justified"
 bikeshed war).

Yah, it sometimes does look a bit forced. I'd need to add hyphenation to make justified text look good. Andrei
Feb 02 2011
parent "Nick Sabalausky" <a a.a> writes:
"Andrei Alexandrescu" <SeeWebsiteForEmail erdani.org> wrote in message 
news:iibuu1$123i$1 digitalmars.com...
 On 2/2/11 6:06 AM, Nick Sabalausky wrote:
 "Denis Koroskin"<2korden gmail.com>  wrote in message
 news:op.vp9wmrreo7cclz korden-pc...
 On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland
 <magnus hetland.org>  wrote:

 I think perhaps some adjustments could be made to the layout, to make 
 it
 more suitable to narrow(ish) browser windows (c.f., the discussio about
 80 columns -- without starting a huge thread like that again ;)

 For one thing, in narrow(ish) columns, ragged-right might be 
 preferable.
 Then again, it may be that the way it looks on my end isn't what's
 intended:

    http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

Left menu, Category and Function Name tables do take up about 800 pixels in width, leaving very little space for Description on small resolution displays, mostly because of the large font size used and identifiers as long as "largestPartialIntersectionWeighted". While there is little we can do with identifier names, I believe font size could be reduced by about 30% without sacrificing readability. At least in Opera the page looks well even at 70% scale.

Actually, I think a smaller font improves the readability on that page. Left as it is, I would always hit "decrease font" two or three times in my browser before reading. (And that's even not counting the layout problems the current font size causes.)

OK, for now I removed everything fixing the font size from the css. Take a look.

Not quite ideal IMHO, but definitely a *lot* better. I'd be happy with it.
 I also agree with what others said about needing a better visual boundary
 between the different descriptions.

I'll look into this. I saw arguments against alternating colors. Also, horizontal lines throughout would be ugly. More ideas would be welcome.

I think it would work ok if each description were at least 3 lines on average, but yea, with them mostly being one or two lines (esp. one line) it does get noisy. I'd try adding extra spacing before and after the line, and *if* the line still looks noisy I'd try ripping out the line and just go with the extra spacing. It's not actually all that bad as it is, though. I could certainly live with it and get used to it. Big improvement over just not having the line like before.
 Only other thing I could bring up is that I'm really not as much a fan of
 justified text as Andrei. But I can live with it fine, of course, just as
 I've been doing (and I don't want to start a "left-aligned" vs 
 "justified"
 bikeshed war).

Yah, it sometimes does look a bit forced. I'd need to add hyphenation to make justified text look good.

I'm not sure how much that would work in this case, since each "paragraph" is fairly short and there doesn't seem to be much that would be hyphenatable. As it is, I'm getting a lot of rather huge space characters: http://www.semitwist.com/download/phobosAlgoScreenshot.png FWIW, doing one "decrease font" click in FF2 (I have no idea how much that decreases it by) fixes the ultra-large spaces, and puts the font size at what I would consider ideal (although there's probably a number of people who would find that too small.)
Feb 02 2011
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 7:00 AM, spir wrote:
 On 02/02/2011 12:24 PM, Denis Koroskin wrote:
 On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland
 <magnus hetland.org> wrote:

 I think perhaps some adjustments could be made to the layout, to make
 it more
 suitable to narrow(ish) browser windows (c.f., the discussio about 80
 columns
 -- without starting a huge thread like that again ;)

 For one thing, in narrow(ish) columns, ragged-right might be
 preferable. Then
 again, it may be that the way it looks on my end isn't what's intended:

 http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

Left menu, Category and Function Name tables do take up about 800 pixels in width, leaving very little space for Description on small resolution displays, mostly because of the large font size used and identifiers as long as "largestPartialIntersectionWeighted". While there is little we can do with identifier names, I believe font size could be reduced by about 30% without sacrificing readability. At least in Opera the page looks well even at 70% scale.

(Absolute) font size does not belong to the page designer, instead to the user. Just press dedicated key binding (often ctrl-), or whatever command to set it appropriately.

I'm not sure about that. Facebook's site is professionally designed and I think they use fixed font sizes all over the place. Andrei
Feb 02 2011
next sibling parent reply =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Andrei Alexandrescu wrote:
=20
 I'm not sure about that. Facebook's site is professionally designed and=

 I think they use fixed font sizes all over the place.
=20

Jerome --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Feb 02 2011
next sibling parent reply David Nadlinger <see klickverbot.at> writes:
On 2/2/11 10:03 PM, spir wrote:
 On 02/02/2011 09:40 PM, "Jérôme M. Berger" wrote:
 Andrei Alexandrescu wrote:
 I'm not sure about that. Facebook's site is professionally designed and
 I think they use fixed font sizes all over the place.

Jerome

Sure, setting absolute sizes and such was what web-designers used to do before the first html/CSS tutorial was published?

No, it's what designers do if they are actual designers. Having text size entirely determined by the user is a noble idea for a web page consisting entirely of freely reflowable text, but as a matter of fact, there is much more to a web page today, and much more to what people expect from website design. Setting font size, line height and element dimensions in pixels is the only option if you want an at least somewhat consistent user experience across multiple devices (and their default values). If an user dislikes the designer's choices, they might always use the zoom controls on their browser to adjust the site to their liking (and browsers have gotten pretty good at resizing nowadays). David
Feb 02 2011
parent reply David Nadlinger <see klickverbot.at> writes:
On 2/2/11 11:34 PM, David Nadlinger wrote:
 Setting font size, line height and element dimensions in pixels is the
 only option if you want an at least somewhat consistent user experience […]

Okay, I guess that should rather be »the most reasonable option if you want an at least somewhat consistent user experience…«. I know well that standards-minded web developers used to strongly advocate using relative sizes not too long ago, but in my perception, things have changed since that. Anyway, regardless of what's used as a base for font size, you'll probably always need to modify the zoom level on some sites out there. For example, Andrei's copy of the cutting-edge Phobos docs appears way to big with standard Chromium font size settings on my screen, but if I turned it down globally in browser preferences, Wikipedia would now be too small – they use 0.8em font size for body copy… David
Feb 02 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 5:20 PM, David Nadlinger wrote:
 On 2/2/11 11:34 PM, David Nadlinger wrote:
 Setting font size, line height and element dimensions in pixels is the
 only option if you want an at least somewhat consistent user
 experience […]

Okay, I guess that should rather be »the most reasonable option if you want an at least somewhat consistent user experience…«. I know well that standards-minded web developers used to strongly advocate using relative sizes not too long ago, but in my perception, things have changed since that. Anyway, regardless of what's used as a base for font size, you'll probably always need to modify the zoom level on some sites out there. For example, Andrei's copy of the cutting-edge Phobos docs appears way to big with standard Chromium font size settings on my screen, but if I turned it down globally in browser preferences, Wikipedia would now be too small – they use 0.8em font size for body copy… David

It is also my perception that many of today's sites choose their own fonts and font sizes. Do we have a person with experience who could tell us what to do about font sizes? Andrei
Feb 02 2011
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
Jérôme M. Berger wrote:
 Andrei Alexandrescu wrote:
 I'm not sure about that. Facebook's site is professionally designed and
 I think they use fixed font sizes all over the place.


Apple's SDK documentation on their web site is literally painful for me to read. The light grey on white coupled with small font is awful. For a company focussed on design, I don't understand this.
Feb 02 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 09:40 PM, "Jérôme M. Berger" wrote:
 Andrei Alexandrescu wrote:
 I'm not sure about that. Facebook's site is professionally designed and
 I think they use fixed font sizes all over the place.

Jerome

Sure, setting absolute sizes and such was what web-designers used to do before the first html/CSS tutorial was published? denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 02/02/2011 10:59 AM, Andrei Alexandrescu wrote:
 (Absolute) font size does not belong to the page designer, instead to
 the user. Just press dedicated key binding (often ctrl-), or whatever
 command to set it appropriately.

I'm not sure about that. Facebook's site is professionally designed and I think they use fixed font sizes all over the place.

There are tons of "professionally designed" big name sites all over the web that use fixed-font sizes that either look terribly small or terribly large, comparatively. Don't you experience this yourself? The whole idea is just wrong. People browse the web in all kinds of default font sizes, screen resolutions, and preferred browser width. Your web page should flow naturally to whatever the user has.
Feb 02 2011
next sibling parent reply David Nadlinger <see klickverbot.at> writes:
On 2/3/11 6:06 AM, Jeff Nowakowski wrote:
 The whole idea is just wrong. People browse the web in all kinds of
 default font sizes, […]

Yet I'd guess that 99% of all people on the web have never touched their browsers default font size/style controls… David
Feb 02 2011
parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 02/03/2011 12:26 AM, David Nadlinger wrote:
 Yet I'd guess that 99% of all people on the web have never touched their
 browsers default font size/style controls…

Then let them get the defaults. Do you think designers know better? They can't, because every screen and browser window comes in arbitrary resolutions and sizes. What the designers do is pick something that looks good for them, and if they're /really/ "professional", they'll assume some "standard" screen real-estate is available and design the page as if the user was browsing at that. More likely they'll just try to please the managers.
Feb 03 2011
parent reply David Nadlinger <see klickverbot.at> writes:
On 2/3/11 4:06 PM, Jeff Nowakowski wrote:
 What the designers do is pick something that looks good for them, and if
 they're /really/ "professional", they'll assume some "standard" screen
 real-estate is available and design the page as if the user was browsing
 at that.

 More likely they'll just try to please the managers.

Sorry, I don't quite get your point there. Of course there is the standard 960px desktop viewport to target, and typical mobile device dimensions are getting more and more important as well. It's part of delivering a good job to make sure that your work looks splendid at the few »standard« configurations, and not too bad on the rest. Where is the contradiction? And what does »pleasing the managers« have to do with that? I just wanted to point out that using relative font sizes has hardly any intrinsic advantages to just specifying sizes in pixels (zoom controls work for both). You just have to specify *everything* using one method, if you want to have a consistent, layout glitch-free experience for your users – and in the end, pixels often make your life easier because you tend to be dealing with stuff for which pixels are the native unit of measurement. [1] David [1] By the way, the situation is getting considerably better with the advance of CSS3 and web fonts, since you'll be able to go without pixel graphics for design elements a lot more.
Feb 03 2011
parent Jeff Nowakowski <jeff dilacero.org> writes:
On 02/03/2011 11:54 AM, David Nadlinger wrote:
 Sorry, I don't quite get your point there. Of course there is the
 standard 960px desktop viewport to target, and typical mobile device
 dimensions are getting more and more important as well. It's part of
 delivering a good job to make sure that your work looks splendid at the
 few »standard« configurations, and not too bad on the rest. Where is the
 contradiction? And what does »pleasing the managers« have to do with that?

What 960 pixel "standard"? Who the hell decided that? Who even knows how large a pixel is on my monitor, or my preferred browser width, or what font settings I might be using either due to preference or poor eyesight? Laptop screens, desktop monitors, and mobile devices come in a dizzying array of sizes and resolutions. The "standard" used to be 800x600 back in the 90s. The idea was idiotic then, and it's idiotic now. There are no standard display sizes on the web. The whole idea is trying to force-fit a print design mindset onto a medium that was explicitly designed to not have one.
 I just wanted to point out that using relative font sizes has hardly any
 intrinsic advantages to just specifying sizes in pixels (zoom controls
 work for both).

Using pixels means it's much more likely that somebody is going to have to manually adjust the zoom. Also, fixing the amount of content you're going to display based on pixels, instead of properly flowing, is broken when the client's resolution doesn't match your chosen "standard". They will either get too much content or not enough, and zooming won't help.
Feb 03 2011
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 11:06 PM, Jeff Nowakowski wrote:
 On 02/02/2011 10:59 AM, Andrei Alexandrescu wrote:
 (Absolute) font size does not belong to the page designer, instead to
 the user. Just press dedicated key binding (often ctrl-), or whatever
 command to set it appropriately.

I'm not sure about that. Facebook's site is professionally designed and I think they use fixed font sizes all over the place.

There are tons of "professionally designed" big name sites all over the web that use fixed-font sizes that either look terribly small or terribly large, comparatively. Don't you experience this yourself? The whole idea is just wrong. People browse the web in all kinds of default font sizes, screen resolutions, and preferred browser width. Your web page should flow naturally to whatever the user has.

Someone mentioned in this thread that leaving all font sizes to default causes the text to be too small. The rhetoric is convincing but I'm afraid it can't be properly translated into reality. Andrei
Feb 02 2011
next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Andrei:

 Someone mentioned in this thread that leaving all font sizes to default 
 causes the text to be too small.
 
 The rhetoric is convincing but I'm afraid it can't be properly 
 translated into reality.

There's a step between fixed font sizes and no information about font sizes at all: relative sizes (-1, -2, etc). Bye, bearophile
Feb 03 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/3/11 4:24 AM, bearophile wrote:
 Andrei:

 Someone mentioned in this thread that leaving all font sizes to default
 causes the text to be too small.

 The rhetoric is convincing but I'm afraid it can't be properly
 translated into reality.

There's a step between fixed font sizes and no information about font sizes at all: relative sizes (-1, -2, etc). Bye, bearophile

That is used but I don't think it helps choosing something that works well for everyone. Andrei
Feb 03 2011
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-02-03 07:21, Andrei Alexandrescu wrote:
 On 2/2/11 11:06 PM, Jeff Nowakowski wrote:
 On 02/02/2011 10:59 AM, Andrei Alexandrescu wrote:
 (Absolute) font size does not belong to the page designer, instead to
 the user. Just press dedicated key binding (often ctrl-), or whatever
 command to set it appropriately.

I'm not sure about that. Facebook's site is professionally designed and I think they use fixed font sizes all over the place.

There are tons of "professionally designed" big name sites all over the web that use fixed-font sizes that either look terribly small or terribly large, comparatively. Don't you experience this yourself? The whole idea is just wrong. People browse the web in all kinds of default font sizes, screen resolutions, and preferred browser width. Your web page should flow naturally to whatever the user has.

Someone mentioned in this thread that leaving all font sizes to default causes the text to be too small.

Is there a minimum font size to set?
 The rhetoric is convincing but I'm afraid it can't be properly
 translated into reality.


 Andrei

-- /Jacob Carlborg
Feb 03 2011
prev sibling parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 02/03/2011 01:21 AM, Andrei Alexandrescu wrote:
 Someone mentioned in this thread that leaving all font sizes to default
 causes the text to be too small.

 The rhetoric is convincing but I'm afraid it can't be properly
 translated into reality.

It doesn't matter *what* you choose, somebody will complain it is too small or too large. That doesn't mean that some choices aren't better than others. Going by default size and making the fonts relative to that is the way to go, assuming smaller sizes are justified to squeeze in text to cramped spaces. Large blocks of text descriptions should be at the default size. Then if somebody complains about that, tell them to fix their defaults instead of imposing their monitor and browser settings on the rest of the Internet.
Feb 03 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/3/11 9:11 AM, Jeff Nowakowski wrote:
 On 02/03/2011 01:21 AM, Andrei Alexandrescu wrote:
 Someone mentioned in this thread that leaving all font sizes to default
 causes the text to be too small.

 The rhetoric is convincing but I'm afraid it can't be properly
 translated into reality.

It doesn't matter *what* you choose, somebody will complain it is too small or too large. That doesn't mean that some choices aren't better than others. Going by default size and making the fonts relative to that is the way to go, assuming smaller sizes are justified to squeeze in text to cramped spaces. Large blocks of text descriptions should be at the default size. Then if somebody complains about that, tell them to fix their defaults instead of imposing their monitor and browser settings on the rest of the Internet.

Apparently at least for one person choosing the default makes the text too large. Making the default smaller in turn makes Wikipedia text too small. I wouldn't want to require a change of defaults to see our website or to compete with Wikipedia :o). Andrei
Feb 03 2011
next sibling parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 02/03/2011 11:09 AM, Andrei Alexandrescu wrote:
 Apparently at least for one person choosing the default makes the text
 too large. Making the default smaller in turn makes Wikipedia text too
 small.

 I wouldn't want to require a change of defaults to see our website or to
 compete with Wikipedia :o).

Can't you see the ridiculous of this argument? You are talking about the problems of one person, and then comparing it to one site. I feel like you completely ignored what I said. So go ahead and change it to fixed. I'll now complain it doesn't work for me. Will you then change it back?
Feb 03 2011
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/3/11 11:02 AM, Jeff Nowakowski wrote:
 On 02/03/2011 11:09 AM, Andrei Alexandrescu wrote:
 Apparently at least for one person choosing the default makes the text
 too large. Making the default smaller in turn makes Wikipedia text too
 small.

 I wouldn't want to require a change of defaults to see our website or to
 compete with Wikipedia :o).

Can't you see the ridiculous of this argument? You are talking about the problems of one person, and then comparing it to one site. I feel like you completely ignored what I said. So go ahead and change it to fixed. I'll now complain it doesn't work for me. Will you then change it back?

I guess you're right. Anyhow, the site is up with hyphenation fixed (checked on Chrome, probably works in Konqueror too). Andrei
Feb 03 2011
prev sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Thursday, February 03, 2011 11:22:14 Andrei Alexandrescu wrote:
 On 2/3/11 11:02 AM, Jeff Nowakowski wrote:
 On 02/03/2011 11:09 AM, Andrei Alexandrescu wrote:
 Apparently at least for one person choosing the default makes the text
 too large. Making the default smaller in turn makes Wikipedia text too
 small.
 
 I wouldn't want to require a change of defaults to see our website or to
 compete with Wikipedia :o).

Can't you see the ridiculous of this argument? You are talking about the problems of one person, and then comparing it to one site. I feel like you completely ignored what I said. So go ahead and change it to fixed. I'll now complain it doesn't work for me. Will you then change it back?

I guess you're right. Anyhow, the site is up with hyphenation fixed (checked on Chrome, probably works in Konqueror too).

Confirmed. It looks fine in Konqueror now. Overall, the table at the top makes things look much nicer. - Jonathan M Davis
Feb 03 2011
prev sibling parent reply =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Andrei Alexandrescu wrote:
 On 2/3/11 9:11 AM, Jeff Nowakowski wrote:
 On 02/03/2011 01:21 AM, Andrei Alexandrescu wrote:
 Someone mentioned in this thread that leaving all font sizes to defau=



 causes the text to be too small.

 The rhetoric is convincing but I'm afraid it can't be properly
 translated into reality.

It doesn't matter *what* you choose, somebody will complain it is too small or too large. That doesn't mean that some choices aren't better than others. Going by default size and making the fonts relative to th=


 is the way to go, assuming smaller sizes are justified to squeeze in
 text to cramped spaces.

 Large blocks of text descriptions should be at the default size. Then =


 somebody complains about that, tell them to fix their defaults instead=


 of imposing their monitor and browser settings on the rest of the
 Internet.

Apparently at least for one person choosing the default makes the text too large. Making the default smaller in turn makes Wikipedia text too small. =20

font size set to 80% of the default, which means that they *want* their text to be too small. That is not a reason why we should emulate them. Jerome --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Feb 03 2011
parent reply David Nadlinger <see klickverbot.at> writes:
On 2/3/11 6:42 PM, "Jérôme M. Berger" wrote:
 	That is because Wikipedia text *is* to small! Wikipedia has the
 font size set to 80% of the default, which means that they *want*
 their text to be too small. That is not a reason why we should
 emulate them.

This is exactly the issue I was talking about, using relative font sizes in their current incarnation doesn't solve any problems per se. Also, it's precisely the point where one's ideal conceptions and reality differ. Just imagine what would happen if Wikipedia used a font-size of 1: Millions of users would complain that the body copy is way too large for something encyclopedic in nature. In the end, web development is not about constructing an ideal(istic) world, but about catering end user needs. If you can unite the two goals, that's great, but ignoring reality usually doesn't quite work out well… David
Feb 03 2011
parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 02/03/2011 06:15 PM, David Nadlinger wrote:
 This is exactly the issue I was talking about, using relative font
 sizes in their current incarnation doesn't solve any problems per
 se.

It does, as I explained in my other post to you. Repeating an assertion is not a logical argument.
 Also, it's precisely the point where one's ideal conceptions and
 reality differ. Just imagine what would happen if Wikipedia used a
 font-size of 1: Millions of users would complain that the body copy
 is way too large for something encyclopedic in nature.

Imagine if they used a font-size of 1 and hardly anybody complained. You just made up some crazy number. I'd like to know exactly why Wikipedia chose the font size they did. I looked around and couldn't find any reason for it. They did at one time do a usability study, but it didn't mention anything about font sizes. I'm willing to bet this decision was poorly made by scant evidence and personal preference of a few.
 In the end, web development is not about constructing an ideal(istic)
 world, but about catering end user needs. If you can unite the two
 goals, that's great, but ignoring reality usually doesn't quite work
 out well…

Exactly so, but the problem is that a certain set of web designers have fooled themselves into a fantasy that they have actually come to some practical solution by settling on "standard" pixel sizes, when they have chosen a solution that cannot work and fails in practice. At least when you use default sizes and flow layout it works in a usable manner, meaning zoom works properly and the text should be at a readable size. It also allows for an approach where at least a user has a standard way to display their preferred font size by default instead of by the whims of some designer who treats the web as a print medium.
Feb 04 2011
parent reply David Nadlinger <see klickverbot.at> writes:
On 2/4/11 4:39 PM, Jeff Nowakowski wrote:
 It does, as I explained in my other post to you. Repeating an assertion
 is not a logical argument.

I tried to explain the issue to you, but you have been quick to dismiss any attempt to do so based on your own opinion. I won't spend any more time on this fruitless discussion, but I can only suggest you to set out and try to design/implement a few non-trivial websites yourself, closely listening to user feedback. Maybe you'll come up with a revolutionary new solution for the problems that will inevitably pop up, but maybe you'll also discover that the designers of the most frequented sites aren't exactly complete dorks either. David
Feb 04 2011
parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 02/04/2011 11:38 AM, David Nadlinger wrote:
 I tried to explain the issue to you, but you have been quick to
 dismiss any attempt to do so based on your own opinion.

You've made silly arguments about opinion yourself, stating that a million Wikipedia users would complain if the default font setting was used. That was what you came up instead of responding to a detailed argument from me. Pure intellectual laziness. You've completely ignored the problems of the variety of real-world resolutions, monitor sizes, and preferred font sizes. You've ignored the problems caused by designs that do not flow, especially as it relates to zoom. You've ignored the fact that relative fonts and flow layout do not have this problem. You're advocating that people's explicit preferences should be ignored in favor of designers who think the Web should act as a print medium. You've ignored the fact that the Web was explicitly designed to not be such a medium, and in practice cannot be due to the myriad of devices connected to it.
 maybe you'll also discover that the designers of the most frequented
 sites aren't exactly complete dorks either.

I've seen tons of designs by high-profile sites, and many are pointlessly broken for me. I've seen them redesigned after having been in a workable state and then made broken by an obsession of pixel-based layout. The problem is these designers are control-freaks and don't understand the Web.
Feb 04 2011
parent reply =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Jeff Nowakowski wrote:
 On 02/04/2011 11:38 AM, David Nadlinger wrote:
 maybe you'll also discover that the designers of the most frequented
 sites aren't exactly complete dorks either.

I've seen tons of designs by high-profile sites, and many are pointlessly broken for me. I've seen them redesigned after having been in a workable state and then made broken by an obsession of pixel-based=

 layout. The problem is these designers are control-freaks and don't
 understand the Web.

Plus, very often there are two categories of =E2=80=9Cdesigners=E2=80=9D= working on these sites. The first do not know anything about the web and create a mockup of the site using Photoshop, then the others (who do know at least some html+css, or at least Dreamweaver) are required by their managers (who know even less than the first category) to match the Photoshop design exactly on the manager's computer. The easiest (or even only) way to do that is to set all dimensions in pixels. And the result is something that ranges from bad to horrible for most other people. Jerome PS: Yes, I know, this probably does not apply to wikipedia but I am pretty sure it applies to most =E2=80=9Cprofessional=E2=80=9D web sites. --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Feb 04 2011
parent "Nick Sabalausky" <a a.a> writes:
""Jrme M. Berger"" <jeberger free.fr> wrote in message 
news:iiht66$vnt$1 digitalmars.com...
 Plus, very often there are two categories of "designers" working on
 these sites. The first do not know anything about the web and create
 a mockup of the site using Photoshop, then the others (who do know
 at least some html+css, or at least Dreamweaver) are required by
 their managers (who know even less than the first category) to match
 the Photoshop design exactly on the manager's computer.

A related pet peeve: This situation wouldn't even happen if the world wasn't so full of "yes"-men. (And note that outside of fiction, most "yes"-men don't realize they're "yes"-men). In an ideal world (ie, fat chance of this happening - I know) the people who actually do know better would explain to the manager that that method is bullshit (not in such words, of course). This would force the manager to do one of three things: Either pull his head out of his ass, or shoot his worker turnover sky-high by firing everyone that comes along (and thus drive the company into the ground), or drive the company into the ground directly by only ever hiring people who really don't know what they're doing (and then get a government bailout, etc, etc...) But everyone just looks out for "#1", even if that means holding on to a job that's a piss-poor one to begin with. So the ignorant/incompetent managers remain ignorant, incompetent and employed, and all their workers and customers (and the rest of the damn world, for that matter) have to suffer for it.
 The easiest
 (or even only) way to do that is to set all dimensions in pixels.
 And the result is something that ranges from bad to horrible for
 most other people.

Feb 04 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/03/2011 06:19 AM, Walter Bright wrote:
 Jérôme M. Berger wrote:
 Andrei Alexandrescu wrote:
 I'm not sure about that. Facebook's site is professionally designed and
 I think they use fixed font sizes all over the place.


Apple's SDK documentation on their web site is literally painful for me to read. The light grey on white coupled with small font is awful. For a company focussed on design, I don't understand this.

You can probably fix that by setting personal bg/fg colors in your browser, and stating they should override the original page's colors. Using firefox (probably others have similar feature) one can even write a whole CSS style sheet for web page rendering. (*) I nearly never navigate letting page original colors, because of white backgrounds. Sometimes it's necessary when part of the text is actually kinds of B-on-W images (like math formulas on wikipedia). Denis (*) I use it mainly because Mozilla apps (firefox & thunderbird in my case) do not correctly follow system style settings; which I desperately need to change mainly to avoid white backgrounds everywhere, but this change implies changing /all/ other colors. -- _________________ vita es estrany spir.wikidot.com
Feb 03 2011
prev sibling parent spir <denis.spir gmail.com> writes:
On 02/03/2011 04:11 PM, Jeff Nowakowski wrote:
 On 02/03/2011 01:21 AM, Andrei Alexandrescu wrote:
 Someone mentioned in this thread that leaving all font sizes to default
 causes the text to be too small.

 The rhetoric is convincing but I'm afraid it can't be properly
 translated into reality.

It doesn't matter *what* you choose, somebody will complain it is too small or too large. That doesn't mean that some choices aren't better than others. Going by default size and making the fonts relative to that is the way to go, assuming smaller sizes are justified to squeeze in text to cramped spaces. Large blocks of text descriptions should be at the default size. Then if somebody complains about that, tell them to fix their defaults instead of imposing their monitor and browser settings on the rest of the Internet.

+++ (that's how I understand the issue as well, virulence apart) A particular point is when you need a rather wide horizontal space, like in the initial design of the cheat sheet. This is to be avoided as much as possible because layout will be broken by people using narrow/low resolution devices or needing larger fonts than you have in mind or just test with. In all cases, I guess the proper method is to avoid setting absolute widths (or implicitely requiring big ones via layout design such in the case of the cheat sheet) and just let content flow, according to user-side /actual/ width. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 03 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 12:24 PM, Denis Koroskin wrote:
 On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland <magnus hetland.org>
wrote:

 I think perhaps some adjustments could be made to the layout, to make it more
 suitable to narrow(ish) browser windows (c.f., the discussio about 80 columns
 -- without starting a huge thread like that again ;)

 For one thing, in narrow(ish) columns, ragged-right might be preferable. Then
 again, it may be that the way it looks on my end isn't what's intended:

 http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

Left menu, Category and Function Name tables do take up about 800 pixels in width, leaving very little space for Description on small resolution displays, mostly because of the large font size used and identifiers as long as "largestPartialIntersectionWeighted". While there is little we can do with identifier names, I believe font size could be reduced by about 30% without sacrificing readability. At least in Opera the page looks well even at 70% scale.

(Absolute) font size does not belong to the page designer, instead to the user. Just press dedicated key binding (often ctrl-), or whatever command to set it appropriately. But I agree a page's structure should avoid /requiring/ to much width just to be corrctly displayed; and thus /force/ users to scale text down. Very "unnice" to people with sight problems (not my case, but...). Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 5:06 AM, Magnus Lie Hetland wrote:
 I think perhaps some adjustments could be made to the layout, to make it
 more suitable to narrow(ish) browser windows (c.f., the discussio about
 80 columns -- without starting a huge thread like that again ;)

Yah, the irony! :o)
 For one thing, in narrow(ish) columns, ragged-right might be preferable.
 Then again, it may be that the way it looks on my end isn't what's
 intended:

 http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

This is a problem indeed. Andrei
Feb 02 2011
parent reply Magnus Lie Hetland <magnus hetland.org> writes:
On 2011-02-02 16:40:15 +0100, Andrei Alexandrescu said:

 On 2/2/11 5:06 AM, Magnus Lie Hetland wrote:
 I think perhaps some adjustments could be made to the layout, to make it
 more suitable to narrow(ish) browser windows (c.f., the discussio about
 80 columns -- without starting a huge thread like that again ;)

Yah, the irony! :o)

:D
 For one thing, in narrow(ish) columns, ragged-right might be preferable.
 Then again, it may be that the way it looks on my end isn't what's
 intended:
 
 http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

This is a problem indeed.

The current version looks quite a bit better. However, it seems like the hyphenation has gone a bit haywire. Just look at the categories, function names etc. now... http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png It does seem like slightly smaller text would help in general, but there are so many ideas/opinions flying around -- I'll just leave it up to you ;) -- Magnus Lie Hetland http://hetland.org
Feb 02 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 2:15 PM, Magnus Lie Hetland wrote:
 On 2011-02-02 16:40:15 +0100, Andrei Alexandrescu said:

 On 2/2/11 5:06 AM, Magnus Lie Hetland wrote:
 I think perhaps some adjustments could be made to the layout, to make it
 more suitable to narrow(ish) browser windows (c.f., the discussio about
 80 columns -- without starting a huge thread like that again ;)

Yah, the irony! :o)

:D
 For one thing, in narrow(ish) columns, ragged-right might be preferable.
 Then again, it may be that the way it looks on my end isn't what's
 intended:

 http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png

This is a problem indeed.

The current version looks quite a bit better. However, it seems like the hyphenation has gone a bit haywire. Just look at the categories, function names etc. now... http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png It does seem like slightly smaller text would help in general, but there are so many ideas/opinions flying around -- I'll just leave it up to you ;)

The png seems to refer to an older version with three columns. No? Andrei
Feb 02 2011
prev sibling next sibling parent reply spir <denis.spir gmail.com> writes:
On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

Waow! This is a great leap forward on the way to clear, useful, & welcoming documentation. Thank you very much :-) On the other hand, it lets me wonder about Phobos organisation: many of those funcs apply on ranges, right? Thus, why are they not in std.range? Why define types on one hand, their functionality on the other? The consequence is, when importing std.range, one also must import std.algo in most cases (and often std.functional, std.typecons,...). One problem is most of those algos apply on other kinds of sequences or "iterable" collections as well (arrays, sets, trees...): shouldn't there be kinds of supertypes or interfaces? Another problem is std.range already is over-populated; which may raise other kinds of questions. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 6:40 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

Waow! This is a great leap forward on the way to clear, useful, & welcoming documentation. Thank you very much :-) On the other hand, it lets me wonder about Phobos organisation: many of those funcs apply on ranges, right? Thus, why are they not in std.range? Why define types on one hand, their functionality on the other? The consequence is, when importing std.range, one also must import std.algo in most cases (and often std.functional, std.typecons,...). One problem is most of those algos apply on other kinds of sequences or "iterable" collections as well (arrays, sets, trees...): shouldn't there be kinds of supertypes or interfaces? Another problem is std.range already is over-populated; which may raise other kinds of questions. Denis

std.algorithm implements what's traditionally considered an "algorithm", a process. std.range implements range paraphernalia. A notable exception is that binary search algorithms are in std.range because they belong to a specialized range. I'm not sure how to improve on this. Andrei
Feb 02 2011
prev sibling next sibling parent reply spir <denis.spir gmail.com> writes:
On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 7:07 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis

Probably one table per category would make for too many tables. How about the separating rows in http://d-programming-language.org/cutting-edge/phobos/std_container.html? Andrei
Feb 02 2011
next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 08:41 PM, Denis Koroskin wrote:
 On Wed, 02 Feb 2011 19:00:20 +0300, Andrei Alexandrescu
 <SeeWebsiteForEmail erdani.org> wrote:

 On 2/2/11 7:07 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis

Probably one table per category would make for too many tables. How about the separating rows in http://d-programming-language.org/cutting-edge/phobos/std_container.html? Andrei

FWIW, in Opera there is also a huge gap (about 1000 pixels in height) between the table and its summary (http://habreffect.ru/files/940/18dbd8cbb/bug.png). It is most like Opera specific, but I'm not sure. That gap is coming from lots of empty paragraphs (<p></p>) in between table rows: <tr> ... </tr> <p></p> <tr> ... </tr> I think it won't hurt to remove those as unnecessary.

They don't appear in firefox rendering by me. (But are well in source.) Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 1:41 PM, Denis Koroskin wrote:
 On Wed, 02 Feb 2011 19:00:20 +0300, Andrei Alexandrescu
 <SeeWebsiteForEmail erdani.org> wrote:

 On 2/2/11 7:07 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html


 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis

Probably one table per category would make for too many tables. How about the separating rows in http://d-programming-language.org/cutting-edge/phobos/std_container.html? Andrei

FWIW, in Opera there is also a huge gap (about 1000 pixels in height) between the table and its summary (http://habreffect.ru/files/940/18dbd8cbb/bug.png). It is most like Opera specific, but I'm not sure. That gap is coming from lots of empty paragraphs (<p></p>) in between table rows: <tr> ... </tr> <p></p> <tr> ... </tr> I think it won't hurt to remove those as unnecessary.

Yah, that needs fixing. Unfortunately it makes a mess of the source as the empty line in between rows made it easy for me to follow and easy for emacs to wrap rows properly (at 80 columns, heh). Andrei
Feb 02 2011
prev sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 05:00 PM, Andrei Alexandrescu wrote:
 On 2/2/11 7:07 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis

Probably one table per category would make for too many tables. How about the separating rows in http://d-programming-language.org/cutting-edge/phobos/std_container.html?

Just what was needed, I guess. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 02:07 PM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?).

PS: The latter solution also brings the following opportunity: a line of pointers to category (tables) at top of page. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent reply "Simen kjaeraas" <simen.kjaras gmail.com> writes:
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:

 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names  
 and a brief description. Let me know of any feedback. Thanks!

Much better. However, for not-so-wide monitors (i'm on 1280x1024 atm, can't wait till I get a new one), it would be much nicer if the categories were put in a row above the functions. The way it is, a single word is eating space for 48 words on my screen. -- Simen
Feb 02 2011
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 8:34 AM, Simen kjaeraas wrote:
 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:

 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!

Much better. However, for not-so-wide monitors (i'm on 1280x1024 atm, can't wait till I get a new one), it would be much nicer if the categories were put in a row above the functions. The way it is, a single word is eating space for 48 words on my screen.

Alright. Again, I'm thinking of something a la http://d-programming-language.org/cutting-edge/phobos/std_container.html. Works? Andrei
Feb 02 2011
prev sibling parent reply Magnus Lie Hetland <magnus hetland.org> writes:
On 2011-02-02 16:01:29 +0100, Andrej Mitrovic said:

 Yay! Glad to see this being incorporated in the website.
 
 Btw, about the fonts:
 I think this is a bug with the cutting-edge site only. The fonts
 appear bigger, but they'll end up being smaller on the dmars website.
 See:
 
 http://i.imgur.com/7nfzz.jpg

Ahah! Then I guess squashing that bug would be useful, before fretting any more about horizontal real-estate :) -- Magnus Lie Hetland http://hetland.org
Feb 02 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 2:16 PM, Magnus Lie Hetland wrote:
 On 2011-02-02 16:01:29 +0100, Andrej Mitrovic said:

 Yay! Glad to see this being incorporated in the website.

 Btw, about the fonts:
 I think this is a bug with the cutting-edge site only. The fonts
 appear bigger, but they'll end up being smaller on the dmars website.
 See:

 http://i.imgur.com/7nfzz.jpg

Ahah! Then I guess squashing that bug would be useful, before fretting any more about horizontal real-estate :)

I fixed it by removing any absolute font sizes from std.ddoc. Andrei
Feb 02 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
Yay! Glad to see this being incorporated in the website.

Btw, about the fonts:
I think this is a bug with the cutting-edge site only. The fonts
appear bigger, but they'll end up being smaller on the dmars website.
See:

http://i.imgur.com/7nfzz.jpg
Feb 02 2011
prev sibling next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu Wrote:
 There are two tables, one with just the names and the other with names 
 and a brief description. Let me know of any feedback. Thanks!

Did you decide on a manually maintained table or is it auto generated? I do really think adding a Tags: section, or perhaps just putting groups under the See_Also: section is a good way to do the grouping. The mini examples might be good as a new section too, one that can be hidden in the big docs, but available to the jump table. Also a few notes: a) I really like a fixed width for the links, so it forms a neat grid. My eyes just see a blob of links when it's a list... b) The <a name=""> anchors in the page are repeated in a lot of cases, meaning the links may go to the wrong place. I suggest tweaking ddoc to make them fully qualified (at least inside the module, for example, "#OpenRight.yes" instead of "#yes"). c) I think I agree with the others that the Category header eats a bit too much horizontal space, but it isn't a big deal to me. I'm working on my own little tweaks to the system concurrently. I like your version a lot more than mine right now, but still think we can do a little better... if I have time today in between my other work, I'll see about adding my ideas here to my version so you can see them in practice.
Feb 02 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 9:08 AM, Adam Ruppe wrote:
 Andrei Alexandrescu Wrote:
 There are two tables, one with just the names and the other with
 names and a brief description. Let me know of any feedback.
 Thanks!

Did you decide on a manually maintained table or is it auto generated? I do really think adding a Tags: section, or perhaps just putting groups under the See_Also: section is a good way to do the grouping.

For now it's manual; I had to write the actual text which was the bulk anyway. Long term we'll need to look at generating the table by adding category tags to each function/class etc.
 The mini examples might be good as a new section too, one that can be
 hidden in the big docs, but available to the jump table.

Not getting this.
 Also a few notes:

 a) I really like a fixed width for the links, so it forms a neat
 grid. My eyes just see a blob of links when it's a list...

That would really hurt e.g. set operations.
 b) The<a name="">  anchors in the page are repeated in a lot of
 cases, meaning the links may go to the wrong place. I suggest
 tweaking ddoc to make them fully qualified (at least inside the
 module, for example, "#OpenRight.yes" instead of "#yes").

Yah, how did you pull that trick in your generated jump table?
 c) I think I agree with the others that the Category header eats a
 bit too much horizontal space, but it isn't a big deal to me.

I'll probably change that.
 I'm working on my own little tweaks to the system concurrently. I
 like your version a lot more than mine right now, but still think we
 can do a little better... if I have time today in between my other
 work, I'll see about adding my ideas here to my version so you can
 see them in practice.

Awesome! Andrei
Feb 02 2011
next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu wrote:
 For now it's manual; I had to write the actual text which was the bulk
 anyway. Long term we'll need to look at generating the table by adding
 category tags to each function/class etc.

Right. I now think the best way to do it is something like this: Macros: WIKI = Phobos/StdAlgorithm TAG = <a href="#$1" class="tag">$1</a> /** map!"2 * a"([1, 2, 3]) lazily returns a range with the numbers 2, 4, 6. Implements the homonym function (also known as $(D transform)) present [... snip all unmodified existing content ...] See_also: $(TAG Iteration) */ Then, the function tags are grouped in a pretty logical place, and have enough decoration in the HTML that we can easily parse them out before or after. The helper program would search all links with the tag class and figure out what function they belong to. With that, it generates the categorization tables. Alternatively, it could use a "Tags:" instead of "See_also:". I also moved the brief description from the table to the first line of the ddoc. The ddoc spec already describes the first paragraph as being a summary, with the following paragraphs as a separate description <http://digitalmars.com/d/2.0/ddoc.html>, so we're just leveraging that existing definition. Now, when the table is generated, it can go through and pull the first paragraph out of each ddoc section and put it in the summary table. Alternatively, we add a new section, say, "Briefly": /** Implements the homonym function (also known as $(D transform)) present [... snip all unmodified existing content ...] Briefly: map!"2 * a"([1, 2, 3]) lazily returns a range with the numbers 2, 4, 6. See_also: $(TAG Iteration) */ And the helper program pulls that out for the table. The result might look something like this: http://arsdnet.net/d-web-site/algorithm.html (I only played with map() there and dmd -D'd it, so nothing fancy).
 Not getting this.

What I mean there is the above "Briefly:" section.
 That would really hurt e.g. set operations.

Yeah. Oh well.
Feb 02 2011
parent Adam Ruppe <destructionator gmail.com> writes:
 Same principle may even be the default for
 most modules, don't you think?

Indeed. It also lets us automatically generate stuff off the existing files. Here's my first go at automated tables: http://arsdnet.net/d-web-site/std_algorithm2.html I only tagged the map function in the std.algorithm source. http://arsdnet.net/d-web-site/algorithm.d (Using the ($TAG) macro described in a last post) The program to do the automation is here: http://arsdnet.net/d-web-site/improveddoc.d It needs my dom module, here: http://arsdnet.net/d-web-site/arsd/dom.d If you want the Phobos html to work, you need to fix std.ddoc. BIGOH = <b><i>&Omicron;</i>(</b>$(D $0)<b><i>)</i></b> Is the new line. (The old one had terribly butchered html and broke even my dom's tag soup fixer...)
Feb 02 2011
prev sibling parent "Nick Sabalausky" <a a.a> writes:
"Andrei Alexandrescu" <SeeWebsiteForEmail erdani.org> wrote in message 
news:iibvgn$13bt$1 digitalmars.com...
 On 2/2/11 9:08 AM, Adam Ruppe wrote:
 a) I really like a fixed width for the links, so it forms a neat
 grid. My eyes just see a blob of links when it's a list...

That would really hurt e.g. set operations.

I have the same problem. Maybe if it was just fixed-width *per* section?
Feb 02 2011
prev sibling next sibling parent "Simen kjaeraas" <simen.kjaras gmail.com> writes:
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:

 On 2/2/11 8:34 AM, Simen kjaeraas wrote:
 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:

 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!

Much better. However, for not-so-wide monitors (i'm on 1280x1024 atm, can't wait till I get a new one), it would be much nicer if the categories were put in a row above the functions. The way it is, a single word is eating space for 48 words on my screen.

Alright. Again, I'm thinking of something a la http://d-programming-language.org/cutting-edge/phobos/std_container.html. Works?

Absolutely. -- Simen
Feb 02 2011
prev sibling next sibling parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 02.02.2011 09:45, schrieb Andrei Alexandrescu:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I like it. It's much easier to find the right function. I don't understand why cmp, equal, isSorted, ... are in the "Mutations" category. It makes sense for bringToFront, initializeAll, swap etc, though. Maybe a "Analyzation" category would make sense for the former? Cheers, - Daniel
Feb 02 2011
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 10:05 AM, Daniel Gibson wrote:
 Am 02.02.2011 09:45, schrieb Andrei Alexandrescu:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I like it. It's much easier to find the right function. I don't understand why cmp, equal, isSorted, ... are in the "Mutations" category. It makes sense for bringToFront, initializeAll, swap etc, though. Maybe a "Analyzation" category would make sense for the former? Cheers, - Daniel

That's a mistake; I must have been tired because my plan was to put cmp, equal, isSorted under their own category called "comparison". In fact I could swear I did that, but I can't find that text. I might have cut it and forgot to paste... :o) Will fix a bit later. Andrei
Feb 02 2011
parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 02.02.2011 17:20, schrieb Andrei Alexandrescu:
 On 2/2/11 10:05 AM, Daniel Gibson wrote:
 Am 02.02.2011 09:45, schrieb Andrei Alexandrescu:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I like it. It's much easier to find the right function. I don't understand why cmp, equal, isSorted, ... are in the "Mutations" category. It makes sense for bringToFront, initializeAll, swap etc, though. Maybe a "Analyzation" category would make sense for the former? Cheers, - Daniel

That's a mistake; I must have been tired because my plan was to put cmp, equal, isSorted under their own category called "comparison". In fact I could swear I did that, but I can't find that text. I might have cut it and forgot to paste... :o) Will fix a bit later. Andrei

Ok :) What about min, max and such?
Feb 02 2011
parent Daniel Gibson <metalcaedes gmail.com> writes:
Am 02.02.2011 17:22, schrieb Daniel Gibson:
 Am 02.02.2011 17:20, schrieb Andrei Alexandrescu:
 On 2/2/11 10:05 AM, Daniel Gibson wrote:
 Am 02.02.2011 09:45, schrieb Andrei Alexandrescu:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html


 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I like it. It's much easier to find the right function. I don't understand why cmp, equal, isSorted, ... are in the "Mutations" category. It makes sense for bringToFront, initializeAll, swap etc, though. Maybe a "Analyzation" category would make sense for the former? Cheers, - Daniel

That's a mistake; I must have been tired because my plan was to put cmp, equal, isSorted under their own category called "comparison". In fact I could swear I did that, but I can't find that text. I might have cut it and forgot to paste... :o) Will fix a bit later. Andrei

Ok :) What about min, max and such?

ok, there seems to be no "and such", but I just realized that min and max are missing in the upper table.
Feb 02 2011
prev sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 05:05 PM, Daniel Gibson wrote:
 I don't understand why cmp, equal, isSorted, ... are in the "Mutations"
category.

what about an 'information' category? I use that word to categorise type functionality when there are numerous methods, seems to work fine. Typically '==', cmp, contains, count, indexOf... fall into this category. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 04:55 PM, Andrei Alexandrescu wrote:
 I also agree with what others said about needing a better visual boundary
 between the different descriptions.

I'll look into this. I saw arguments against alternating colors. Also, horizontal lines throughout would be ugly.

Agreed.
  More ideas would be welcome.

Wouldn't 0.1 or 0.2 em vertical spacing do the job? denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 05:44 PM, Adam Ruppe wrote:
 I also moved the brief description from the table to the first
 line of the ddoc. The ddoc spec already describes the first paragraph
 as being a summary, with the following paragraphs as a separate
 description<http://digitalmars.com/d/2.0/ddoc.html>, so we're
 just leveraging that existing definition.

I think that's just the-right-thing. Same principle may even be the default for most modules, don't you think? Thus allowing to generate summary tables of module functionality close to the top of generated html pages. This would also encourage authors writing sensible (first-line) summaries, properly telling the /purpose/ of each feature. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, February 02, 2011 00:45:59 Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at
 
 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html
 
 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!

Definitely an improvement and looks good overall, but I really don't think that you should try to center the function names. It looks bad and makes them harer to read IMHO. If you're going to justify them at all, I'd suggest left justify. - Jonathan M Davis
Feb 02 2011
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I made one more pass and made the following changes: * Added thin horizontal rules (you might have seen this already) * Added "Comparison" category * Reduced columns to two in the cheat sheet table and used leading rows for distinguishing categories * Added hyphenation, which should make justice to the justified style (watch it at work in a narrow window!) Let me know how it looks! Andrei
Feb 02 2011
next sibling parent "Simen kjaeraas" <simen.kjaras gmail.com> writes:
On Wed, 02 Feb 2011 20:12:07 +0100, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I made one more pass and made the following changes: * Added thin horizontal rules (you might have seen this already) * Added "Comparison" category * Reduced columns to two in the cheat sheet table and used leading rows for distinguishing categories * Added hyphenation, which should make justice to the justified style (watch it at work in a narrow window!) Let me know how it looks!

Much better! I vote this for official style. -- Simen
Feb 02 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/02/2011 08:12 PM, Andrei Alexandrescu wrote:
 On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I made one more pass and made the following changes: * Added thin horizontal rules (you might have seen this already) * Added "Comparison" category * Reduced columns to two in the cheat sheet table and used leading rows for distinguishing categories * Added hyphenation, which should make justice to the justified style (watch it at work in a narrow window!) Let me know how it looks!

Looks very good by me (even with my custom colors, but also watched with original ones). A single detail: You should not use hyphenation in the top (simple) table, else it will cut function names, like mismatch in: ...findSplitAfter findSplitBefore indexOf minCount minPos mis- match skipOver startsWith until... Thank you for this work, Andrei. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, February 02, 2011 11:12:07 Andrei Alexandrescu wrote:
 On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at
 
 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html
 
 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!
 
 
 Andrei

I made one more pass and made the following changes: * Added thin horizontal rules (you might have seen this already) * Added "Comparison" category * Reduced columns to two in the cheat sheet table and used leading rows for distinguishing categories * Added hyphenation, which should make justice to the justified style (watch it at work in a narrow window!) Let me know how it looks!

Aside from the category column, it looks great. However, the hyphenated category column looks horrible. The only one that manages to put its whole name on one line is Sorting. All of the others get split up onto 2 or 3 lines and become almost illegible. There's _tons_ of room for the Functions column in comparison. Unless you really think that there are going to be screens that are so small that they can't even fit all of the function names in there by listing them in a single line vertically (i.e. so small that there isn't enough space to horizontally place the longest function name), I would strongly suggest having the category column take up one line for each name rather than trying to hyphenate it. At most, split up Set Operations onto two lines, with Set on one line and Operations on the second. The hyphenating looks horrible and is hard to read. I see no reason to make the category column worry about space so much. I would expect the functions column to be able to handle the width adjustment for various screen sizes. Screenshot: http://is.gd/J51l9r - Jonathan M Davis
Feb 02 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/2/11 7:24 PM, Jonathan M Davis wrote:
 On Wednesday, February 02, 2011 11:12:07 Andrei Alexandrescu wrote:
 On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I made one more pass and made the following changes: * Added thin horizontal rules (you might have seen this already) * Added "Comparison" category * Reduced columns to two in the cheat sheet table and used leading rows for distinguishing categories * Added hyphenation, which should make justice to the justified style (watch it at work in a narrow window!) Let me know how it looks!

Aside from the category column, it looks great. However, the hyphenated category column looks horrible. The only one that manages to put its whole name on one line is Sorting. All of the others get split up onto 2 or 3 lines and become almost illegible. There's _tons_ of room for the Functions column in comparison. Unless you really think that there are going to be screens that are so small that they can't even fit all of the function names in there by listing them in a single line vertically (i.e. so small that there isn't enough space to horizontally place the longest function name), I would strongly suggest having the category column take up one line for each name rather than trying to hyphenate it. At most, split up Set Operations onto two lines, with Set on one line and Operations on the second. The hyphenating looks horrible and is hard to read. I see no reason to make the category column worry about space so much. I would expect the functions column to be able to handle the width adjustment for various screen sizes. Screenshot: http://is.gd/J51l9r - Jonathan M Davis

Wow, Konqueror has a pretty bad layout engine wrt soft hyphenation. Hyphenating has a high penalty and should only occur when otherwise things would be really ugly. I'll setup the table such that the first column is not hyphenated. Andrei
Feb 02 2011
prev sibling next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
Andrei wrote:
 I made one more pass and made the following changes:

I downloaded your new style to my site too and ran the automatic table generator over std.stdio so we can see how it looks with some different content. http://arsdnet.net/d-web-site/std_stdio.html I actually like that quite a bit! I don't have the hyphenation script, so that won't work, but the rest is there. As a side note, I want to do a huge battery of changes to std.ddoc so it puts out nicer semantic html. I'll try it on my private copy first. If all goes well, it won't change the appearance at all and will let my helper programs (and others like them, if any exist) do a much better job. The current ddoc macros used there really undersell its capabilities IMO.
Feb 02 2011
parent Adam D. Ruppe <destructionator gmail.com> writes:
spir wrote:
 Is there an easy way to avoid duplicates in cheat sheet (2 readln, 3 writeln)?

Yes, easily, done now. http://arsdnet.net/d-web-site/std_stdio.html
 * The pointer to readln points ~ 3 lines below readln's doc's headline.

Fixed via hackish. The real cause here is ddoc for some reason outputs the <a name> anchors all over the place, almost at random, and with repeated names... it's partially useful, but could be a lot more. My program runs through all of them, removing the ones that look useless and renaming the others, so direct links work correctly, even to things like enums with repeated names. (for example: http://arsdnet.net/d-web-site/std_stdio.html#File.readln vs http://arsdnet.net/d-web-site/std_stdio.html#readln works there. But on the real site: http://d-programming-language.org/phobos/std_stdio.html#readln It just goes to the first reference of the name, which, in this case, is wrong - it goes to the struct member instead of the global that was asked for.) The ideal situation is probably to fix up the ddoc macros so it outputs the right thing in the first place. Maybe I'll find the cause when I look at std.ddoc later in the week.
Feb 02 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/03/2011 02:24 AM, Jonathan M Davis wrote:
 The hyphenating looks horrible and is hard to
 read. I see no reason to make the category column worry about space so much. I
 would expect the functions column to be able to handle the width adjustment for
 various screen sizes.

 Screenshot:http://is.gd/J51l9r

Nothing like that by me; screenshot: http://spir.wdfiles.com/local--files/variety/Screenshot-1.png Actually, all looks rather nice now, imo, with latest settings. The second table (in firefox, light on dark colors): http://spir.wdfiles.com/local--files/variety/Screenshot-2.png Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling parent spir <denis.spir gmail.com> writes:
On 02/03/2011 03:20 AM, Adam Ruppe wrote:
 I downloaded your new style to my site too and ran the automatic
 table generator over std.stdio so we can see how it looks with
 some different content.

 http://arsdnet.net/d-web-site/std_stdio.html

 I actually like that quite a bit! I don't have the hyphenation
 script, so that won't work, but the rest is there.

I think such evolutation becoming standard for stdlib doc is a big gain. Just this cheat sheet table with a few words on /purpose/ of each feature helps much in (re)discovering a module. Two notes: * Is there an easy way to avoid duplicates in cheat sheet (2 readln, 3 writeln)? * The pointer to readln points ~ 3 lines below readln's doc's headline. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 02 2011
prev sibling next sibling parent "Denis Koroskin" <2korden gmail.com> writes:
On Wed, 02 Feb 2011 19:00:20 +0300, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 On 2/2/11 7:07 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis

Probably one table per category would make for too many tables. How about the separating rows in http://d-programming-language.org/cutting-edge/phobos/std_container.html? Andrei

It looks great! One thing I don't like is that complexity sometimes gets split into 2 lines with huge spaces before and after asterisk (tested in Opera and Chrome): nr * log nc Either increased column width or <nobr> could probably help.
Feb 02 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 2/2/11, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 * Added hyphenation, which should make justice to the justified style
 (watch it at work in a narrow window!)

It even copies text properly when there's a hyphen. Nice.
Feb 02 2011
prev sibling next sibling parent "Denis Koroskin" <2korden gmail.com> writes:
On Wed, 02 Feb 2011 19:00:20 +0300, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 On 2/2/11 7:07 AM, spir wrote:
 On 02/02/2011 09:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a
 brief description. Let me know of any feedback. Thanks!


 Andrei

To avoid the descriptive table taking to much width, as evoked, remove the category column by: * Putting category names as "inter-lines" (dunno how to code that in html, but there's certainly a way to do it). * Making one table per category (simpler and nicer?). Denis

Probably one table per category would make for too many tables. How about the separating rows in http://d-programming-language.org/cutting-edge/phobos/std_container.html? Andrei

FWIW, in Opera there is also a huge gap (about 1000 pixels in height) between the table and its summary (http://habreffect.ru/files/940/18dbd8cbb/bug.png). It is most like Opera specific, but I'm not sure. That gap is coming from lots of empty paragraphs (<p></p>) in between table rows: <tr> ... </tr> <p></p> <tr> ... </tr> I think it won't hurt to remove those as unnecessary.
Feb 02 2011
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-02-02 09:45, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!


 Andrei

I think the font looks kind of weird, at least on Mac OS X. The font for the "intro text" looks fine. In the description column, I think the text that is the actual function call should have a different style from the rest of the text. Probably some other color or something like that. -- /Jacob Carlborg
Feb 02 2011
prev sibling next sibling parent =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at
=20
 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.htm=

=20
 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!
=20

the snippet calls "find" instead of "canFind". Jerome --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Feb 02 2011
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, February 02, 2011 17:37:27 Andrei Alexandrescu wrote:
 On 2/2/11 7:24 PM, Jonathan M Davis wrote:
 On Wednesday, February 02, 2011 11:12:07 Andrei Alexandrescu wrote:
 On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
 Following ideas and advice from this newsgroup, I have a draft at
 
 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.htm
 l
 
 There are two tables, one with just the names and the other with names
 and a brief description. Let me know of any feedback. Thanks!
 
 
 Andrei

I made one more pass and made the following changes: * Added thin horizontal rules (you might have seen this already) * Added "Comparison" category * Reduced columns to two in the cheat sheet table and used leading rows for distinguishing categories * Added hyphenation, which should make justice to the justified style (watch it at work in a narrow window!) Let me know how it looks!

Aside from the category column, it looks great. However, the hyphenated category column looks horrible. The only one that manages to put its whole name on one line is Sorting. All of the others get split up onto 2 or 3 lines and become almost illegible. There's _tons_ of room for the Functions column in comparison. Unless you really think that there are going to be screens that are so small that they can't even fit all of the function names in there by listing them in a single line vertically (i.e. so small that there isn't enough space to horizontally place the longest function name), I would strongly suggest having the category column take up one line for each name rather than trying to hyphenate it. At most, split up Set Operations onto two lines, with Set on one line and Operations on the second. The hyphenating looks horrible and is hard to read. I see no reason to make the category column worry about space so much. I would expect the functions column to be able to handle the width adjustment for various screen sizes. Screenshot: http://is.gd/J51l9r - Jonathan M Davis

Wow, Konqueror has a pretty bad layout engine wrt soft hyphenation. Hyphenating has a high penalty and should only occur when otherwise things would be really ugly. I'll setup the table such that the first column is not hyphenated.

Chrome looks pretty much the same (though for some reason it shows almost none of the hyphens). Of course, they are cousins, since Konqueror uses KHTML and Chrome uses Webkit, which was forked from KHTML. Regardless, even if Konqueror were considered unimportant (which, fortunately, was not your reaction), the fact that Chrome has the problem would make it so that it was still something that needed to be addressed (since Chrome certainly doesn't have a small user base). - Jonathan M Davis
Feb 02 2011
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, February 02, 2011 18:27:34 spir wrote:
 On 02/03/2011 02:24 AM, Jonathan M Davis wrote:
 The hyphenating looks horrible and is hard to
 read. I see no reason to make the category column worry about space so
 much. I would expect the functions column to be able to handle the width
 adjustment for various screen sizes.
 
 Screenshot:http://is.gd/J51l9r

Nothing like that by me; screenshot: http://spir.wdfiles.com/local--files/variety/Screenshot-1.png Actually, all looks rather nice now, imo, with latest settings. The second table (in firefox, light on dark colors): http://spir.wdfiles.com/local--files/variety/Screenshot-2.png

Evidently, Gecko handles the hyphenated stuff better than KHTML or Webkit. - Jonathan M Davis
Feb 02 2011
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 02 Feb 2011 03:45:59 -0500, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html

 There are two tables, one with just the names and the other with names  
 and a brief description. Let me know of any feedback. Thanks!

This looks *much* better. One curiosity, on Opera, the "Cheat Sheet" title is separated from the actual table by a full page of white space. Not sure why. Firefox looks fine. -Steve
Feb 03 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 02/03/2011 05:05 PM, Andrei Alexandrescu wrote:
 There's a step between fixed font sizes and no information about font sizes
 at all: relative sizes (-1, -2, etc).

 Bye,
 bearophile

That is used but I don't think it helps choosing something that works well for everyone.

This cannot be done. Just design with 'content flow' and 'relative sizes' in mind. Then everything should look correct on the user-side; except for wished absolute content size (which depends on a set of uncontrollable factors from resolution to eye-sight), which the user can freely set via a variety of UI commands. Denis -- _________________ vita es estrany spir.wikidot.com
Feb 03 2011
prev sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 2/2/11, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 Following ideas and advice from this newsgroup, I have a draft at

 http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html
 Andrei

You know, we could use the same thing for the language reference. E.g.: http://www.digitalmars.com/d/2.0/template.html We could have a table at the top linking to these sections: Explicit Template Instantiation Instantiation Scope Argument Deduction Template Type Parameters Specialization Template This Parameters Template Value Parameters Template Alias Parameters Template Tuple Parameters Template Parameter Default Values Implicit Template Properties Template Constructors Class Templates Struct, Union, and Interface Templates Function Templates Function Templates with Auto Ref Parameters Recursive Templates Template Constraints Limitations That is a lot of sections, and they're not being linked to right now so they're hard to find without a search.
Feb 11 2011