subject:"Improved Phobos dox"

On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu 
wrote:

What's a good small circular central bullet for HTML?


·

Re: Improved Phobos dox


On 2013-09-16 18:22, Andrei Alexandrescu wrote:


[citation needed]


http://en.wikipedia.org/wiki/Semantic_HTML


On the contrary, from what I've read in LaTeX and typography is that you
want to keep formatting semantics high level, e.g. "This is a chapter
title" as opposed to "this is heading text" or (worse) "this is large
text with large spacing".


This is not LaTeX. When using the proper tags you're adding semantic 
meaning to your content. Example, a proper table with an header and 
footer should look like this:



  

  Header
  Header 2

  

  

  Footer data
  Footer data 2

  

  

  Data
  Data 2

  


The reason for adding proper tags like "thead", "tfoot" and "tbody" is 
it gives semantic meaning to the content. A browser can choose to scroll 
the content in "tbody" while having the content in "thead" and "tfoot".


The same idea can be applied to navigation as well. Using the "nav" tag 
a browser could probably choose to scroll the main content and but not 
the content of the "nav" tag.



It is, but it seems to me the more specific "list of symbols introduced"
is better.


Then you add a class in addition to the correct tag.


In this case the distinction is actually material because we have one
style file for both Phobos and the larger dlang.org, and we may want to
format regular  differently from Phobos symbols description. This
seems to be a Good Thing (tm).


Then you use different classes, but still uses the correct tag.

Another example. If you want to emphasis text one uses the "em" tag, not 
the "i" tag. The it's up to the style sheet (CSS) to decide if the 
emphasized text should be italic, bold or some other font.


It's the same thing why one should use the type "bool" (D, C++) instead 
of "int". It gives the correct semantic meaning.



Actually as I noted above that's an issue because we share the same
style file between dlang.org and phobos. Of course, we could have two
files, but I don't find using classes a shameful alternative.


We most likely should.

--
/Jacob Carlborg

Re: Improved Phobos dox


On 2013-09-16 18:49, Andrei Alexandrescu wrote:


For my part I prefer the minimal commitment of  - just leave it to
the style to decide how to go about things. So I have minimal hardcoding
of semantics in the generated html, and maximum flexibility in the CSS -
I can get to hide the thing altogether, or format it in ways that are
very different from classic .


It's doesn't matter if it's a  tag or a  tag. You can style 
both the same way.


We might want to add some style sheet that resets an unifies the default 
styling for all element a cross all browsers.


This is an example: http://necolas.github.io/normalize.css/

That one is used by Bootstrap and other libraries.

--
/Jacob Carlborg

Re: Improved Phobos dox


On 9/16/13 11:21 AM, Jacob Carlborg wrote:

On 2013-09-16 18:22, Andrei Alexandrescu wrote:

On the contrary, from what I've read in LaTeX and typography is that you
want to keep formatting semantics high level, e.g. "This is a chapter
title" as opposed to "this is heading text" or (worse) "this is large
text with large spacing".


This is not LaTeX. When using the proper tags you're adding semantic
meaning to your content.


Same principles apply to LaTeX. Anyhow, the discussions has been 
settled. You are right, and I got convinced.



Actually as I noted above that's an issue because we share the same
style file between dlang.org and phobos. Of course, we could have two
files, but I don't find using classes a shameful alternative.


We most likely should.


Yah, we already have separate ddoc files for the main site and for the 
library. I suspect at a point we'll segregate the css files, too. We 
haven't gotten to the necessity yet.



Andrei

Re: Improved Phobos dox


On 9/16/13 11:18 AM, Tourist wrote:

On Monday, 16 September 2013 at 18:14:23 UTC, Andrei Alexandrescu wrote:

On 9/16/13 11:08 AM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:

What's a good small circular central bullet for HTML?


·


Done, looks nice. http://erdani.com/d/phobos/std_array.html

Anyhow enough with this - it's just a patch until ddox. Somebody
please pull the blessed thing :o).


Andrei


My 2 cents: links without the underline look quite counter-intuitive.
Not that I care that much, I'd rather see ddox up and running by default.


Sure, fixed.

Andrei

Re: Improved Phobos dox

2013-09-16 Thread Tourist

On Monday, 16 September 2013 at 18:14:23 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
On Monday, 16 September 2013 at 17:59:11 UTC, Andrei 
Alexandrescu wrote:

What's a good small circular central bullet for HTML?


·


Done, looks nice. http://erdani.com/d/phobos/std_array.html

Anyhow enough with this - it's just a patch until ddox. 
Somebody please pull the blessed thing :o).



Andrei


My 2 cents: links without the underline look quite 
counter-intuitive.
Not that I care that much, I'd rather see ddox up and running by 
default.

Re: Improved Phobos dox


On 9/16/13 11:08 AM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:

What's a good small circular central bullet for HTML?


·


Done, looks nice. http://erdani.com/d/phobos/std_array.html

Anyhow enough with this - it's just a patch until ddox. Somebody please 
pull the blessed thing :o).



Andrei

Re: Improved Phobos dox


On 9/16/13 10:07 AM, H. S. Teoh wrote:

I can attest to that. I'm on another mailing list where one of the list
members is sight-impaired, and she complains about how some websites
(i.e. those that suffer from heavy divitis and spanitis) simply can't be
read in any sane way by the screen reader. Using built-in semantic tags
like  can make a world of difference for these users, since the
screen reader has no idea what class="d_decl" means, but it *does* know
what  means. I wouldn't be so quick to dismiss it.


OK I went back to dl/dt as shown in http://goo.gl/DzW2iI. However, when 
I tried to redefine DDOC_DECL_DD from


DDOC_DECL_DD   = $(DIVC d_decl_dd, $0)

to

DDOC_DECL_DD   = $(DDC d_decl_dd, $0)

I got bad rendering problems. What could be the matter? Is it because of 
nesting?



Thanks,

Andrei

Re: Improved Phobos dox


On 9/16/13 10:10 AM, H. S. Teoh wrote:

On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic wrote:

On 9/16/13, Andrei Alexandrescu  wrote:

I did it on purpose :o). I found the many adjacent underlines unsightly,
and thought that "Jump to" would be evocative enough. Rollback?


Well, it looks like one giant sentence instead of a set of links,
especially since some are capitalized and some are not. Perhaps
separate them with a bullet? E.g.:

Appender • RefAppender • appender • array • assocArray • back...

I don't know. :]


I like the idea of delimiting with bullets.


What's a good small circular central bullet for HTML?

Andrei

Re: Improved Phobos dox

2013-09-16 Thread Wyatt

On Monday, 16 September 2013 at 14:38:25 UTC, Andrei Alexandrescu 
wrote:


Which example? Are you referring to the extra spacing I added 
between symbols?


Turns out I was looking at the wrong version.  The current 
version here looks all right:

http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

Though I have numerous concerns with having comments on the doc 
pages, and ESPECIALLY using an external service for them.


-Wyatt

Re: Improved Phobos dox


On 2013-09-16 16:39, H. S. Teoh wrote:


The problem is that Walter wants DDOC to be a generic macro-expansion
system. Adding any further smarts to it would tie it down to D-specific
functionality, which reduces the likelihood of it being accepted.

But, you may be able to change his mind. :)


I just want to have good documentation for D. If Walter wants to create 
a competitor to Markdown, sure, but don't put it in D.


--
/Jacob Carlborg

Re: Improved Phobos dox

2013-09-16 Thread Brad Anderson

On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 10:10 AM, H. S. Teoh wrote:
On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic 
wrote:
On 9/16/13, Andrei Alexandrescu 
 wrote:
I did it on purpose :o). I found the many adjacent 
underlines unsightly,
and thought that "Jump to" would be evocative enough. 
Rollback?


Well, it looks like one giant sentence instead of a set of 
links,
especially since some are capitalized and some are not. 
Perhaps

separate them with a bullet? E.g.:

Appender • RefAppender • appender • array • assocArray • 
back...


I don't know. :]


I like the idea of delimiting with bullets.


What's a good small circular central bullet for HTML?

Andrei


http://www.fileformat.info/info/unicode/char/25cf/index.htm

Re: Improved Phobos dox


On 9/16/13 10:12 AM, Sönke Ludwig wrote:

Am 16.09.2013 12:45, schrieb Andrei Alexandrescu:

On 9/15/13 11:34 PM, Sönke Ludwig wrote:

I need some form of authoritative decision on how to go about making (or
not making) the transition before I can start to work on the necessary
changes to the make file and the rest of the site. There is a suggestion
I made in the pull request:

https://github.com/D-Programming-Language/dlang.org/pull/267


What other changes need to be made in addition to what's in 267 now?

Andrei


My idea was to make a proper transition from the current docs to the new
ones using a different path. Quoting from the pull:

  - Adjust the make file so that the ddox documentation goes to
"library/" and "library-prerelease/" instead of "phobos/" - leave the
original documentation there


OK, preserve existing links and migrate later, nice.


  - Keep the main documentation links pointed to "phobos/", but add a
small secondary link to "library/"


Fine for the beginning. Guess we can pull the plug in a future small diff.


  - (Optional) In the ddox documentation, add a link at the top of each
page to the corresponding old doc page


Probably not worth the trouble, but always good if easy to implement for 
making transitioning palatable.



  - Make the pull in this state


Ja.


  - Incorporate improvements for a while and eventually exchange the
links, making "library/" the default

Maybe with "api" instead of "library".

The current state is that the new docs have a separate make target that
needs to be invoked explicitly, but it will write to the same "phobos"
folder.


OK great. I'll look at it soon.


Andrei

Re: Improved Phobos dox

On Monday, 16 September 2013 at 17:08:21 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 9:56 AM, Vladimir Panteleev wrote:
Right. I think I found the source of the misunderstanding: the 
idea is
not to depend on the default formatting of  - the idea is 
to remove
the default styles using CSS, then use it like , which is 
what the

old code did.


I don't understand this paragraph.


You presented the example regarding replacing  with class="param">. We agree that this is a good change.


I understood that your argument against using  is its 
*stylistic* (not semantic) properties: by default, a  has 
additional CSS styles that are not present on  tags.


We agreed that tags that have only stylistic properties, such as 
, should not be used.  has no semantic meaning (its 
recommended replacement is , short for "emphasized", which 
has the same default stylistic properties, but now also has 
semantic meaning).


I understood that you applied the above arguments together, to 
conclude that  should not be used for the same reasons that 
that  should not be used -  has the same semantic 
properties as .


However, the difference between  and  
is that the former has semantics which the latter doesn't. (To 
clarify, by "semantics" I mean meaning that can be useful to 
user-agents reading the HTML, such as screen readers.)

Re: Improved Phobos dox

2013-09-16 Thread Adam D. Ruppe

On Monday, 16 September 2013 at 17:25:11 UTC, Vladimir Panteleev 
wrote:

You don't need to set the class to every  tag.


Yes, but since it is ddoc macros we might as well retain whatever 
information we can. It's only written once there, in the macro, 
so it isn't a big hassle anyway.

Re: Improved Phobos dox

2013-09-16 Thread Gary Willoughby


On Monday, 16 September 2013 at 04:15:43 UTC, deadalnix wrote:
On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig 
wrote:

Am 15.09.2013 19:20, schrieb Walter Bright:

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
What happened with Ddox? This looks like an improvement in 
both

function and
aesthetics:

http://vibed.org/temp/phobos/std/array.html


It doesn't document the parameters, return type, and doesn't 
recognize

embedded hyperlinks.


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html


I'm sold, that is awesome !


Me too that is much, much nicer! :D

Re: Improved Phobos dox

On Monday, 16 September 2013 at 17:16:30 UTC, Andrei Alexandrescu 
wrote:
The problem now is I need to worry about two things: class 
_and_ element. With div/span I only need to worry about 
paragraph/inline (a simpler Boolean decision) and class.


You don't need to set the class to every  tag. Since all  
tags are direct children of a  tag, you can set the class on 
the  tag, then use a CSS child selector to specify styling. 
E.g.:


HTML:
  
...
...
...

CSS:
  dl.decl_ddoc > dd {
/* styles that apply only to 
   inside a 
*/
  }

Re: Improved Phobos dox

On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic wrote:
> On 9/16/13, Andrei Alexandrescu  wrote:
> > I did it on purpose :o). I found the many adjacent underlines unsightly,
> > and thought that "Jump to" would be evocative enough. Rollback?
> 
> Well, it looks like one giant sentence instead of a set of links,
> especially since some are capitalized and some are not. Perhaps
> separate them with a bullet? E.g.:
> 
> Appender • RefAppender • appender • array • assocArray • back...
> 
> I don't know. :]

I like the idea of delimiting with bullets.


T

-- 
Perhaps the most widespread illusion is that if we were in power we
would behave very differently from those who now hold it---when, in
truth, in order to get power we would have to become very much like
them. -- Unknown

Re: Improved Phobos dox

2013-09-16 Thread Sönke Ludwig


Am 16.09.2013 12:45, schrieb Andrei Alexandrescu:

On 9/15/13 11:34 PM, Sönke Ludwig wrote:

I need some form of authoritative decision on how to go about making (or
not making) the transition before I can start to work on the necessary
changes to the make file and the rest of the site. There is a suggestion
I made in the pull request:

https://github.com/D-Programming-Language/dlang.org/pull/267


What other changes need to be made in addition to what's in 267 now?

Andrei


My idea was to make a proper transition from the current docs to the new 
ones using a different path. Quoting from the pull:


 - Adjust the make file so that the ddox documentation goes to 
"library/" and "library-prerelease/" instead of "phobos/" - leave the 
original documentation there
 - Keep the main documentation links pointed to "phobos/", but add a 
small secondary link to "library/"
 - (Optional) In the ddox documentation, add a link at the top of each 
page to the corresponding old doc page

 - Make the pull in this state
 - Incorporate improvements for a while and eventually exchange the 
links, making "library/" the default


Maybe with "api" instead of "library".

The current state is that the new docs have a separate make target that 
needs to be invoked explicitly, but it will write to the same "phobos" 
folder.

Re: Improved Phobos dox


On 9/16/13 10:02 AM, Adam D. Ruppe wrote:

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:

Now you're arguing that  is better than . This is more interesting, and I'd like to get
convinced one way or another.


The difference is the  is part of a list.  is just a division
of the webpage.

If you were using a generic program to fetch all the lists on the page,
that could find  better than it could find a . Such a generic
program might be a search engine, a screen reader, a customized browser,
or something like my old improveddoc.d program. (Though the latter,
being custom made for this site, could just use class names too.)

You lose nothing by using the most applicable tag, and gain the
potential that generic programs will understand your page better.


Weakly agreed.


BTW, you should use as many classes as possible as well. I think each
and every ddoc macro should have its own html class. Even if you never
use them in the css file, they can be useful for third party analyzer
tools. improveddoc.d used a few hacks to reconstruct some ddoc semantics
lost in the old setup - knowing that  was actually a param for
instance, so good to see that fixed.


The problem now is I need to worry about two things: class _and_ 
element. With div/span I only need to worry about paragraph/inline (a 
simpler Boolean decision) and class.



Andrei

Re: Improved Phobos dox

2013-09-16 Thread Brad Anderson

On Monday, 16 September 2013 at 17:14:01 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 10:01 AM, Brad Anderson wrote:
On Monday, 16 September 2013 at 16:49:25 UTC, Andrei 
Alexandrescu wrote:

On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
I noticed the change: dd -> div. This is bad, because it 
reduces

semantics.


The change was from unqualified  to . 
Big

difference.

Now you're arguing that  is better than . This is more interesting, and I'd like to get
convinced one way or another.

For my part I prefer the minimal commitment of  - just 
leave it
to the style to decide how to go about things. So I have 
minimal
hardcoding of semantics in the generated html, and maximum 
flexibility
in the CSS - I can get to hide the thing altogether, or 
format it in

ways that are very different from classic .

Your example is: i -> span class="param". This is good, 
because it

improves semantics.


Great.


Andrei


Why not just make every element a div with a class in that 
case?


The point of using specific elements is to get their default 
attributes "for free". Otherwise one would need to specify a 
bunch in the class definitions.


I can see how using specific elements may help the browser if 
the user alters the defaults.




The point is the semantics, not the default styling.  The default 
styling exists just to give them a sane default to work with.

Re: Improved Phobos dox


On 9/16/13 9:57 AM, Dicebot wrote:

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:

...


Sounds like you are exactly arguing over the concept of semantic web and
related tools. Which is a bit weird because it basically repeats the
debates from various web world articles I have been reading almost 5
years ago :P Maybe we should use established wisdom of people who are
doomed to deal with it on daily basis? :P


What is the established wisdom?

Andrei

Re: Improved Phobos dox


On 9/16/13 10:01 AM, Brad Anderson wrote:

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:

On 9/16/13 9:44 AM, Vladimir Panteleev wrote:

I noticed the change: dd -> div. This is bad, because it reduces
semantics.


The change was from unqualified  to . Big
difference.

Now you're arguing that  is better than . This is more interesting, and I'd like to get
convinced one way or another.

For my part I prefer the minimal commitment of  - just leave it
to the style to decide how to go about things. So I have minimal
hardcoding of semantics in the generated html, and maximum flexibility
in the CSS - I can get to hide the thing altogether, or format it in
ways that are very different from classic .


Your example is: i -> span class="param". This is good, because it
improves semantics.


Great.


Andrei


Why not just make every element a div with a class in that case?


The point of using specific elements is to get their default attributes 
"for free". Otherwise one would need to specify a bunch in the class 
definitions.


I can see how using specific elements may help the browser if the user 
alters the defaults.



There is a reason HTML 4 offered many element types and HTML 5 expanded
this even more so.  It improves code readability and has other benefits
beyond that including assisting screen readers and other accessibility
services for disabled people.

http://coding.smashingmagazine.com/2013/01/18/the-importance-of-sections/


Sections would be nice to use.


Andrei

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu
wrote:
Now you're arguing that is better than class="param">. This is more interesting, and I'd like to get
convinced one way or another.

The difference is the is part of a list. is just a
division of the webpage.

If you were using a generic program to fetch all the lists on the
page, that could find better than it could find a .
Such a generic program might be a search engine, a screen reader,
a customized browser, or something like my old improveddoc.d
program. (Though the latter, being custom made for this site,
could just use class names too.)

You lose nothing by using the most applicable tag, and gain the
potential that generic programs will understand your page better.

BTW, you should use as many classes as possible as well. I think
each and every ddoc macro should have its own html class. Even if
you never use them in the css file, they can be useful for third
party analyzer tools. improveddoc.d used a few hacks to
reconstruct some ddoc semantics lost in the old setup - knowing
that was actually a param for instance, so good to see that
fixed.

For my part I prefer the minimal commitment of - just
leave it to the style to decide how to go about things.

The stylesheet has full control of appearance regardless of the
tag. You can make a look like a rainbow circle with
invisible text on the top of the page if you want to, or make it
plain inline text. Same as , , or (almost*) anything
else.

* browser bugs might come into play but they aren't supposed to.

Re: Improved Phobos dox

2013-09-16 Thread Dicebot

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu 
wrote:

...


Sounds like you are exactly arguing over the concept of semantic 
web and related tools. Which is a bit weird because it basically 
repeats the debates from various web world articles I have been 
reading almost 5 years ago :P Maybe we should use established 
wisdom of people who are doomed to deal with it on daily basis? :P

Re: Improved Phobos dox

2013-09-16 Thread Brad Anderson

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
I noticed the change: dd -> div. This is bad, because it 
reduces semantics.


The change was from unqualified  to . 
Big difference.


Now you're arguing that  is better than class="param">. This is more interesting, and I'd like to get 
convinced one way or another.


For my part I prefer the minimal commitment of  - just 
leave it to the style to decide how to go about things. So I 
have minimal hardcoding of semantics in the generated html, and 
maximum flexibility in the CSS - I can get to hide the thing 
altogether, or format it in ways that are very different from 
classic .


Your example is: i -> span class="param". This is good, 
because it

improves semantics.


Great.


Andrei


Why not just make every element a div with a class in that case?

There is a reason HTML 4 offered many element types and HTML 5 
expanded this even more so.  It improves code readability and has 
other benefits beyond that including assisting screen readers and 
other accessibility services for disabled people.


http://coding.smashingmagazine.com/2013/01/18/the-importance-of-sections/

Re: Improved Phobos dox

On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu
wrote:

On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
I noticed the change: dd -> div. This is bad, because it
reduces semantics.

The change was from unqualified to .
Big difference.

(I assume that "param" is now used with the meaning of the
abstract value of the "class" HTML attribute, in contrast to its
previous occurrence as the literal "param" CSS class from the
example)

Now you're arguing that is better than class="param">. This is more interesting, and I'd like to get
convinced one way or another.

Is the Wikipedia link I posted earlier not applicable? I believe
it discusses why it is beneficial to use HTML tags that reflect,
or reflect closely the semantics of their contents. E.g.
instead of for navigation blocks, instead of
for addresses, and respectively instead of for
definition lists.

For my part I prefer the minimal commitment of - just
leave it to the style to decide how to go about things. So I
have minimal hardcoding of semantics in the generated html, and
maximum flexibility in the CSS - I can get to hide the thing
altogether, or format it in ways that are very different from
classic .

Right. I think I found the source of the misunderstanding: the
idea is not to depend on the default formatting of - the
idea is to remove the default styles using CSS, then use it like
, which is what the old code did.

(Apologies to everyone for, once again, blowing up a nitpick
matter into an overgrown discussion of a dozen posts.)

Re: Improved Phobos dox


On 9/16/13 8:55 AM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu wrote:

On 9/16/13 6:40 AM, Vladimir Panteleev wrote:

What before was , now is  (and the margin was
a dd style). Why this change? You can apply any properties of one to the
other through CSS.


Great, thanks. Now fixed. My intent was to use  and  for
styling ddoc elements to the extent possible, in order to make styling
as flexible as possible.


Although bordering on nitpicking, I'll mention that this is not a good
change.


I'm here to learn.


It is recommended to use the appropriate HTML elements for their
semantic meaning.


[citation needed]

On the contrary, from what I've read in LaTeX and typography is that you 
want to keep formatting semantics high level, e.g. "This is a chapter 
title" as opposed to "this is heading text" or (worse) "this is large 
text with large spacing".



 is a definition list, which nicely fits
documenting a list of entities.


It is, but it seems to me the more specific "list of symbols introduced" 
is better.


In this case the distinction is actually material because we have one 
style file for both Phobos and the larger dlang.org, and we may want to 
format regular  differently from Phobos symbols description. This 
seems to be a Good Thing (tm).



HTML5 even introduced additional HTML
tags, such as .


Even better. The more semantic the better, but actual documents always 
have their own higher-level semantics.



Styling is not a problem, since you can use CSS to
remove the default styles from practically any layout tag, making it
behave like  or .


Actually as I noted above that's an issue because we share the same 
style file between dlang.org and phobos. Of course, we could have two 
files, but I don't find using classes a shameful alternative.



If it's not too much effort, I'd revert this change, however this is
more of a question of principle than practicality.


I think this change makes things better, but am listening to arguments 
because I'm not an expert.



Andrei

Re: Improved Phobos dox

On Monday, 16 September 2013 at 16:37:06 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
If it's not too much effort, I'd revert this change, however 
this is

more of a question of principle than practicality.


One more argument in favor of using style classes.

Consider the bug you found - parameters were not styled in 
italics. (Whether or not we care to keep that particular 
formatting is a different matter.)


That format was enacted as follows:

DDOC_PARAM = $(I $0)

which expands to $0. To change that in any way, one 
would have to do surgery on some .ddoc file, rebuild, and 
upload the entire site.


Alternatively, one could, as you mentioned, restyle  in the 
css file, but then not only parameters would be restyled, but 
ALL italic text! Not good.


The new definition is:

DDOC_PARAM=$0

The current style is:

.param
{
font-style: italic;
}

Now whenever we want to change the styling of those particular 
elements (and only those), we edit the css file and upload it 
again to the site. This is very simple, economic, and modular.


This is correct and I agree. I think we misunderstood each other?

I noticed the change: dd -> div. This is bad, because it reduces 
semantics.


Your example is: i -> span class="param". This is good, because 
it improves semantics.

Re: Improved Phobos dox


On 9/16/13 9:56 AM, Vladimir Panteleev wrote:

Right. I think I found the source of the misunderstanding: the idea is
not to depend on the default formatting of  - the idea is to remove
the default styles using CSS, then use it like , which is what the
old code did.


I don't understand this paragraph.

Andrei

Re: Improved Phobos dox

On Mon, Sep 16, 2013 at 06:49:01PM +0200, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 16:44:56 UTC, Andrei Alexandrescu
> wrote:
> >I don't find disagreement with what I said.
> >[...]
> >Nice, but what I see here is "different", not "better".
> 
> I think we may be disagreeing regarding different things.
> 
> >>You could use both () if you like.
> >
> >I guess '' is one iota more specific than ' >class="d_decl">' and would help if one wanted to view the HTML
> >without any accompanying CSS. I doubt this is a goal to pursue.
> 
> I refer to my original argument about how this is
> borderline-nitpicking. I'd like to add, however, that user-agents
> such as screen readers might behave better when using appropriate
> HTML tags.

I can attest to that. I'm on another mailing list where one of the list
members is sight-impaired, and she complains about how some websites
(i.e. those that suffer from heavy divitis and spanitis) simply can't be
read in any sane way by the screen reader. Using built-in semantic tags
like  can make a world of difference for these users, since the
screen reader has no idea what class="d_decl" means, but it *does* know
what  means. I wouldn't be so quick to dismiss it.

T

-- 
It is the quality rather than the quantity that matters. -- Lucius Annaeus 
Seneca

Re: Improved Phobos dox


On 9/16/13 9:44 AM, Vladimir Panteleev wrote:

I noticed the change: dd -> div. This is bad, because it reduces semantics.


The change was from unqualified  to . Big difference.

Now you're arguing that  is better than class="param">. This is more interesting, and I'd like to get convinced 
one way or another.


For my part I prefer the minimal commitment of  - just leave it to 
the style to decide how to go about things. So I have minimal hardcoding 
of semantics in the generated html, and maximum flexibility in the CSS - 
I can get to hide the thing altogether, or format it in ways that are 
very different from classic .



Your example is: i -> span class="param". This is good, because it
improves semantics.


Great.


Andrei

Re: Improved Phobos dox


On 9/16/13 9:28 AM, Adam D. Ruppe wrote:

On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu wrote:

 is a definition list, which nicely fits
documenting a list of entities.


It is, but it seems to me the more specific "list of symbols
introduced" is better.



 or whatever


Use the closest tag name to what it is, and then put a class in there to
get more specific.


Why? To me it seems it makes no difference. Both are phrases that mean 
"this is a D declaration".


Andrei

Re: Improved Phobos dox

2013-09-16 Thread Adam D. Ruppe

On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu 
wrote:

 is a definition list, which nicely fits
documenting a list of entities.


It is, but it seems to me the more specific "list of symbols 
introduced" is better.



 or whatever


Use the closest tag name to what it is, and then put a class in 
there to get more specific.

Re: Improved Phobos dox

On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu 
wrote:

[citation needed]


Sure, here you go:

https://en.wikipedia.org/wiki/Semantic_HTML

On the contrary, from what I've read in LaTeX and typography is 
that you want to keep formatting semantics high level, e.g. 
"This is a chapter title" as opposed to "this is heading text" 
or (worse) "this is large text with large spacing".


Well, the big difference with TeX and HTML is that with *TeX, you 
distribute the output, whereas with HTML, you distribute the 
source code - which can be interpreted by user agents other than 
web browsers rendering the page on a computer display.



 is a definition list, which nicely fits
documenting a list of entities.


It is, but it seems to me the more specific "list of symbols 
introduced" is better.


You could use both () if you like.

In this case the distinction is actually material because we 
have one style file for both Phobos and the larger dlang.org, 
and we may want to format regular  differently from Phobos 
symbols description. This seems to be a Good Thing (tm).


Good thing for that C in CSS! :) If you add a class to the  
or  tag (or any other tag that wraps all symbol 
definitions), which only appears on Phobos documentation pages, 
you can create a CSS rule that only applies to those pages. E.g.:


HTML:
  
  ...
  

CSS:
  .library_dox dd {
/* applies only to dd tags in library dox pages */
  }

Re: Improved Phobos dox


On 9/16/13 8:55 AM, Vladimir Panteleev wrote:

If it's not too much effort, I'd revert this change, however this is
more of a question of principle than practicality.


One more argument in favor of using style classes.

Consider the bug you found - parameters were not styled in italics. 
(Whether or not we care to keep that particular formatting is a 
different matter.)


That format was enacted as follows:

DDOC_PARAM = $(I $0)

which expands to $0. To change that in any way, one would have to 
do surgery on some .ddoc file, rebuild, and upload the entire site.


Alternatively, one could, as you mentioned, restyle  in the css file, 
but then not only parameters would be restyled, but ALL italic text! Not 
good.


The new definition is:

DDOC_PARAM=$0

The current style is:

.param
{
font-style: italic;
}

Now whenever we want to change the styling of those particular elements 
(and only those), we edit the css file and upload it again to the site. 
This is very simple, economic, and modular.



Andrei

Re: Improved Phobos dox

On Monday, 16 September 2013 at 16:11:15 UTC, Andrei Alexandrescu 
wrote:

BTW what's the deal with all those \xNN in the javascript?

newText += '  \x3Ca class="jumpto" href="\x23.' + a +
  '"\x3E\x3Cspan class="notranslate donthyphenate"\x3E' + text 
+ '\x3C/span\x3E\x3C/a\x3E';


I guess some care must be exercised so as to not confuse the 
HTML/Javascript parser, but only for things like  and 
probablt a couple more. No?


Not sure if this is the reason that applies to our case, but - 
you can use < and > in inline scripts in HTML, but not in XHTML, 
which must be well-formed XML. The exception is if the script 
code is wrapped in a CDATA block.

Re: Improved Phobos dox

On 9/16/13 9:30 AM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu wrote:

[citation needed]

Sure, here you go:

https://en.wikipedia.org/wiki/Semantic_HTML

I don't find disagreement with what I said.

On the contrary, from what I've read in LaTeX and typography is that
you want to keep formatting semantics high level, e.g. "This is a
chapter title" as opposed to "this is heading text" or (worse) "this
is large text with large spacing".

Well, the big difference with TeX and HTML is that with *TeX, you
distribute the output, whereas with HTML, you distribute the source code
- which can be interpreted by user agents other than web browsers
rendering the page on a computer display.

is a definition list, which nicely fits
documenting a list of entities.

It is, but it seems to me the more specific "list of symbols
introduced" is better.

You could use both () if you like.

I guess '' is one iota more specific than 'class="d_decl">' and would help if one wanted to view the HTML without
any accompanying CSS. I doubt this is a goal to pursue.

In this case the distinction is actually material because we have one
style file for both Phobos and the larger dlang.org, and we may want
to format regular differently from Phobos symbols description.
This seems to be a Good Thing (tm).

Good thing for that C in CSS! :) If you add a class to the or
tag (or any other tag that wraps all symbol definitions), which
only appears on Phobos documentation pages, you can create a CSS rule
that only applies to those pages. E.g.:

HTML:

...

CSS:
.library_dox dd {
/* applies only to dd tags in library dox pages */
}

Nice, but what I see here is "different", not "better".

Andrei

Re: Improved Phobos dox

2013-09-16 Thread Andrej Mitrovic

On 9/16/13, Andrei Alexandrescu  wrote:
> I did it on purpose :o). I found the many adjacent underlines unsightly,
> and thought that "Jump to" would be evocative enough. Rollback?

Well, it looks like one giant sentence instead of a set of links,
especially since some are capitalized and some are not. Perhaps
separate them with a bullet? E.g.:

Appender • RefAppender • appender • array • assocArray • back...

I don't know. :]

Re: Improved Phobos dox

On Monday, 16 September 2013 at 16:44:56 UTC, Andrei Alexandrescu 
wrote:

I don't find disagreement with what I said.
[...]
Nice, but what I see here is "different", not "better".


I think we may be disagreeing regarding different things.


You could use both () if you like.


I guess '' is one iota more specific than 
'' and would help if one wanted to view the 
HTML without any accompanying CSS. I doubt this is a goal to 
pursue.


I refer to my original argument about how this is 
borderline-nitpicking. I'd like to add, however, that user-agents 
such as screen readers might behave better when using appropriate 
HTML tags.

Re: Improved Phobos dox


On 9/16/13 8:27 AM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 15:23:50 UTC, Andrei Alexandrescu wrote:

Yah, apologies. It's the same bug as noted by Vladimir. Fixed now.
Thanks for the feedback and keep it coming!


I'm opening these in two tabs and cycling between them:

http://dlang.org/phobos/std_array.html
http://erdani.com/d/phobos/std_array.html

One noticeable difference is that parameter names are no longer
italicized. Is that on purpose, or a missing .param style?

Looks good otherwise!


Great catch. Fixed, along with a couple other nits.

Andrei

Re: Improved Phobos dox


On 9/16/13 8:30 AM, Andrej Mitrovic wrote:

On 9/16/13, Andrei Alexandrescu  wrote:

Thanks for the feedback and keep it coming!


The links at the top of std_array.html don't have an underline for
some reason, making it hard to know they're links.


I did it on purpose :o). I found the many adjacent underlines unsightly, 
and thought that "Jump to" would be evocative enough. Rollback?



Also, the links are broken. E.g. RefAppencer points to this:
http://erdani.com/d/phobos/std_array.html#RefAppender

But that doesn't lead to anywhere. The old page linked to:

http://dlang.org/phobos/std_array.html#.RefAppender (note the dot
before RefAppender).


Blurgh. Fixed. BTW what's the deal with all those \xNN in the javascript?

newText += '  \x3Ca class="jumpto" href="\x23.' + a +
  '"\x3E\x3Cspan class="notranslate donthyphenate"\x3E' + text + 
'\x3C/span\x3E\x3C/a\x3E';


I guess some care must be exercised so as to not confuse the 
HTML/Javascript parser, but only for things like  and probablt 
a couple more. No?



Andrei

Re: Improved Phobos dox


On 9/16/13 8:34 AM, Andrej Mitrovic wrote:

On 9/16/13, Vladimir Panteleev  wrote:

One noticeable difference is that parameter names are no longer
italicized. Is that on purpose, or a missing .param style?


Personally I never liked this italicization, it doesn't make reading
the docs any simpler or easier to me.


I agree, i.e. the only thing I like about it is that whenever I see it I 
think "nice, that's customizable" :o). Destroy?


Andrei

Re: Improved Phobos dox

On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
What before was , now is  (and the 
margin was
a dd style). Why this change? You can apply any properties of 
one to the

other through CSS.


Great, thanks. Now fixed. My intent was to use  and  
for styling ddoc elements to the extent possible, in order to 
make styling as flexible as possible.


Although bordering on nitpicking, I'll mention that this is not a 
good change. It is recommended to use the appropriate HTML 
elements for their semantic meaning.  is a definition list, 
which nicely fits documenting a list of entities. HTML5 even 
introduced additional HTML tags, such as . Styling is not a 
problem, since you can use CSS to remove the default styles from 
practically any layout tag, making it behave like  or .


If it's not too much effort, I'd revert this change, however this 
is more of a question of principle than practicality.

Re: Improved Phobos dox

2013-09-16 Thread Andrej Mitrovic

On 9/16/13, Andrei Alexandrescu  wrote:
> Thanks for the feedback and keep it coming!

The links at the top of std_array.html don't have an underline for
some reason, making it hard to know they're links.

Also, the links are broken. E.g. RefAppencer points to this:
http://erdani.com/d/phobos/std_array.html#RefAppender

But that doesn't lead to anywhere. The old page linked to:

http://dlang.org/phobos/std_array.html#.RefAppender (note the dot
before RefAppender).

Re: Improved Phobos dox

2013-09-16 Thread Andrej Mitrovic

On 9/16/13, Vladimir Panteleev  wrote:
> One noticeable difference is that parameter names are no longer
> italicized. Is that on purpose, or a missing .param style?

Personally I never liked this italicization, it doesn't make reading
the docs any simpler or easier to me.

Re: Improved Phobos dox

On Mon, Sep 16, 2013 at 08:22:49AM -0700, Andrei Alexandrescu wrote:
> On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
> >What before was , now is  (and the margin was
> >a dd style). Why this change? You can apply any properties of one to the
> >other through CSS.
> 
> Great, thanks. Now fixed. My intent was to use  and  for
> styling ddoc elements to the extent possible, in order to make
> styling as flexible as possible. But I forgot to give the
> appropriate style to d_decl_dd (hopefully not others).
> 
> Destroy: http://erdani.com/d/phobos/std_array.html
[...]

OK, that looks *much* better. Thanks!


T

-- 
The volume of a pizza of thickness a and radius z can be described by the 
following formula: pi zz a. -- Wouter Verhelst

Re: Improved Phobos dox

On Monday, 16 September 2013 at 15:23:50 UTC, Andrei Alexandrescu 
wrote:
Yah, apologies. It's the same bug as noted by Vladimir. Fixed 
now. Thanks for the feedback and keep it coming!


I'm opening these in two tabs and cycling between them:

http://dlang.org/phobos/std_array.html
http://erdani.com/d/phobos/std_array.html

One noticeable difference is that parameter names are no longer 
italicized. Is that on purpose, or a missing .param style?


Looks good otherwise!

Re: Improved Phobos dox


On 9/16/13 7:43 AM, H. S. Teoh wrote:

On Mon, Sep 16, 2013 at 05:59:27AM -0700, Andrei Alexandrescu wrote:

On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a couple of
minor improvements until we land
https://github.com/D-Programming-Language/dlang.org/pull/267.

http://erdani.com/d/phobos/std_array.html

[...]

Can we pretty-please-with-a-cherry-on-top reintroduce indentation for
aggregate members? Right now, for example, RefAppender's members have no
visual distinction from module-level symbols. This pretty much makes the
docs unusable for me.


Yah, apologies. It's the same bug as noted by Vladimir. Fixed now. 
Thanks for the feedback and keep it coming!


Andrei

Re: Improved Phobos dox


On 9/16/13 6:40 AM, Vladimir Panteleev wrote:

What before was , now is  (and the margin was
a dd style). Why this change? You can apply any properties of one to the
other through CSS.


Great, thanks. Now fixed. My intent was to use  and  for 
styling ddoc elements to the extent possible, in order to make styling 
as flexible as possible. But I forgot to give the appropriate style to 
d_decl_dd (hopefully not others).


Destroy: http://erdani.com/d/phobos/std_array.html


Andrei

Re: Improved Phobos dox

On Mon, Sep 16, 2013 at 08:58:31AM +0200, Jacob Carlborg wrote:
> On 2013-09-16 06:50, H. S. Teoh wrote:
> 
> >What we need is not Yet Another Snake Oil Automagic Trick that will
> >somehow magically make it all work. What we need is to sit down and
> >put in the time to organize the module docs, grouping the symbols by
> >logical categories (which a computer can't really figure out for us,
> >unless we tag the code, which requires the same amount of effort
> >anyway). I think std.algorithm and std.range's docs are a good model
> >to follow. They set the minimum standard all Phobos docs should meet.
> >
> >Of course, we can also improve on them even more, by figuring out a
> >way to prevent the DRY violation currently in std.algorithm (to add a
> >new symbol, you now have to add it in 3 places: at the navigation
> >table at the top, then in the cheatsheet, then the actual code in the
> >module body). Maybe some kind of DDoc tag or UDA that can be
> >collected by a postprocessing script that autogenerates the relevant
> >tables based on what information is there? For example:
> >
> > // Note: not actual syntax, I just made this up for illustration
> > // purposes:
> >
> > /**
> >  * @category: searching
> >  * @cheatsheet: newHaystack = find(haystack, needle)
> >  *
> >  * Finds needle in haystack.
> >  * ...
> >  */
> > R find(R,S)(R haystack, S needle)
> > {
> > ...
> > }
> >
> >The postprocessing tool would then collect all the @category tags and
> >@cheatsheet tags and assemble a table out of them, linked to the
> >relevant symbols, and insert it at the top of the page. (Or, it could
> >even split the files up into individual pages, which we've been
> >talking about since, oh, last year?)
> 
> I think we should try and enhance the documentation generated
> automatically. Tagging and doing other things manually doesn't scale.
> This should only be used as a last option.
[...]

The problem is that Walter wants DDOC to be a generic macro-expansion
system. Adding any further smarts to it would tie it down to D-specific
functionality, which reduces the likelihood of it being accepted.

But, you may be able to change his mind. :)


T

-- 
Computers are like a jungle: they have monitor lizards, rams, mice,
c-moss, binary trees... and bugs.

Re: Improved Phobos dox

On Mon, Sep 16, 2013 at 05:59:27AM -0700, Andrei Alexandrescu wrote:
> On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
> [snip]
> 
> Got destroyed so I changed the jump-to list back, added a couple of
> minor improvements until we land
> https://github.com/D-Programming-Language/dlang.org/pull/267.
> 
> http://erdani.com/d/phobos/std_array.html
[...]

Can we pretty-please-with-a-cherry-on-top reintroduce indentation for
aggregate members? Right now, for example, RefAppender's members have no
visual distinction from module-level symbols. This pretty much makes the
docs unusable for me.

T

-- 
Marketing: the art of convincing people to pay for what they didn't need
before which you can't deliver after.

Re: Improved Phobos dox


On 9/16/13 7:30 AM, Wyatt wrote:

On Monday, 16 September 2013 at 13:33:55 UTC, Andrei Alexandrescu wrote:


Probably not. The consensus is to got the ddox way, and Walter and
myself are on board with it. We're a bit concerned about switching to
new tooling (dependencies, bus factor etc) but we think it's worth it.


Well, as long as it works (and works WELL) without Javascript, I guess
that's a fine start.  Though I have to admit the example linked above
hurts my eyes. :(  (So. Much. White.)


Which example? Are you referring to the extra spacing I added between 
symbols?


Andrei

Re: Improved Phobos dox

2013-09-16 Thread Wyatt

On Monday, 16 September 2013 at 13:33:55 UTC, Andrei Alexandrescu 
wrote:


Probably not. The consensus is to got the ddox way, and Walter 
and myself are on board with it. We're a bit concerned about 
switching to new tooling (dependencies, bus factor etc) but we 
think it's worth it.


Well, as long as it works (and works WELL) without Javascript, I 
guess that's a fine start.  Though I have to admit the example 
linked above hurts my eyes. :(  (So. Much. White.)


-Wyatt

Re: Improved Phobos dox

On Monday, 16 September 2013 at 13:32:29 UTC, Andrei Alexandrescu 
wrote:

On 9/16/13 6:08 AM, Vladimir Panteleev wrote:
On Monday, 16 September 2013 at 12:59:28 UTC, Andrei 
Alexandrescu wrote:

On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a 
couple of

minor improvements until we land
https://github.com/D-Programming-Language/dlang.org/pull/267.

http://erdani.com/d/phobos/std_array.html


What happened to the margins/padding? The assocArray example 
block

shouldn't be glued to the uninitializedArray signature.


Must have fallen through the cracks. Any chance you'd spot it 
in the pull request? I'll try the same when I'll find some time.


What before was , now is  (and the 
margin was a dd style). Why this change? You can apply any 
properties of one to the other through CSS.

Re: Improved Phobos dox


On 9/16/13 6:08 AM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu wrote:

On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a couple of
minor improvements until we land
https://github.com/D-Programming-Language/dlang.org/pull/267.

http://erdani.com/d/phobos/std_array.html


What happened to the margins/padding? The assocArray example block
shouldn't be glued to the uninitializedArray signature.


Must have fallen through the cracks. Any chance you'd spot it in the 
pull request? I'll try the same when I'll find some time.


Andrei

Re: Improved Phobos dox


On 9/16/13 6:20 AM, Wyatt wrote:

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:


Sure. My goal with this upgrade is to get rid of the unsightly bag of
words at the top of most pages.


A few months ago, I made a prototype that turned the "bag of words" into
a boxed out vertical list floating at the left.  It worked fairly well
at all sorts of browser sizes and required zero Javascript.  (It will
work even better when all the modules have introductory text as
mentioned in another thread.)

I wonder if I should resurrect that branch?

-Wyatt


Probably not. The consensus is to got the ddox way, and Walter and 
myself are on board with it. We're a bit concerned about switching to 
new tooling (dependencies, bus factor etc) but we think it's worth it.


Andrei

Re: Improved Phobos dox

2013-09-16 Thread Wyatt

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu 
wrote:


Sure. My goal with this upgrade is to get rid of the unsightly 
bag of words at the top of most pages.


A few months ago, I made a prototype that turned the "bag of 
words" into a boxed out vertical list floating at the left.  It 
worked fairly well at all sorts of browser sizes and required 
zero Javascript.  (It will work even better when all the modules 
have introductory text as mentioned in another thread.)


I wonder if I should resurrect that branch?

-Wyatt

Re: Improved Phobos dox

On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu 
wrote:

On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a 
couple of minor improvements until we land 
https://github.com/D-Programming-Language/dlang.org/pull/267.


http://erdani.com/d/phobos/std_array.html


Links in the list are currently broken, I think you need to 
prepend a ".".

Re: Improved Phobos dox

On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu 
wrote:

On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a 
couple of minor improvements until we land 
https://github.com/D-Programming-Language/dlang.org/pull/267.


http://erdani.com/d/phobos/std_array.html


What happened to the margins/padding? The assocArray example 
block shouldn't be glued to the uninitializedArray signature.

Re: Improved Phobos dox


On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a couple of 
minor improvements until we land 
https://github.com/D-Programming-Language/dlang.org/pull/267.


http://erdani.com/d/phobos/std_array.html


Andrei

Re: Improved Phobos dox

On Monday, 16 September 2013 at 10:47:25 UTC, Andrei Alexandrescu 
wrote:
Ctrl-F does not progressively adjust the list of search 
candidates - it can highlight only what's actually visible in 
the document.


If the page is property laid out, this is not an issue.

http://dump.thecybershadow.net/269d31b27d121d13ceb51dc308b89b69/0088.png
http://dump.thecybershadow.net/9b9e677a061087ef9486288eeaaccdc1/0087.png

Re: Improved Phobos dox


On 9/15/13 11:49 PM, Vladimir Panteleev wrote:

On Monday, 16 September 2013 at 01:44:34 UTC, Andrei Alexandrescu wrote:

On 9/15/13 11:25 AM, Vladimir Panteleev wrote:

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:

Vladimir, do you think you could easily implement such an incremental
search box (with autocompletion)?


Sorry, that idea does not appeal to me either. Web browsers already have
the function of searching within a page.


But search boxes with autocomplete are vastly better.


Search boxes with autocomplete are vastly better than the classical
Ctrl+F dialog as implemented in Internet Explorer 6. Most browsers
currently implement Ctrl+F as incremental search, which highlights
results as you type.


Ctrl-F does not progressively adjust the list of search candidates - it 
can highlight only what's actually visible in the document.


Andrei

Re: Improved Phobos dox


On 9/15/13 11:34 PM, Sönke Ludwig wrote:

I need some form of authoritative decision on how to go about making (or
not making) the transition before I can start to work on the necessary
changes to the make file and the rest of the site. There is a suggestion
I made in the pull request:

https://github.com/D-Programming-Language/dlang.org/pull/267


What other changes need to be made in addition to what's in 267 now?

Andrei

Re: Improved Phobos dox


On 9/15/13 9:53 PM, H. S. Teoh wrote:

On Mon, Sep 16, 2013 at 06:15:35AM +0200, deadalnix wrote:

On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:

Am 15.09.2013 19:20, schrieb Walter Bright:

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:

What happened with Ddox? This looks like an improvement in both
function and aesthetics:

http://vibed.org/temp/phobos/std/array.html


It doesn't document the parameters, return type, and doesn't
recognize embedded hyperlinks.


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html


I'm sold, that is awesome !


Me too.  Why aren't we working towards that, instead of trying to cook
up yet another hack on top of the current poor state of documentation?


https://github.com/D-Programming-Language/dlang.org/pull/271 consists 
mainly of a reorganization of the ddoc macros for PDF and ebook 
generation purposes, as well as helpers such as plaintext generator and 
"debugger". These are good starting points for anyone using ddoc for 
generating their own documentations.


I was at it so I thought I'd improve on the bag-of-words-at-the-top 
morass, too. It only took a little time. That was apparently 
unsuccessful so I'll remove it from the pull request.


https://github.com/D-Programming-Language/dlang.org/pull/267 is the pull 
request using ddox. That's a larger change of build tooling, which I 
plan to get to after 271 (with a revert to the bag-of-words) gets in.



Andrei

Re: Improved Phobos dox


On 9/15/13 11:04 AM, Walter Bright wrote:

On 9/15/2013 10:52 AM, Andrei Alexandrescu wrote:

the simpler approach of making the file and line of each symbol
available as
ddoc symbols.



I think that would make for a nice enhancement to ddoc. Enhancement
request to bugzilla?


http://d.puremagic.com/issues/show_bug.cgi?id=11050

Andrei

Re: Improved Phobos dox


On 2013-09-16 03:54, Andrei Alexandrescu wrote:


Aha, I now remember - you mentioned this once, really like it.

http://ruby-doc.org/core-1.9.3/


I forgot the link, thanks.

--
/Jacob Carlborg

Re: Improved Phobos dox


On 2013-09-16 06:50, H. S. Teoh wrote:


What we need is not Yet Another Snake Oil Automagic Trick that will
somehow magically make it all work. What we need is to sit down and put
in the time to organize the module docs, grouping the symbols by logical
categories (which a computer can't really figure out for us, unless we
tag the code, which requires the same amount of effort anyway). I think
std.algorithm and std.range's docs are a good model to follow. They set
the minimum standard all Phobos docs should meet.

Of course, we can also improve on them even more, by figuring out a way
to prevent the DRY violation currently in std.algorithm (to add a new
symbol, you now have to add it in 3 places: at the navigation table at
the top, then in the cheatsheet, then the actual code in the module
body). Maybe some kind of DDoc tag or UDA that can be collected by a
postprocessing script that autogenerates the relevant tables based on
what information is there? For example:

// Note: not actual syntax, I just made this up for illustration
// purposes:

/**
 * @category: searching
 * @cheatsheet: newHaystack = find(haystack, needle)
 *
 * Finds needle in haystack.
 * ...
 */
R find(R,S)(R haystack, S needle)
{
...
}

The postprocessing tool would then collect all the @category tags and
@cheatsheet tags and assemble a table out of them, linked to the
relevant symbols, and insert it at the top of the page. (Or, it could
even split the files up into individual pages, which we've been talking
about since, oh, last year?)


I think we should try and enhance the documentation generated 
automatically. Tagging and doing other things manually doesn't scale. 
This should only be used as a last option.


--
/Jacob Carlborg

Re: Improved Phobos dox

2013-09-15 Thread Vladimir Panteleev

On Monday, 16 September 2013 at 01:44:34 UTC, Andrei Alexandrescu 
wrote:

On 9/15/13 11:25 AM, Vladimir Panteleev wrote:
On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei 
Alexandrescu wrote:
Vladimir, do you think you could easily implement such an 
incremental

search box (with autocompletion)?


Sorry, that idea does not appeal to me either. Web browsers 
already have

the function of searching within a page.


But search boxes with autocomplete are vastly better.


Search boxes with autocomplete are vastly better than the 
classical Ctrl+F dialog as implemented in Internet Explorer 6. 
Most browsers currently implement Ctrl+F as incremental search, 
which highlights results as you type. These have the advantage 
that simply typing the term will 1) scroll down and highlight the 
term, bringing into view the symbol's documentation on a "hit", 
and 2) highlight all occurrences of the term on the visible page, 
making e.g. overloads and related symbols immediately noticeable. 
You also don't need to focus a search box immediately after 
arriving at a page.


Anyway, no reason we can't have both. The CHM build tool 
generates an index of all Phobos/Druntime symbols and D keywords, 
and I think the dman tool does something similar as well - 
perhaps it could be used for a site-wide searchbox with 
autocomplete.

Re: Improved Phobos dox

2013-09-15 Thread Sönke Ludwig


Am 16.09.2013 02:54, schrieb Walter Bright:

On 9/15/2013 11:38 AM, Sönke Ludwig wrote:

Am 15.09.2013 19:20, schrieb Walter Bright:

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:

What happened with Ddox? This looks like an improvement in both
function and
aesthetics:

http://vibed.org/temp/phobos/std/array.html


It doesn't document the parameters, return type, and doesn't recognize
embedded hyperlinks.


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html


Much better!


I need some form of authoritative decision on how to go about making (or 
not making) the transition before I can start to work on the necessary 
changes to the make file and the rest of the site. There is a suggestion 
I made in the pull request:


https://github.com/D-Programming-Language/dlang.org/pull/267

Re: Improved Phobos dox

2013-09-15 Thread Joshua Niehus


On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html


This is way better
+1

Re: Improved Phobos dox

2013-09-15 Thread H. S. Teoh

On Mon, Sep 16, 2013 at 06:15:35AM +0200, deadalnix wrote:
> On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:
> >Am 15.09.2013 19:20, schrieb Walter Bright:
> >>On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
> >>>What happened with Ddox? This looks like an improvement in both
> >>>function and aesthetics:
> >>>
> >>>http://vibed.org/temp/phobos/std/array.html
> >>
> >>It doesn't document the parameters, return type, and doesn't
> >>recognize embedded hyperlinks.
> >
> >Just as a reminder, this is the current version:
> >http://vibed.org/temp/d-programming-language.org/phobos/std/array.html
> 
> I'm sold, that is awesome !

Me too.  Why aren't we working towards that, instead of trying to cook
up yet another hack on top of the current poor state of documentation?


T

-- 
The day Microsoft makes something that doesn't suck is probably the day
they start making vacuum cleaners... -- Slashdotter

Re: Improved Phobos dox

2013-09-15 Thread H. S. Teoh

On Sun, Sep 15, 2013 at 11:40:28AM -0700, Jonathan M Davis wrote:
> On Sunday, September 15, 2013 11:02:11 Andrei Alexandrescu wrote:
> > One obvious drawback of ^F working is that all symbols are there in
> > sight.
> 
> I actually consider it a serious drawback when they're _not_ in sight.
> The problem that we have is not that all of the symbols are shown as
> links but how they're organized. Trying to hide them doesn't help.
[...]

+1.

What we need is not Yet Another Snake Oil Automagic Trick that will
somehow magically make it all work. What we need is to sit down and put
in the time to organize the module docs, grouping the symbols by logical
categories (which a computer can't really figure out for us, unless we
tag the code, which requires the same amount of effort anyway). I think
std.algorithm and std.range's docs are a good model to follow. They set
the minimum standard all Phobos docs should meet.

Of course, we can also improve on them even more, by figuring out a way
to prevent the DRY violation currently in std.algorithm (to add a new
symbol, you now have to add it in 3 places: at the navigation table at
the top, then in the cheatsheet, then the actual code in the module
body). Maybe some kind of DDoc tag or UDA that can be collected by a
postprocessing script that autogenerates the relevant tables based on
what information is there? For example:

// Note: not actual syntax, I just made this up for illustration
// purposes:

/**
 * @category: searching
 * @cheatsheet: newHaystack = find(haystack, needle)
 *
 * Finds needle in haystack.
 * ...
 */
R find(R,S)(R haystack, S needle)
{
...
}

The postprocessing tool would then collect all the @category tags and
@cheatsheet tags and assemble a table out of them, linked to the
relevant symbols, and insert it at the top of the page. (Or, it could
even split the files up into individual pages, which we've been talking
about since, oh, last year?)

T

-- 
I think the conspiracy theorists are out to get us...

Re: Improved Phobos dox

2013-09-15 Thread deadalnix


On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:

Am 15.09.2013 19:20, schrieb Walter Bright:

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
What happened with Ddox? This looks like an improvement in 
both

function and
aesthetics:

http://vibed.org/temp/phobos/std/array.html


It doesn't document the parameters, return type, and doesn't 
recognize

embedded hyperlinks.


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html


I'm sold, that is awesome !

Re: Improved Phobos dox

2013-09-15 Thread H. S. Teoh

On Sun, Sep 15, 2013 at 12:14:14AM -0700, Andrei Alexandrescu wrote:
> I finally gathered strength to rebase
> https://github.com/D-Programming-Language/dlang.org/pull/271
> manually, which was every bit as involved as I feared.
> 
> I hope I didn't mess up anything, reviews appreciated.
> 
> That diff includes a new page navigation scheme. (Wasn't the main
> purpose of the diff but found it a nice perk.) I see it as a
> transitional stage toward the larger transition to
> one-page-per-entity that Sönke has proposed.
> 
> Check out the new navigation at
> http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list
> as the top gets replaced by a slick drop-down. Once you jump to a
> name, you can go back by pressing the up arrow on the right or
> simply go to top.
[...]

Not bad. I'd suggest replacing the default selection on the "slick"
drop-down with a more helpful message, like "choose a declaration..." or
something like that, instead of just a down arrow with lots of trailing
blank space.

The one thing that I do NOT like, is the lack of indentation for
aggregate members. For example, struct Appender's members aren't
visually differentiated from other module-level symbols, which makes the
documentation VERY confusing. For reference, this is the format I use
for my own ddocs:

http://eusebeia.dyndns.org/~hsteoh/tmp/doc/mda

which are generated by the minimalistic macros here:

https://github.com/quickfur/Viola-ddoc-macros

The nesting of various identifiers are deliberately made very explicit
visually (see, for example, the docs for `struct IndexRange`), so
there's no confusion as to what symbol belongs in which aggregate. I
think this is indispensible for the docs to be useful to newbies.

T

-- 
Error: Keyboard not attached. Press F1 to continue. -- Yoon Ha Lee, CONLANG

Re: Improved Phobos dox


On 9/15/13 7:15 PM, Adam D. Ruppe wrote:

On Monday, 16 September 2013 at 01:52:38 UTC, Andrei Alexandrescu wrote:

It's not a combo box.


http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx


check out the CBS_DROPDOWNLIST style.


Ha, it is. Thanks.

Andrei

Re: Improved Phobos dox

2013-09-15 Thread Adam D. Ruppe

On Monday, 16 September 2013 at 01:52:38 UTC, Andrei Alexandrescu 
wrote:

It's not a combo box.


http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx

check out the CBS_DROPDOWNLIST style.

Or 
http://harmattan-dev.nokia.com/docs/library/html/qt4/qcombobox.html#details



BTW MSDN has something the D docs are really lacking: the 
conceptual overviews.


What are controls?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb773173%28v=vs.85%29.aspx

What options are available?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb773169%28v=vs.85%29.aspx

Big picture, what is a combo box?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb775792%28v=vs.85%29.aspx

Can you tell me more?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx

What about a complete example program?
http://msdn.microsoft.com/en-us/library/windows/desktop/hh298364%28v=vs.85%29.aspx

When I was new with Windows, half my programs were just bits of 
Microsoft examples (back then it was a .hlp file rather than a 
website though :) ) copy/pasted together. They're still useful 
today too.




Of course, D doesn't have the kind of resources Microsoft has, 
and those Windows documents were written over many years.


But we should start striving to at least offer:

1) conceptual overviews discussing the big idea and pointing to 
relevant modules. e.g. "Strings" or "Ranges". Put them right in 
the Phobos docs linked in all places like MSDN does with the 
"Related Topics" at the bottom of every page.


2) a big picture module overview on each and every one of them. 
Could just be a paragraph or two. Some already have this.


3) Collecting more full example programs. The samples directory 
in the dmd zip should be easily viewable online and open to more 
submissions. Is it on github?

Re: Improved Phobos dox


On 9/15/13 11:43 AM, Jonathan M Davis wrote:

On Sunday, September 15, 2013 10:47:06 Andrei Alexandrescu wrote:

On 9/15/13 12:53 AM, Vladimir Panteleev wrote:

On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:

Check out the new navigation at
http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
the top gets replaced by a slick drop-down. Once you jump to a name,
you can go back by pressing the up arrow on the right or simply go to
top.


I'm not sure this is an improvement, functionally. Finding the right
item in much faster when you can see all items at once, and not lined up
on only one direction.


Not sure what that's based on, but at least for me that only works up to
a few words. For large modules that's hopeless. Just look at:

http://dlang.org/phobos/std_datetime.html

Can you really pick up the desired term? I think
http://erdani.com/d/phobos/std_datetime.html is a real improvement over
that (it also reduces the size of the list to the top-level ones, which
helps).


It's an improvement because it shows the top-level symbols only rather than
putting all of the symbols inside of the types at the top level like the
current links do. The fact that it's a drop-down hurts rather than helps.

- Jonathan  Davis


Probably I'll keep that in and drop the drop-down box.

Andrei

Re: Improved Phobos dox


On 9/15/13 12:48 PM, Dicebot wrote:

On Sunday, 15 September 2013 at 19:29:56 UTC, Gary Willoughby wrote:

Agreed. Sorry Andrei but this is not an improvement for usability. It
disables being able to search the index via page search (Ctrl-F). Also
i thought combobox navigation died out in the 90's!?


+1, combo boxes are terrible


It's not a combo box.

Andrei

Re: Improved Phobos dox


On 9/15/13 1:11 PM, Jacob Carlborg wrote:

On 2013-09-15 20:25, Vladimir Panteleev wrote:

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:

Vladimir, do you think you could easily implement such an incremental
search box (with autocompletion)?


Sorry, that idea does not appeal to me either. Web browsers already have
the function of searching within a page. An in-page search box is not a
common UI element, users would need to learn to use it, and that's bad
UX - we should stick to existing UI conventions to avoid forcing the
users to think to get to their dox.


The Ruby documentation shows all core symbols (classes and methods) in
one page with two filters. I like that. It's really useful when you know
the name of the method/class you're looking for. It's also useful for
guessing names. Like, is there a method called "sort". Then you find it
you can figure out if it does what you think it will.


Aha, I now remember - you mentioned this once, really like it.

http://ruby-doc.org/core-1.9.3/


Andrei

Re: Improved Phobos dox


On 9/15/13 11:25 AM, Vladimir Panteleev wrote:

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:

Vladimir, do you think you could easily implement such an incremental
search box (with autocompletion)?


Sorry, that idea does not appeal to me either. Web browsers already have
the function of searching within a page.


But search boxes with autocomplete are vastly better.

Andrei

Re: Improved Phobos dox

2013-09-15 Thread Walter Bright


On 9/15/2013 11:38 AM, Sönke Ludwig wrote:

Am 15.09.2013 19:20, schrieb Walter Bright:

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:

What happened with Ddox? This looks like an improvement in both
function and
aesthetics:

http://vibed.org/temp/phobos/std/array.html


It doesn't document the parameters, return type, and doesn't recognize
embedded hyperlinks.


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html


Much better!

Re: Improved Phobos dox

2013-09-15 Thread F i L


Andrei Alexandrescu wrote:
Of course better designs are welcome. One possibility is an 
incremental search box.


Best solution, IMO, would be using a categorized jump-list on the 
left that scrolls separately from the actual documentation (or 
each item could have it's own page). That way you get and 
"overview at a glance" of everything in the module, regardless of 
where you are. Similar to how MSDN works.

Re: Improved Phobos dox

2013-09-15 Thread Jacob Carlborg


On 2013-09-15 09:14, Andrei Alexandrescu wrote:

I finally gathered strength to rebase
https://github.com/D-Programming-Language/dlang.org/pull/271 manually,
which was every bit as involved as I feared.

I hope I didn't mess up anything, reviews appreciated.

That diff includes a new page navigation scheme. (Wasn't the main
purpose of the diff but found it a nice perk.) I see it as a
transitional stage toward the larger transition to one-page-per-entity
that Sönke has proposed.

Check out the new navigation at
http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
the top gets replaced by a slick drop-down. Once you jump to a name, you
can go back by pressing the up arrow on the right or simply go to top.


Can't we just use something like CandyDoc. This requires JavaScript but 
it actually improves the documentation. The version used by Tango looks 
like this:


http://dsource.org/projects/tango/docs/current/

It has a tree which list all packages and modules and a different tree 
which list the symbols in a module. It also has a filter for the tree. 
Simple and useable.


--
/Jacob Carlborg

Re: Improved Phobos dox

2013-09-15 Thread Jacob Carlborg


On 2013-09-15 20:25, Vladimir Panteleev wrote:

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:

Vladimir, do you think you could easily implement such an incremental
search box (with autocompletion)?


Sorry, that idea does not appeal to me either. Web browsers already have
the function of searching within a page. An in-page search box is not a
common UI element, users would need to learn to use it, and that's bad
UX - we should stick to existing UI conventions to avoid forcing the
users to think to get to their dox.


The Ruby documentation shows all core symbols (classes and methods) in 
one page with two filters. I like that. It's really useful when you know 
the name of the method/class you're looking for. It's also useful for 
guessing names. Like, is there a method called "sort". Then you find it 
you can figure out if it does what you think it will.


--
/Jacob Carlborg

Re: Improved Phobos dox

2013-09-15 Thread Dicebot

On Sunday, 15 September 2013 at 19:29:56 UTC, Gary Willoughby 
wrote:
Agreed. Sorry Andrei but this is not an improvement for 
usability. It disables being able to search the index via page 
search (Ctrl-F). Also i thought combobox navigation died out in 
the 90's!?


+1, combo boxes are terrible

Polishing ddox is much more promising approach.

Re: Improved Phobos dox

2013-09-15 Thread Gary Willoughby

On Sunday, 15 September 2013 at 07:53:23 UTC, Vladimir Panteleev 
wrote:
On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei 
Alexandrescu wrote:
Check out the new navigation at 
http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" 
list as the top gets replaced by a slick drop-down. Once you 
jump to a name, you can go back by pressing the up arrow on 
the right or simply go to top.


I'm not sure this is an improvement, functionally. Finding the 
right item in much faster when you can see all items at once, 
and not lined up on only one direction. Also, Ctrl+F was more 
likely to find the link to the correct item before than now 
(and if you used your browser's inline search feature, then you 
could activate that link by pressing Enter).


I think some kind of outline would be more useful.

What happened with Ddox? This looks like an improvement in both 
function and aesthetics:


http://vibed.org/temp/phobos/std/array.html


Agreed. Sorry Andrei but this is not an improvement for 
usability. It disables being able to search the index via page 
search (Ctrl-F). Also i thought combobox navigation died out in 
the 90's!?


Seriously though, the navigation needs to be available no matter 
where you are on the page. For me this is a huge step backwards, 
you've effectively hidden the navigation and introduced a 
dependency on javascript.


Is there any chance some money can be spent to employ a good web 
developer to develop a nice user friendly site? IMHO the website 
really lets D down and to be honest looks very amateurish.

Re: Improved Phobos dox

2013-09-15 Thread Adam D. Ruppe

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu 
wrote:
Vladimir, do you think you could easily implement such an 
incremental search box (with autocompletion)?


One of the things that pisses me off most about facebook now is 
they hooked the / key to go into their own search, thereby 
breaking the browser's search hotkey (which i use often) and my 
expectations.


Let's let the browser do what it does and not get too smart about 
it.

Re: Improved Phobos dox

2013-09-15 Thread Andrej Mitrovic

On 9/15/13, Jonathan M Davis  wrote:
> Yeah. It feels a lot like when you can't resize a Window like Microsoft
> won't
> let you done with the dialog for setting environment variables. When I mess
> with my PATH in Windows, I typically have to copy it elsewhere, edit it, and
> copy it back.

P.S. you may want to give this app a shot:
http://www.rapidee.com/en/screenshots

Re: Improved Phobos dox

On Sunday, September 15, 2013 19:56:43 Vladimir Panteleev wrote:
> On Sunday, 15 September 2013 at 17:47:06 UTC, Andrei Alexandrescu
> 
> wrote:
> > Not sure what that's based on, but at least for me that only
> > works up to a few words. For large modules that's hopeless.
> > Just look at:
> > 
> > http://dlang.org/phobos/std_datetime.html
> > 
> > Can you really pick up the desired term? I think
> > http://erdani.com/d/phobos/std_datetime.html is a real
> > improvement over that (it also reduces the size of the list to
> > the top-level ones, which helps).
> 
> I believe that example is invalid. std.datetime is too big, as
> abundantly discussed previously. The module's documentation web
> page is over 13 pixels long (for me)!

I've got the code split into a package on my box locally, but I need to finish 
fixing the documentation before I can create a pull request for it. Once I do 
that, the blob of links won't be so bad, since it'll be split across modules. 
Unfortunately, I'm quite slow in getting the job finished though as I'm quite 
busy at the moment.

But what I think will really help deal with the blob of links for any module 
which isn't just a huge list of free functions (e.g. std.algorithm) would be 
if the links were actually hierarchical instead of treating all symbols like 
they are at the top level of the module rather than inside an enum or a struct 
or any other deeper scope.

- Jonathan M Davis

Re: Improved Phobos dox

On Sunday, September 15, 2013 10:47:06 Andrei Alexandrescu wrote:
> On 9/15/13 12:53 AM, Vladimir Panteleev wrote:
> > On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:
> >> Check out the new navigation at
> >> http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
> >> the top gets replaced by a slick drop-down. Once you jump to a name,
> >> you can go back by pressing the up arrow on the right or simply go to
> >> top.
> > 
> > I'm not sure this is an improvement, functionally. Finding the right
> > item in much faster when you can see all items at once, and not lined up
> > on only one direction.
> 
> Not sure what that's based on, but at least for me that only works up to
> a few words. For large modules that's hopeless. Just look at:
> 
> http://dlang.org/phobos/std_datetime.html
> 
> Can you really pick up the desired term? I think
> http://erdani.com/d/phobos/std_datetime.html is a real improvement over
> that (it also reduces the size of the list to the top-level ones, which
> helps).

It's an improvement because it shows the top-level symbols only rather than 
putting all of the symbols inside of the types at the top level like the 
current links do. The fact that it's a drop-down hurts rather than helps.

- Jonathan  Davis

Re: Improved Phobos dox

On Sunday, September 15, 2013 11:02:11 Andrei Alexandrescu wrote:
> One obvious
> drawback of ^F working is that all symbols are there in sight.

I actually consider it a serious drawback when they're _not_ in sight. The 
problem that we have is not that all of the symbols are shown as links but how 
they're organized. Trying to hide them doesn't help.

- Jonathan m Davis

Re: Improved Phobos dox

2013-09-15 Thread Sönke Ludwig


Am 15.09.2013 19:20, schrieb Walter Bright:

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:

What happened with Ddox? This looks like an improvement in both
function and
aesthetics:

http://vibed.org/temp/phobos/std/array.html


It doesn't document the parameters, return type, and doesn't recognize
embedded hyperlinks.


Just as a reminder, this is the current version:
http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

Re: Improved Phobos dox

2013-09-15 Thread Iain Buclaw

On 15 September 2013 19:22, Joseph Rushton Wakeling
 wrote:
> On 15/09/13 19:47, Andrei Alexandrescu wrote:
>>
>> Not sure what that's based on, but at least for me that only works up to a
>> few
>> words. For large modules that's hopeless. Just look at:
>>
>> http://dlang.org/phobos/std_datetime.html
>>
>> Can you really pick up the desired term?
>
>
> It's very unwieldy as is, but what if it was split up into a categorized
> table and cheat-sheet à la std.algorithm?

I'm sure you could make a t-shirt out of such a cheat-sheet.

-- 
Iain Buclaw

*(p < e ? p++ : p) = (c & 0x0f) + '0';

Re: Improved Phobos dox

2013-09-15 Thread Vladimir Panteleev


On Sunday, 15 September 2013 at 18:31:16 UTC, Dicebot wrote:
On Sunday, 15 September 2013 at 18:25:03 UTC, Vladimir 
Panteleev wrote:
I assume Ddox has failed to be integrated because it was a 
server-side process. It also places each symbol in its own 
file, which will break existing links. Perhaps it be feasible 
to reimplement only its basic index-table functionality in 
JavaScript, to replace the word-blob/dropdown?


Admitting that server-side process has failed and moving to JS 
is akin to accepting failure to do proper documentation at all. 
Static documentation which requires JS to be conveniently 
usable is disaster.


Using JS has several disadvantages, but would require much less 
effort for everyone involved. (If effort is not a factor, how 
come we don't have Ddox on dlang.org yet?)

Re: Improved Phobos dox