www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - working on the dlang.org website

reply Val Markovic <val markovic.io> writes:
I just watched Andrei's *Quo Vadis *talk from this year's DConf and I liked
it a lot. I strongly agreed with his notion that the D community needs to
embrace "operational professionalism"; I've been thinking along those same
lines for months and it's the one thing that the D community really, *really
* needs to work on. I've been a huge fan of the D language ever since I
read TDPL ~a year ago. IMO it's the most amazing language I've ever used,
and I've used far too many.

I don't normally participate on the D mailing lists (I lurk often though),
but my conscience was gnawing at me to send this email. It's a bit long, so
bear with me.

So, Andrei also mentioned how the community needs to improve the
dlang.orgsite and make it a first-class priority. It's the point of
contact for
newcomers so it's very important we get it right. Since I know a
thing-or-two about web development, I decided to look into improving the
site.

There's some low-hanging fruit with the site that shouldn't be too hard to
fix: there's an incredibly annoying "content flash" after any page is
loaded (it loads fine, you see the text, then the text disappears for a
second, then appears again). I've cursed at this more than a dozen times;
it's especially annoying on any mobile browser.

For a site that's just static content it also takes a long time to load.
Inexcusably long TBH. The PageSpeed analyzer puts the load time at ~7
seconds for a big page from the library
reference<https://developers.google.com/speed/pagespeed/insights#url=http_3A_2F_2Fdlang.org_2Fphobos_2Fstd__datetime.html&mobile=false&rule=____critical__path>.
In my personal experience there's no good reason why any 100% static site
should take more than 1s to load on a fast desktop machine, and often you
can get it to 0.5s with a bit more work. If it's loading in more than 1s,
then something is being done in a sub-optimal way. But that's not
surprising because building a site so that it loads optimally takes a fair
bit of doing and a large amount of domain knowledge.

So I decided to work on it a bit. Here's a blow-by-blow description of my
attempts to do so. All of this happens over the course of a few hours.

   1. Run the site through the PageSpeed analyzer and realize there's lots
   of low-hanging fruit. I can fix all of those and make the site faster,
   great.
   2. Looking at the Network data in the Chrome DevTools, realize the site
   isn't using a CDN. Make a note of mentioning this to the site maintainers;
   using a CDN is critical to performance and ever since CloudFlare came on
   the scene (fast & free CDN that's also trivial to set up) there's no excuse
   not to use one.
   3. Record a Timeline profile of the site's loading process in the Chrome
   DevTools. Study the profile and realize there's quite a bit extra reflow
   and repaint going on. Those should be addressed as well.
   4. Record a JavaScript profile of the site with the DevTools JS profiler
   and the new Flame view. With this information and the Timeline profile,
   realize that hypenate.js is probably the culprit of the content flash bug.
   Still have to verify this, it might be something else.
   5. Notice the site's homepage is throwing JS exceptions; that will need
   to be fixed as well. OK, time to checkout the site repo and make changes.
   6. Go to the D-Programming-Language/dlang.org github repo page.
   7. Wait, where's the README? No README? What? How do I make heads or
   tails of this thing?
   8. Oh God, the site is written in ddoc. Dear God *why*? Whatever, I'm
   not trying to change the content, just the framework that delivers the
   content. Complaining about the choice of markup language used for the
   content is not a fight worth fighting and the discussion would probably not
   be productive.
   9. Spend X minutes trying to figure out how to build the site. Find
   "wind32.mak". Sigh. I use Mac OS X and Linux.
   10. Search for "unix", "linux" and "makefile" in Chrome on the repo
   site. Nothing useful. Is there no way to build this site on a unix machine?
   11. Notice there are several outstanding pull requests. Look through
   them to figure out if there's any useful information there.
   12. Through nothing but sheer luck, notice a pull request that makes
   changes to "posix.mak". Ah, so there's an important file I missed. An ~hour
   down the drain because there was no README and I very easily could have not
   even found the relevant file.
   13. It appears that the makefile assumes the repo checkout needs to be
   performed inside of a specific folder structure that has other repositories
   already checked out. Great, so the build is not hermetic. Is continuing to
   try to make this work going to be worth my time? Let's look at how the
   project handles pull requests.
   14. Notice that there are several pull requests that have been waiting
   for a response for weeks and months. So even if I figure everything out
   (probably not too complicated from this point forward) and successfully
   make the relevant changes, my pull requests would probably languish
   unattended for a very long time.
   15. Conclude that this is not worth my time. "Meh, someone else will fix
   the site."

That last point was several hours ago. Since then my conscience has forced
me to at least point out the issues I encountered so that project leaders
might do something about it so that possible future contributors don't have
to go through the same painful process.

Criticism that's not constructive is not useful. So here's several
actionable items for the project leaders:

   - Prompt response to pull requests from outsiders is of the utmost
   importance. Response latency of anything more than a few days sends the
   signal that the community doesn't care about external contributions. To
   paraphrase Andrei, "if you want to be an OSS project with many
   contributors, do what projects with many contributors do". This entails
   promptly responding to external developers. Huge and successful projects
   like Ruby on Rails and Twitter Bootstrap can afford to have a high response
   latency because they have countless thousands of people trying to
   contribute to them. Causing those contributors some pain is not going to
   materially impact the success of the project (IMO of course they still
   shouldn't do this, but they can afford to). D is not there yet and should
   go out of its way to facilitate ease of contribution.
   - Good, up-to-date developer documentation is necessary if you want
   others to contribute. People can't make changes if they can't easily build
   the project. Sure, determined people could figure it out after a while even
   without the docs, but these roadblocks on the road of success don't help
   the project and are discouraging to outsiders. All of the
   "D-Programming-Language" repos on GitHub should at the very least have a
   README file that points newcomers in the right direction and answers the
   most basic questions they might have.
   - The issue tracker for the dlang.org repo has been turned off. I now
   realize that this is probably because the D community uses their bugzilla
   tracker and wants issues reported there, but nothing on the
dlang.orgrepo page says this. There are no docs that say "hey use this
bugzilla
   tracker to report issues". Nothing on the dmd repo page says this either.

I hope I have been constructive with my suggestions and that some of them
will be acted upon.

Wow, this ended up being far too long.
Jul 13 2013
next sibling parent "Suliman" <evermind live.ru> writes:
Would it be possible to add links to national dlang communities 
to the bottom of the page to make comers easier to find 
information and help on their native language?
Jul 14 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-14 05:19, Val Markovic wrote:

 I just watched Andrei's /Quo Vadis /talk from this year's DConf and I
 liked it a lot. I strongly agreed with his notion that the D community
 needs to embrace "operational professionalism"; I've been thinking along
 those same lines for months and it's the one thing that the D community
 really, /really/ needs to work on. I've been a huge fan of the D
 language ever since I read TDPL ~a year ago. IMO it's the most amazing
 language I've ever used, and I've used far too many.

 I don't normally participate on the D mailing lists (I lurk often
 though), but my conscience was gnawing at me to send this email. It's a
 bit long, so bear with me.

 [Snip]


I completely agree with you and I think it madness that the site is 
written in Ddoc. But apparently Walter and company loves it.

-- 
/Jacob Carlborg
Jul 14 2013
next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
Jacob Carlborg:


 I completely agree with you and I think it madness that the 
 site is written in Ddoc. But apparently Walter and company 
 loves it.


Do you like this? It's made with Python:
http://sphinx-doc.org/

Bye,
bearophile
Jul 14 2013
parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-14 14:34, bearophile wrote:


 Do you like this? It's made with Python:
 http://sphinx-doc.org/


Ddoc in it self is not that bad, for documenting code. It's just that I 
would never create a web site using it. I would go with a server side 
script. I prefer Ruby on Rails for that.

-- 
/Jacob Carlborg
Jul 14 2013
parent reply "nazriel" <spam dzfl.pl> writes:
On Sunday, 14 July 2013 at 20:19:06 UTC, Jacob Carlborg wrote:

 On 2013-07-14 14:34, bearophile wrote:


 Do you like this? It's made with Python:
 http://sphinx-doc.org/


 Ddoc in it self is not that bad, for documenting code. It's 
 just that I would never create a web site using it. I would go 
 with a server side script. I prefer Ruby on Rails for that.


There is absolutely nothing that Ruby, PHP or anything else would
buy us at this point. It would be just killing fly with the
hammer.

If someone is super stubborn to change DDOC for something
dynamically generated then PHP is available on DMD server.

The biggest issues with dlang.org are (basing on YSlow):
- Lack of compression of HTML, CSS and JS content.
      ---
      There are 7 plain text components that should be sent
compressed

      http://dlang.org/
      http://dlang.org/css/codemirror.css
      http://dlang.org/css/style.css
      ...
      ---

- Most of the java-script being included in header instead of
footer.
    That is also partially my fault, but I just went with flow back
then.
- No expire headers
- Lack of CDN


Other things that YSlow points out that may be important:
- There are 13 components with misconfigured ETags
- This page has 10 external Javascript scripts. Try combining
them into one.
- This page has 4 external stylesheets. Try combining them into
one.

I've done tests few months ago because people where complaining
about JavaScript and (wrongly) blamed run-able examples for this.

Hyphenate.js indeed has an impact on load times and removing it
in favor of CSS3 would fix the problem. Of course there is
probability that people with '90s browsers will complain (stares
at Nick ;>) but it is their choice to stick with such outdated
software.

Regards
Damian Ziemba
Jul 23 2013
next sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Tuesday, 23 July 2013 at 07:47:03 UTC, nazriel wrote:

 Hyphenate.js indeed has an impact on load times and removing it
 in favor of CSS3 would fix the problem. Of course there is
 probability that people with '90s browsers will complain (stares
 at Nick ;>) but it is their choice to stick with such outdated
 software.

 Regards
 Damian Ziemba


100% agree on this.
Jul 23 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-23 09:47, nazriel wrote:


 There is absolutely nothing that Ruby, PHP or anything else would
 buy us at this point. It would be just killing fly with the
 hammer.


I guess you don't see the advantage of having:

* Built in support for Sass, CoffeeScript and similar techniques
* Using a well known framework that have plenty of documentation available
* Having a server and database backing up new features as such comments

BTW, you do know that you can do server side caching to avoid hitting 
the Rails/PHP stack at all most times? The web server (apache) would 
just serve the raw HTML just as it does now.

-- 
/Jacob Carlborg
Jul 23 2013
parent reply "Dicebot" <public dicebot.lv> writes:
On Tuesday, 23 July 2013 at 12:29:38 UTC, Jacob Carlborg wrote:

 * Built in support for Sass, CoffeeScript and similar techniques
 * Using a well known framework that have plenty of 
 documentation available
 * Having a server and database backing up new features as such 
 comments


There is nothing here D can't do. Dogfooding ftw.
Jul 23 2013
next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 23 July 2013 at 13:19:12 UTC, Dicebot wrote:

 There is nothing here D can't do. Dogfooding ftw.


hell, I've done my own versions of that stuff in D! Though most 
the similarities are actually coincidence since I've never 
actually used the Ruby stuff, there are a lot of similarities.

In the perhaps poorly named html.d in my github
https://github.com/adamdruppe/misc-stuff-including-D-programming-language-web-stuff


There's a macro expander thing that includes a css and javascript 
subclass. The javascript one is nothing special, it just adds a 
foreach macro to it. (Which is btw a text expansion macro, but 
hey it works for me fixes the biggest annoyance I have with that 
language.)

The really useful one comes with the expandAndDenest css one 
which translates stuff like

  .test {
     color: red;
     .bold { font-weight: bold; }
  }

into

  .test { color: red; }
  .test .bold { font-weight: bold; }


and has a bunch of macros you can define and use yourself for 
stuff like some color manipulation, reuse of declarations, and so 
on.




Of course, no framework for the site is required here, since you 
can always just convert the file ahead of time in the makefile 
and serve plain generated code to the website.
Jul 23 2013
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2013-07-23 15:19, Dicebot wrote:


 There is nothing here D can't do. Dogfooding ftw.


I give up, there's obviously no point in arguing.

-- 
/Jacob Carlborg
Jul 23 2013
prev sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jul 23, 2013 at 09:47:02AM +0200, nazriel wrote:
[...]

 Hyphenate.js indeed has an impact on load times and removing it
 in favor of CSS3 would fix the problem. Of course there is
 probability that people with '90s browsers will complain (stares
 at Nick ;>) but it is their choice to stick with such outdated
 software.


[...]

Honestly, I think hyphenation is blown wayyyy out of proportion. I
turned off JS on dlang.org (I use Opera) because it was so slow, and now
the site is significantly faster. And guess what? I didn't even *notice*
the lack of hyphenation until I saw threads about the slowness of
hyphenate.js. Seriously, we need to take a deep breath, step back, and
get the right perspective on things. Hyphenation is mostly a
*non-issue*. Most people don't even notice it! Have you ever seen
threads on the forum about why dlang.org sucks because it lacks
hyphenation? I haven't. So why are we paying such a hefty tax on it
(i.e. hyphenate.js's slow performance)? On the contrary, there are tons
of threads about slow loading times.

So I say, leave the CSS3 hyphenation stuff in, so that whoever uses
browsers that support it will get the benefit, and take out
hyphenate.js, because the ROI is simply too small to justify such a big
performance hit.


T

-- 
Stop staring at me like that! You'll offend... no, you'll hurt your eyes!
Jul 23 2013
next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Tuesday, 23 July 2013 at 14:48:11 UTC, H. S. Teoh wrote:

 Seriously, we need to take a deep breath, step back, and
 get the right perspective on things. Hyphenation is mostly a
 *non-issue*. Most people don't even notice it!


Here is yet another point of view - hyphenation makes text ugly 
and more difficult to read ;) For me it is a pure legacy of 
hand-written texts where it sometimes hard to reason if word will 
fit into the remainder of the line.
Jul 23 2013
parent "Kagamin" <spam here.lot> writes:
On Tuesday, 23 July 2013 at 14:56:46 UTC, Dicebot wrote:

 Here is yet another point of view - hyphenation makes text ugly 
 and more difficult to read


It certainly looks strange as it's unusual for the web.
Jul 23 2013
prev sibling parent reply Dmitry Olshansky <dmitry.olsh gmail.com> writes:
23-Jul-2013 18:46, H. S. Teoh пишет:

 On Tue, Jul 23, 2013 at 09:47:02AM +0200, nazriel wrote:
 [...]

 Hyphenate.js indeed has an impact on load times and removing it
 in favor of CSS3 would fix the problem. Of course there is
 probability that people with '90s browsers will complain (stares
 at Nick ;>) but it is their choice to stick with such outdated
 software.


 [...]

 Honestly, I think hyphenation is blown wayyyy out of proportion. I
 turned off JS on dlang.org (I use Opera) because it was so slow, and now
 the site is significantly faster. And guess what? I didn't even *notice*
 the lack of hyphenation until I saw threads about the slowness of
 hyphenate.js. Seriously, we need to take a deep breath, step back, and
 get the right perspective on things. Hyphenation is mostly a
 *non-issue*. Most people don't even notice it! Have you ever seen
 threads on the forum about why dlang.org sucks because it lacks
 hyphenation? I haven't. So why are we paying such a hefty tax on it
 (i.e. hyphenate.js's slow performance)? On the contrary, there are tons
 of threads about slow loading times.


Aside from that numerous issue coming up in the past along the line of 
"hyphenated the wrong thing" namely function names in tables and 
whatnot. It was a burden and it's a burden still.


 So I say, leave the CSS3 hyphenation stuff in, so that whoever uses
 browsers that support it will get the benefit, and take out
 hyphenate.js, because the ROI is simply too small to justify such a big
 performance hit.


+1

-- 
Dmitry Olshansky
Jul 23 2013
parent reply "Kagamin" <spam here.lot> writes:
Anybody gets a timeout in hyphenate.js on 
http://dlang.org/phobos/core_memory.html ?

----
A script on this page may be busy, or it may have stopped 
responding. You can stop the script now, or you can continue to 
see if the script will complete.

Script: http://dlang.org/js/hyphenate.js:55
----
Jul 30 2013
next sibling parent reply "Damian" <damianday hotmail.co.uk> writes:
On Tuesday, 30 July 2013 at 16:18:38 UTC, Kagamin wrote:

 Anybody gets a timeout in hyphenate.js on 
 http://dlang.org/phobos/core_memory.html ?

 ----
 A script on this page may be busy, or it may have stopped 
 responding. You can stop the script now, or you can continue to 
 see if the script will complete.

 Script: http://dlang.org/js/hyphenate.js:55
 ----


Working fine with Chrome 28.
Jul 30 2013
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jul 30, 2013 at 06:25:30PM +0200, Damian wrote:

 On Tuesday, 30 July 2013 at 16:18:38 UTC, Kagamin wrote:

Anybody gets a timeout in hyphenate.js on
http://dlang.org/phobos/core_memory.html ?

----
A script on this page may be busy, or it may have stopped
responding. You can stop the script now, or you can continue to
see if the script will complete.

Script: http://dlang.org/js/hyphenate.js:55
----


 
 Working fine with Chrome 28.


I turn off JS for dlang.org. It works much faster that way, and is far
more usable.


T

-- 
"Hi." "'Lo."
Jul 30 2013
parent reply "John Colvin" <john.loughran.colvin gmail.com> writes:
On Tuesday, 30 July 2013 at 16:48:49 UTC, H. S. Teoh wrote:

 On Tue, Jul 30, 2013 at 06:25:30PM +0200, Damian wrote:

 On Tuesday, 30 July 2013 at 16:18:38 UTC, Kagamin wrote:

Anybody gets a timeout in hyphenate.js on
http://dlang.org/phobos/core_memory.html ?

----
A script on this page may be busy, or it may have stopped
responding. You can stop the script now, or you can continue 
to
see if the script will complete.

Script: http://dlang.org/js/hyphenate.js:55
----


 
 Working fine with Chrome 28.


 I turn off JS for dlang.org. It works much faster that way, and 
 is far
 more usable.


 T


I really wish I could do that. Unfortunately I need js for the 
forum split-view and NotScripts isn't sophisticated enough to 
whitelist subdomains.
Jul 30 2013
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 7/30/13, John Colvin <john.loughran.colvin gmail.com> wrote:

 I really wish I could do that. Unfortunately I need js for the
 forum split-view and NotScripts isn't sophisticated enough to
 whitelist subdomains.


I use YesScript to block JS in specific websites, maybe that could work for you.
Jul 30 2013
prev sibling next sibling parent "Kapps" <opantm2+spam gmail.com> writes:
On Tuesday, 30 July 2013 at 16:18:38 UTC, Kagamin wrote:

 Anybody gets a timeout in hyphenate.js on 
 http://dlang.org/phobos/core_memory.html ?

 ----
 A script on this page may be busy, or it may have stopped 
 responding. You can stop the script now, or you can continue to 
 see if the script will complete.

 Script: http://dlang.org/js/hyphenate.js:55
 ----


This sometimes happens to me in Firefox and IE. I just clicked 
your link and IE11 is saying that the tab isn't responding as 
well.

Honestly, this hyphenate.js is much more trouble than it's worth.
Jul 30 2013
prev sibling parent reply "Wyatt" <wyatt.epp gmail.com> writes:
On Tuesday, 30 July 2013 at 16:18:38 UTC, Kagamin wrote:

 Anybody gets a timeout in hyphenate.js on 
 http://dlang.org/phobos/core_memory.html ?

 ----
 A script on this page may be busy, or it may have stopped 
 responding. You can stop the script now, or you can continue to 
 see if the script will complete.

 Script: http://dlang.org/js/hyphenate.js:55
 ----


Yeah.  I've seen it.  Even though it's supposed to be disabled 
for Firefox.  I'm waiting eagerly for this pull request to get 
merged so we can end this farce:
https://github.com/D-Programming-Language/dlang.org/pull/367

-Wyatt
Jul 30 2013
parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 07/30/2013 02:00 PM, Wyatt wrote:

 On Tuesday, 30 July 2013 at 16:18:38 UTC, Kagamin wrote:

 Anybody gets a timeout in hyphenate.js [..]


 Yeah. I've seen it. Even though it's supposed to be disabled for
 Firefox. I'm waiting eagerly for this pull request to get merged so we
 can end this farce:
 https://github.com/D-Programming-Language/dlang.org/pull/367


Seems like Andrei is dragging his feet over a fetish that only he cares 
about. Personally, I find hyphenation as a hindrance to readability, 
unless I'm reading a newspaper column. Maybe it's useful for mobile, but 
not if it degrades speed or does crap like flashing the page.

By the way, the worst idea I've seen is to do hyphenation statically on 
the server side. How does the server know in advance how wide my browser 
window is or the text size? It can't. It's the client's job to flow the 
text.
Jul 31 2013
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Wednesday, 31 July 2013 at 07:35:34 UTC, Jeff Nowakowski wrote:

 By the way, the worst idea I've seen is to do hyphenation 
 statically on the server side. How does the server know in 
 advance how wide my browser window is or the text size? It 
 can't. It's the client's job to flow the text.


Both hyphenate.js and hyphenate.d statically insert shy hyphens, 
which indicate potential line breaks to browsers. They are 
invisible except when the line is wrapped at their position.

Of course, this still doesn't work correctly in some browsers - 
very old browsers render all shy hyphens as regular hyphens, and 
some browsers include the invisible shy hyphen characters when 
you select and copy text.
Jul 31 2013
next sibling parent reply "Brad Anderson" <eco gnuk.net> writes:
On Wednesday, 31 July 2013 at 14:14:50 UTC, Vladimir Panteleev 
wrote:

 On Wednesday, 31 July 2013 at 07:35:34 UTC, Jeff Nowakowski 
 wrote:

 By the way, the worst idea I've seen is to do hyphenation 
 statically on the server side. How does the server know in 
 advance how wide my browser window is or the text size? It 
 can't. It's the client's job to flow the text.


 Both hyphenate.js and hyphenate.d statically insert shy 
 hyphens, which indicate potential line breaks to browsers. They 
 are invisible except when the line is wrapped at their position.

 Of course, this still doesn't work correctly in some browsers - 
 very old browsers render all shy hyphens as regular hyphens, 
 and some browsers include the invisible shy hyphen characters 
 when you select and copy text.


Someone in IRC,  Hackerpilot I believe, related how they copied 
and pasted some code from dlang.org into their editor and random 
things weren't getting syntax highlighted.  He only noticed what 
was causing it when he was moving the cursor around and his 
cursor wouldn't move the same number of arrow key presses he made.

Invisible characters breaking my code is pretty much my greatest 
nightmare as a programmer.
Jul 31 2013
parent "Brian Schott" <briancschott gmail.com> writes:
On Wednesday, 31 July 2013 at 21:50:15 UTC, Brad Anderson wrote:

 Someone in IRC,  Hackerpilot I believe, related how they copied 
 and pasted some code from dlang.org into their editor and 
 random things weren't getting syntax highlighted.  He only 
 noticed what was causing it when he was moving the cursor 
 around and his cursor wouldn't move the same number of arrow 
 key presses he made.

 Invisible characters breaking my code is pretty much my 
 greatest nightmare as a programmer.


To clarify: I was updating the syntax highlighting file for 
Textadept so that it would include the latest list of __traits 
arguments and so on. I copied and pasted the listing off the site 
into the lexer file and random things failed to highlight.
Jul 31 2013
prev sibling parent Jeff Nowakowski <jeff dilacero.org> writes:
On 07/31/2013 10:14 AM, Vladimir Panteleev wrote:

 On Wednesday, 31 July 2013 at 07:35:34 UTC, Jeff Nowakowski wrote:

 By the way, the worst idea I've seen is to do hyphenation statically
 on the server side. How does the server know in advance how wide my
 browser window is or the text size? It can't. It's the client's job to
 flow the text.


 Both hyphenate.js and hyphenate.d statically insert shy hyphens, which
 indicate potential line breaks to browsers. They are invisible except
 when the line is wrapped at their position.


Sorry for the misinformation, and thanks for the correction.
Jul 31 2013
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/14/2013 2:30 AM, Jacob Carlborg wrote:

 I think it madness that the site is written in Ddoc.


Different, sure. Madness - why?
Jul 14 2013
next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 7/14/13 5:20 PM, Walter Bright wrote:

 On 7/14/2013 2:30 AM, Jacob Carlborg wrote:

 I think it madness that the site is written in Ddoc.


 Different, sure. Madness - why?


If you look at for example this file:

https://github.com/D-Programming-Language/dlang.org/blob/master/lex.dd

All I see is HTML with a different syntax. You can achieve the same 
using html tags (<h4> instead of $(H4)) and div ids or classes, then 
applying css rules.

If somebody wants to contribute, it's sure easy to understand HTML. But 
understanding DDoc requires more knowledge, so less chance of receiving 
contributions.

But I think it's ok to do the website... for dog-fooding :-)
Jul 14 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/14/2013 7:19 PM, Ary Borenszweig wrote:

 On 7/14/13 5:20 PM, Walter Bright wrote:

 On 7/14/2013 2:30 AM, Jacob Carlborg wrote:

 I think it madness that the site is written in Ddoc.


 Different, sure. Madness - why?


 If you look at for example this file:

 https://github.com/D-Programming-Language/dlang.org/blob/master/lex.dd

 All I see is HTML with a different syntax. You can achieve the same using html
 tags (<h4> instead of $(H4)) and div ids or classes, then applying css rules.


HTML doesn't work for other kinds of output that is supported by the makefiles
- 
ebook, pdf, etc.

I wrote the original Digital Mars web site in plain html. That's what motivated 
me to invent Ddoc. I'm at least twice as productive in Ddoc, maybe even 4
times. 
For example, if I want to change the copyright notice, I can:

1. edit hundreds of files

    -- or --

2. edit a Ddoc macro

It's no contest.


 If somebody wants to contribute, it's sure easy to understand HTML. But
 understanding DDoc requires more knowledge, so less chance of receiving
 contributions.


Ddoc isn't any harder than any of the innumerable markup languages out there, 
like mediawiki.
Jul 14 2013
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-15 05:22, Walter Bright wrote:


 HTML doesn't work for other kinds of output that is supported by the
 makefiles - ebook, pdf, etc.


I thought the PDF was generated from the HTML output.


 I wrote the original Digital Mars web site in plain html. That's what
 motivated me to invent Ddoc. I'm at least twice as productive in Ddoc,
 maybe even 4 times.


Come on. That's like say "I'm more productive using C than writing in 
machine code directly". Try comparing with PHP, Python, Ruby on Rails, D 
or any other language. Plain HTML just sucks.


 For example, if I want to change the copyright
 notice, I can:

 1. edit hundreds of files

     -- or --

 2. edit a Ddoc macro


You can do that with any other language or template system that support 
templates or similar.


 Ddoc isn't any harder than any of the innumerable markup languages out
 there, like mediawiki.


I was more thinking of a proper language, as mentioned above.

-- 
/Jacob Carlborg
Jul 14 2013
parent "Dicebot" <public dicebot.lv> writes:
On Monday, 15 July 2013 at 06:35:44 UTC, Jacob Carlborg wrote:

 On 2013-07-15 05:22, Walter Bright wrote:
 ...


Makes me wonder if dlang.org backend reflavored to use vibe.d + 
some database has any chance to be accepted as a new upstream :) 
Dogfooding can done in a variety of ways ;)
Jul 15 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-15 05:22, Walter Bright wrote:


 Ddoc isn't any harder than any of the innumerable markup languages out
 there, like mediawiki.


But how do I add support for Sass, CoffeeScript and similar languages 
that web developers expect today? It's dead easy in a framework like 
Ruby on Rails.

-- 
/Jacob Carlborg
Jul 14 2013
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 15 July 2013 at 06:56:38 UTC, Jacob Carlborg wrote:

 But how do I add support for Sass, CoffeeScript and similar 
 languages that web developers expect today?


This is almost as silly as Walter's copyright thing, since those 
languages are converted to regular js+css which are linked in 
just like anything else. In fact, it is identical to the 
copyright edit except maybe editing the makefile to generate the 
file too.
Jul 15 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-07-15 14:25, Adam D. Ruppe wrote:


 This is almost as silly as Walter's copyright thing, since those
 languages are converted to regular js+css which are linked in just like
 anything else. In fact, it is identical to the copyright edit except
 maybe editing the makefile to generate the file too.


I would not consider it to be the same. Doing what the Rails asset 
pipeline does manually is quite a lot of work. Merging files, minifying, 
piping through various preprocessors, adding unique hash based on the 
content to the file name and so on.

-- 
/Jacob Carlborg
Jul 15 2013
prev sibling parent reply "John Colvin" <john.loughran.colvin gmail.com> writes:
On Monday, 15 July 2013 at 03:22:59 UTC, Walter Bright wrote:

 For example, if I want to change the copyright notice, I can:

 1. edit hundreds of files

    -- or --

 2. edit a Ddoc macro

 It's no contest.


Even the very simplest roll-your-own framework would remove this 
necessity.

Even simpler, you just split the contents of the site in to 
components and load them via your favourite scripting language, 
e.g.

<?php echo get_file_contents("copyright.html"); ?>

I don't necessarily think using ddoc is a bad idea, but web 
development has moved on a long way from editing every file 
separately.
Jul 15 2013
parent Walter Bright <newshound2 digitalmars.com> writes:
On 7/15/2013 1:20 AM, John Colvin wrote:

 On Monday, 15 July 2013 at 03:22:59 UTC, Walter Bright wrote:

 For example, if I want to change the copyright notice, I can:

 1. edit hundreds of files

    -- or --

 2. edit a Ddoc macro

 It's no contest.


 Even the very simplest roll-your-own framework would remove this necessity.


Please note that I wrote this in response to Ary's suggestion to just write raw 
HTML.



 Even simpler, you just split the contents of the site in to components and load
 them via your favourite scripting language, e.g.

 <?php echo get_file_contents("copyright.html"); ?>

 I don't necessarily think using ddoc is a bad idea, but web development has
 moved on a long way from editing every file separately.


Yes, and Ddoc has also moved on from that. That's why I wrote it, in fact.
Jul 15 2013
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-14 22:20, Walter Bright wrote:


 Different, sure. Madness - why?


"Madness" might be stretching it. You're making it unnecessary hard for 
someone not familiar with how the D website is structured. Example, I 
added a couple of new files to Phobos (std.serialization), which it 
properly generates the HTML files for. But why don't them show up in the 
left side menu?

-- 
/Jacob Carlborg
Jul 14 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-07-15 08:40, Jacob Carlborg wrote:


 "Madness" might be stretching it. You're making it unnecessary hard for
 someone not familiar with how the D website is structured. Example, I
 added a couple of new files to Phobos (std.serialization), which it
 properly generates the HTML files for. But why don't them show up in the
 left side menu?


Another example. How do I create a macro that takes a string like 
"std.algorithm.find" and create a link to the std.algorithm page and the 
"find" function?

-- 
/Jacob Carlborg
Jul 14 2013
prev sibling next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Sunday, 14 July 2013 at 04:56:46 UTC, Val Markovic wrote:

 ...


Thanks for the input!

I do personally agree that official web page is one of most 
lacking areas of D public image. Maybe that is because there are 
no people among core developers specializing on web development 
(or am I ignorant here?).

To be honest I still have no idea how this web site was created 
and what is the real process behind maintaining it. Guess there 
are two options - either it is made more transparent by current 
maintainers or someone steps up to take the responsibility to 
tidy things up (not me!).

Using DDOC itself does not seem that critical IMHO - it is just 
one more markup language which anyone working with D knows at 
least vaguely. But maintaining whole stuff via git repo + 
makefiles is definitely cumbersome, no idea why that was chosen.
Jul 14 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/14/2013 6:49 AM, Dicebot wrote:

 But maintaining
 whole stuff via git repo + makefiles is definitely cumbersome, no idea why that
 was chosen.


1. github is how the entire rest of D is maintained, it would be strange if the 
website was handled via some completely different system.

2. github is of proven utility in enabling anyone to contribute to the web site 
via pull requests.

3. github/makefiles are how everything else in dlang is done, so contributors 
should already be familiar with the process.


As for using Ddoc,

1. It relies on D being installed. Presumably, anyone interested in developing 
the D website already has D installed. No other tools are necessary.

2. Ye Olde Dogfooding argument. Experience with the web site has driven some 
good improvements to Ddoc.

3. HTML, PDF, Ebook, and CHM outputs are generated from Ddoc.

4. Website can be built on any platform that supports D.
Jul 14 2013
next sibling parent reply Val Markovic <val markovic.io> writes:
This discussion seems to have gone off track.

I pointed out three things that I thought should be addressed to ease the
use of contributing to the dlang.org site (and other D-project components),
and those three things were: a) lower response latency on pull requests, b)
better documentation of the component "plumbings", specifically how to
build the dlang.org website and c) README files in all the D-project repos
with answers to common questions outside developers might have, like "where
do I report bugs?".

The discussion here goes on to debate the pros and cons of ddoc which is *
explicitly* something I mentioned as "not worth fighting over". Yes, IMO
it's an unfortunate choice of a markup language because to outsiders it's
esoteric and unlike most other markup languages and there are far better
options out there (Markdown or reStructuredText). For a project that's
still looking for contributors it's just another roadblock to adoption.
It's what they call an "unforced error" in tennis; something that makes it
harder to succeed for no benefit or reason, and not doing it (or doing it
differently) helps you get to where you want to go faster.

But again, this is beating a dead horse. This mailing list has seen plenty
of discussions on the topic and the powers that be haven't been convinced
to move away from ddoc so I don't think it's going to be fruitful to debate
this further. Let's be practical and let it be and move onto other, more
important problems. Nobody has ever said "Oh that D language is great but
ddoc is so bad I've decided to use Java". That just doesn't happen. It's
not that important.

Ddoc was irrelevant to the changes I wanted to make to the site anyway. The
more important problems I listed were the ones preventing me from making
them.

Other points:

1. Having the website inside git on github was a great idea. Walter made
all the right arguments explaining why.

2. Makefiles are fine, but there needs to be a README saying "hey go run
that posix.mak file" because there's no "Makefile" file in the site repo.
And then the makefile has assumptions about its environment which are not
documented anywhere. It's not obvious what needs to be done.

3. Ruby on Rails (or Django or any other web framework that dynamically
builds a server response) would be a terrible choice for a static website.
It would be nothing but overhead for no benefit. Nothing on dlang.org is
dynamically generated, nothing talks to a database (nor should it). The
site can and should be generated from some simple markup language. The end
result should be HTML, CSS, JS and image files that are then just served by
the simplest of servers. For these types of sites, the industry standard is
quickly becoming to serve the files directly out of Amazon S3 with a CDN
(like CloudFlare) in front of it. The end result is an incredibly fast
browsing experience because everything is just served directly out of the
CDN edge servers without any kind of dynamic response generation. Requests
come in for files and the CDN just echoes them out of memory to the network.

Of course, forum.dlang.org would be different, but (internally) that's a
different site entirely.


On Sun, Jul 14, 2013 at 1:35 PM, Walter Bright
<newshound2 digitalmars.com>wrote:


 On 7/14/2013 6:49 AM, Dicebot wrote:


 But maintaining
 whole stuff via git repo + makefiles is definitely cumbersome, no idea
 why that
 was chosen.


 1. github is how the entire rest of D is maintained, it would be strange
 if the website was handled via some completely different system.

 2. github is of proven utility in enabling anyone to contribute to the web
 site via pull requests.

 3. github/makefiles are how everything else in dlang is done, so
 contributors should already be familiar with the process.


 As for using Ddoc,

 1. It relies on D being installed. Presumably, anyone interested in
 developing the D website already has D installed. No other tools are
 necessary.

 2. Ye Olde Dogfooding argument. Experience with the web site has driven
 some good improvements to Ddoc.

 3. HTML, PDF, Ebook, and CHM outputs are generated from Ddoc.

 4. Website can be built on any platform that supports D.
Jul 14 2013
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/14/2013 2:18 PM, Val Markovic wrote:

 I pointed out three things that I thought should be addressed to ease the use
of
 contributing to the dlang.org <http://dlang.org> site (and other D-project
 components), and those three things were: a) lower response latency on pull
 requests, b) better documentation of the component "plumbings", specifically
how
 to build the dlang.org <http://dlang.org> website and c) README files in all
the
 D-project repos with answers to common questions outside developers might have,
 like "where do I report bugs?".


I agree with your three points. I'll add that anyone can do a pull request to 
address any/all of these.



 The discussion here goes on to debate the pros and cons of ddoc which is
 /explicitly/ something I mentioned as "not worth fighting over".


Sure, but I wanted to address the comments that it was "madness" to and "no 
idea" why to use ddoc. Yes, it's come up before.
Jul 14 2013
next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
One of the things we should add to the new README is a tip 
pointing people toward the DDOC = macro in std.ddoc.

That's the skeleton html for the website and is pretty plain.
Jul 14 2013
prev sibling parent reply Val Markovic <val markovic.io> writes:
On Sun, Jul 14, 2013 at 2:37 PM, Walter Bright
<newshound2 digitalmars.com>wrote:


 I agree with your three points. I'll add that anyone can do a pull request
 to address any/all of these.


How can someone send a pull request to address the long latency of
responding to pull requests? The other issues I pointed out are blocked on
that one, because until that is addressed, there's no point in sending PRs.
My free time is both limited and precious to me and I'm sure the free time
of others is precious to them as well. As an outside contributor, if I see
that contributions are not valued highly (as evidenced by the response
time; I'm sorry but that's just the way it works) I don't feel motivated to
contribute.

I give freely of my own time, make changes, send a pull request and then
wait months for a maintainer to so much as glance in its direction. You can
see the problem here.

As a project maintainer, if you want others to contribute to your project
you need to make contributing utterly frictionless.
Jul 14 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/14/2013 2:59 PM, Val Markovic wrote:

 How can someone send a pull request to address the long latency of responding
to
 pull requests?


There are 13 open PRs, and about 335 pulled ones.

While we can and must do better, I don't think the situation is as dire as you 
suggest.

There are currently 12 team members with pull privileges on the dlang.org repo. 
If you feel a particular PR is being overlooked, or your work is blocked by it, 
you can ping them.

We also tend to promote prolific contributors into being team members, so they 
become part of the problem :-)

You can also post bug reports for the website on bugzilla:

http://d.puremagic.com/issues/

and select "websites" under "Component", and assign the severity as you see fit.
Jul 14 2013
parent Val Markovic <val markovic.io> writes:
On Sun, Jul 14, 2013 at 3:34 PM, Walter Bright
<newshound2 digitalmars.com>wrote:


 While we can and must do better, I don't think the situation is as dire as
 you suggest.


I think it's more dire than you realize, but I could be wrong. Here are a
few links to pull requests on dlang.org that seem to need love from the
maintainers.

No updates from upstream for:

3 months: https://github.com/D-Programming-Language/dlang.org/pull/311
4 months: https://github.com/D-Programming-Language/dlang.org/pull/304
4 months: https://github.com/D-Programming-Language/dlang.org/pull/292
4 months: https://github.com/D-Programming-Language/dlang.org/pull/267

I've created and led several successful open source projects and I've
contributed to many more. The rule of thumb I've observed is that "a few
days" of response latency is fine, ~5 days is plenty and anything more than
a week is too long and sends the wrong signal. I can't say I've always
observed this rule of thumb myself (sometimes I forget or slip up), but
it's a bar I try to meet.

I appreciate your agreement that the community can and must do better.
Jul 14 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-14 23:18, Val Markovic wrote:


 3. Ruby on Rails (or Django or any other web framework that dynamically
 builds a server response) would be a terrible choice for a static
 website. It would be nothing but overhead for no benefit. Nothing on
 dlang.org <http://dlang.org> is dynamically generated, nothing talks to
 a database (nor should it). The site can and should be generated from
 some simple markup language. The end result should be HTML, CSS, JS and
 image files that are then just served by the simplest of servers.


Why not? We're limiting our self here. Someone talked about adding 
comments to the documentation, like PHP has. Or do you want to use a 
database that JavaScript can talk to directly, to avoid server side scripts?

-- 
/Jacob Carlborg
Jul 14 2013
parent reply "Chad Joan" <chadjoan gmail.com> writes:
On Monday, 15 July 2013 at 06:53:37 UTC, Jacob Carlborg wrote:

 On 2013-07-14 23:18, Val Markovic wrote:


 3. Ruby on Rails (or Django or any other web framework that 
 dynamically
 builds a server response) would be a terrible choice for a 
 static
 website. It would be nothing but overhead for no benefit. 
 Nothing on
 dlang.org <http://dlang.org> is dynamically generated, nothing 
 talks to
 a database (nor should it). The site can and should be 
 generated from
 some simple markup language. The end result should be HTML, 
 CSS, JS and
 image files that are then just served by the simplest of 
 servers.


 Why not? We're limiting our self here. Someone talked about 
 adding comments to the documentation, like PHP has. Or do you 
 want to use a database that JavaScript can talk to directly, to 
 avoid server side scripts?


Please no RoR/PHP/JavaScript/etc.  It's already hard enough to 
contribute to this thing as it is.  These would add a bunch of 
dependencies for little gain, and possibly a bunch of alienation.

As a user, I really don't want my browsing experience slowed down 
by that stuff either.

I could maybe see using D+vibe.d, but only because it wouldn't 
introduce a new ecosystem of languages/tools.  It's also based on 
D and should be reasonably fast (and if it isn't: something 
failed; start over).

<rambling>
I think what really needs to be addressed though is the build 
system, checkout process, and maintainer's documentation (ex: 
README).  I've experienced a lot of contribution difficulty too.  
It makes the whole thing not-fun and strongly encourages me to do 
other things.  I remember watching Wyatt hack on the docs and 
then ran a build script that initiated some kind of 
pull/clone/whatever-I-forget-exactly from the main repo (yuck).  
It seems like most of the meaty bits are there, but it all needs 
to get adjusted according to the experiences of (potential) 
contributors.

The github editing interface helps, but is only really effective 
for very small changes that I know will work.  It requires 
generating a pull request before I see what the published result 
will look like.  I really need to be able to see doc changes 
/easily/.

I've always been attended to quickly during the few pull requests 
I made, though there seem to be some important ones (from other 
people) that slip through the cracks.  I find out about those 
later when I read the newsgroup.  I just hope that Walter & Co 
will notice this happening and know what to do about it.

FWIW, I was able to pick up and understand ddoc very quickly.  It 
is awesome for docs (you know, that thing it was made for).  I 
also love the idea of generating webpages from my source code: as 
long as it's API docs.  I don't think this necessarily means it 
should be used for web dev.  At the same time, when web 
developers offer alternative tools, my gag reflexes tend to kick 
in.  Maybe we can solicit the web developers for tool advice and 
pick the things that don't make people gag?  Maybe my imagination 
lives in a perfect world.

I hope this is constructive enough.
(In reality I probably just pissed off a bunch of 
dynamically-typed-language-loving scripty web programmers.  Oh 
crap! *ducks*)
</rambling>
Jul 17 2013
next sibling parent "Chad Joan" <chadjoan gmail.com> writes:
On Wednesday, 17 July 2013 at 07:46:28 UTC, Chad Joan wrote:

 FWIW, I was able to pick up and understand ddoc very quickly.  
 It is awesome for docs (you know, that thing it was made for).  
 I also love the idea of generating webpages from my source 
 code: as long as it's API docs.  I don't think this necessarily 
 means it should be used for web dev.  At the same time, when 
 web developers offer alternative tools, my gag reflexes tend to 
 kick in.  Maybe we can solicit the web developers for tool 
 advice and pick the things that don't make people gag?  Maybe 
 my imagination lives in a perfect world.


This is too harsh, even if I did mean it in a tongue-in-cheek way 
when I wrote it.  I apologize.

Up too late I guess.
Jul 17 2013
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-17 09:46, Chad Joan wrote:


 Please no RoR/PHP/JavaScript/etc.  It's already hard enough to
 contribute to this thing as it is.  These would add a bunch of
 dependencies for little gain, and possibly a bunch of alienation.


Yes, it adds dependencies but it's easy to use and is well documented.


 FWIW, I was able to pick up and understand ddoc very quickly.  It is
 awesome for docs (you know, that thing it was made for).  I also love
 the idea of generating webpages from my source code: as long as it's API
 docs.  I don't think this necessarily means it should be used for web
 dev.  At the same time, when web developers offer alternative tools, my
 gag reflexes tend to kick in.  Maybe we can solicit the web developers
 for tool advice and pick the things that don't make people gag?  Maybe
 my imagination lives in a perfect world.


Ddoc isn't hard to use, it's too limited in what it can do. What is hard 
is everything around it, like building and so on, as you mentioned. With 
a big web development framework, like Rails, it's well documented.

I certainly don't think ddoc should be use for web development. I would 
never create a site with ddoc. It's too limited in what it can do.

-- 
/Jacob Carlborg
Jul 17 2013
parent "Chad Joan" <chadjoan gmail.com> writes:
On 07/17/2013 05:22 AM, Jacob Carlborg wrote:> On 2013-07-17 
09:46, Chad Joan wrote:

 
...
 
 Ddoc isn't hard to use, it's too limited in what it can do. 
 What is hard is everything around it, like building and so on, 
 as you mentioned. With a big web development framework, like 
 Rails, it's well documented.
 


Since ddoc is used for documentation, then I think it should be 
made as easy to build as possible.  This seems like a packaging 
issue.  I'm usually more concerned with documentation fixup 
myself, and documentation fixup is a pain in the butt if the 
build process isn't "run command X, then open your browser to Y".


 I certainly don't think ddoc should be use for web development. 
 I would never create a site with ddoc. It's too limited in what 
 it can do.
 


Reasonable enough.  I easily can see how this would be the case.

I still hope that the D site will be mostly static.  I can see 
use cases in some exceptions (like user comments on various 
things, and maybe news pulling), but I feel like those should 
load as close to static as possible, and otherwise not block the 
experience if I happen to have adblock/noscript/etcetc all 
running at full burn.  I think our forum software is a good 
example of Doing It Right.
Jul 17 2013
prev sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 7/14/13 6:18 PM, Val Markovic wrote:> 3. Ruby on Rails (or Django or 
any other web framework that dynamically

 builds a server response) would be a terrible choice for a static
 website. It would be nothing but overhead for no benefit. Nothing on
 dlang.org <http://dlang.org> is dynamically generated, nothing talks to
 a database (nor should it). The site can and should be generated from
 some simple markup language. The end result should be HTML, CSS, JS and
 image files that are then just served by the simplest of servers. For
 these types of sites, the industry standard is quickly becoming to serve
 the files directly out of Amazon S3 with a CDN (like CloudFlare) in
 front of it. The end result is an incredibly fast browsing experience
 because everything is just served directly out of the CDN edge servers
 without any kind of dynamic response generation. Requests come in for
 files and the CDN just echoes them out of memory to the network.


You can also try GitHub pages. And since D already has its code in 
github it's very simple.

http://pages.github.com/

It generates a static site from a bunch of files. Under the hood it uses 
Jekyll: http://jekyllrb.com/

It also comes with automatic blogging support, which would be a nice 
thing for D (having an official D blog reporting new, awesome stuff, 
anouncing new releases, etc., instead of relying on people to suscribe 
to the newsgroup).

If Walter wants to modify the copyright notice, he could modify the file 
_includes/copyright.html. No need to search for a macro named copyright.

If he wants to highlight D code, he can do:

{% highlight d %}
void some_code() {
}
{% endhighlight %}

because GitHub already colors D code.
Jul 15 2013
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/15/2013 6:12 AM, Ary Borenszweig wrote:

 If Walter wants to modify the copyright notice, he could modify the file
 _includes/copyright.html. No need to search for a macro named copyright.


Are you also going to fix all your .c files to replace:

    #define ABC 3
    #define DEF(i) ((i) + 3)

with a separate file for every macro:

    #include "abc.h"
    #include "def.h"

?
Jul 15 2013
parent Ary Borenszweig <ary esperanto.org.ar> writes:
On 7/15/13 4:13 PM, Walter Bright wrote:

 On 7/15/2013 6:12 AM, Ary Borenszweig wrote:

 If Walter wants to modify the copyright notice, he could modify the file
 _includes/copyright.html. No need to search for a macro named copyright.


 Are you also going to fix all your .c files to replace:

     #define ABC 3
     #define DEF(i) ((i) + 3)

 with a separate file for every macro:

     #include "abc.h"
     #include "def.h"

 ?


I think writing a program and writing a static website are totally 
different things.

If you want to reuse something in a static website you use a partial: 
something that's included. You can optionally pass parameters to that 
partial.

What you usually want to include is HTML, not a value or an expression, 
so it makes sense to put it in a separate html (markdown, whatever) file.

Yes, it's similar to a macro, but that's how *everyone* is doing web 
development.
Jul 15 2013
prev sibling parent "Chad Joan" <chadjoan gmail.com> writes:
On Monday, 15 July 2013 at 13:12:38 UTC, Ary Borenszweig wrote:

 You can also try GitHub pages. And since D already has its code 
 in github it's very simple.

 http://pages.github.com/


I would advise against, since this creates a strong dependency on 
github.  Currently the community would be able to move to another 
git hosting setup without code changes (at least not significant 
ones, AFAIK).  Moving the website to a 
web-service-provider-specific language would create vendor 
lock-in.
Jul 17 2013
prev sibling next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Sunday, 14 July 2013 at 20:35:45 UTC, Walter Bright wrote:

 On 7/14/2013 6:49 AM, Dicebot wrote:

 But maintaining
 whole stuff via git repo + makefiles is definitely cumbersome, 
 no idea why that
 was chosen.


 1. github is how the entire rest of D is maintained, it would 
 be strange if the website was handled via some completely 
 different system.

 2. github is of proven utility in enabling anyone to contribute 
 to the web site via pull requests.

 3. github/makefiles are how everything else in dlang is done, 
 so contributors should already be familiar with the process.


Yeah, sure, I have no problem having website itself maintained 
via GitHub - but in my opinion it makes it much more static than 
it should be. For example, I'd absolutely love to see news & 
announcements added to the main page but don't see how it is 
going to happen if adding single piece of content goes through 
pull request procedure. Latency issues, by the time it is merged, 
information is likely to become irrelevant.

That is the only thing that catches my attention as an area of 
improvement - from non-web guy point of view, of course.
Jul 15 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/15/2013 3:08 AM, Dicebot wrote:

 Yeah, sure, I have no problem having website itself maintained via GitHub - but
 in my opinion it makes it much more static than it should be. For example, I'd
 absolutely love to see news & announcements added to the main page but don't
see
 how it is going to happen if adding single piece of content goes through pull
 request procedure. Latency issues, by the time it is merged, information is
 likely to become irrelevant.


That's why the d_programming twitter feed was added to the front page.

In any case, Ddoc can be used to insert the contents of an "announcements" file 
into the front page. The problem, however, is someone has to write those 
announcements on a timely basis. Nobody has shown any interest in doing so, and 
although I've tried to do it on numerous occaisions, I just lose steam rather 
quickly because it bores me to tears.

The twitter feed is as easy as it gets, and I still don't regularly post to it. 
(Andrei also posts to the d_programming feed.)
Jul 15 2013
parent reply "Dicebot" <public dicebot.lv> writes:
On Monday, 15 July 2013 at 19:20:00 UTC, Walter Bright wrote:

 That's why the d_programming twitter feed was added to the 
 front page.


Twitter is incredibly restrictive in its format. People coming to 
front page want to get a detailed explained overview of latest 
news, not 140-symbol mysteries. Also it ties important 
information channel to an external closed service which is never 
good for the reputation.

And as cherry on top - I don't see and embedded twitter feeds on 
dlang.org right now ;)


 In any case, Ddoc can be used to insert the contents of an 
 "announcements" file into the front page. The problem, however, 
 is someone has to write those announcements on a timely basis. 
 Nobody has shown any interest in doing so, and although I've 
 tried to do it on numerous occasions, I just lose steam rather 
 quickly because it bores me to tears.


And how do you expect someone to show the interest? :) Currently 
there are no tools for proposing front page news other than 
making pull requests which has unacceptable latency for news 
anyway. Dead end!

One of best ways to have lot of contributions is making each 
single one as easy as possible.
Jul 15 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/15/2013 12:39 PM, Dicebot wrote:

 On Monday, 15 July 2013 at 19:20:00 UTC, Walter Bright wrote:

 That's why the d_programming twitter feed was added to the front page.


 Twitter is incredibly restrictive in its format. People coming to front page
 want to get a detailed explained overview of latest news, not 140-symbol
 mysteries.


Given how enormously popular Twitter is for breaking news and announcements, I 
think you're wrong about that.



 Also it ties important information channel to an external closed
 service which is never good for the reputation.


I don't understand that comment. The twitter feed only shows d_programming
tweets.



 And as cherry on top - I don't see and embedded twitter feeds on dlang.org
right
 now ;)


I don't either - I don't know what happened there.



 And how do you expect someone to show the interest? :) Currently there are no
 tools for proposing front page news other than making pull requests which has
 unacceptable latency for news anyway. Dead end!


A large number of improvements have been made by someone showing enough
interest 
to actually drive forward the changes needed to support their interest. For 
example, Brad Roberts and Bugzilla. Vladimir and the D forum software. Etc.



 One of best ways to have lot of contributions is making each single one as easy
 as possible.


It doesn't get easier than twitter.
Jul 15 2013
parent reply "Dicebot" <public dicebot.lv> writes:
On Monday, 15 July 2013 at 19:54:54 UTC, Walter Bright wrote:

 Given how enormously popular Twitter is for breaking news and 
 announcements, I think you're wrong about that.


I have just check web pages for several popular programming 
languages and have found zero using twitter instead of a news 
feed. Popular? Applying general statistics (internet users) to an 
extremely narrow specialized group of people (programming 
language consumers) is not going to work.


 Also it ties important information channel to an external 
 closed
 service which is never good for the reputation.




It is a service that belongs to specific corporation and is 
completely controlled by one providing no means for federation 
and/or self-hosting. Random move from Twitter and D web site can 
loose its only news feed. Outsourcing primary infrastructure does 
not smell good.


 A large number of improvements have been made by someone 
 showing enough interest to actually drive forward the changes 
 needed to support their interest. For example, Brad Roberts and 
 Bugzilla. Vladimir and the D forum software. Etc.


Which mostly highlights how awesome some members of D community 
are :) But why not lower entry barrier? By the way, I have 
already asked a question in that regard - if someone comes up 
with a more dynamic web site implementation which is still based 
on D stack, will it be accepted?
Jul 15 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/15/2013 1:11 PM, Dicebot wrote:

 On Monday, 15 July 2013 at 19:54:54 UTC, Walter Bright wrote:

 Given how enormously popular Twitter is for breaking news and announcements, I
 think you're wrong about that.


 I have just check web pages for several popular programming languages and have
 found zero using twitter instead of a news feed. Popular? Applying general
 statistics (internet users) to an extremely narrow specialized group of people
 (programming language consumers) is not going to work.


Watch the news - many times the news reporters will remark that they not only 
get their breaking news from twitter, they'll show the tweets as part of the 
broadcast.

Twitter for news is mainstream.



 It is a service that belongs to specific corporation and is completely
 controlled by one providing no means for federation and/or self-hosting. Random
 move from Twitter and D web site can loose its only news feed. Outsourcing
 primary infrastructure does not smell good.


If twitter ceases to be useful, we'll move to something else. Note that we also 
rely on github and Amazon S3. We do self-host this n.g., which has been nice in 
keeping it fairly free of spam & trolls.



 Which mostly highlights how awesome some members of D community are :) But why
 not lower entry barrier?


Because somebody has to step up and do the work for that. Note that there is no 
paid IT infrastructure staff. Change is driven by somebody self-appointing 
themselves champion and driving their agenda forward.



 By the way, I have already asked a question in that
 regard - if someone comes up with a more dynamic web site implementation which
 is still based on D stack, will it be accepted?


If it is obviously awesome, sure. If it isn't, or if it is only marginally 
better, or same only different, then no.
Jul 15 2013
parent "Elvis" <nospam pureworld.com> writes:
On Monday, 15 July 2013 at 20:34:07 UTC, Walter Bright wrote:

 On 7/15/2013 1:11 PM, Dicebot wrote:

 On Monday, 15 July 2013 at 19:54:54 UTC, Walter Bright wrote:

 Given how enormously popular Twitter is for breaking news and 
 announcements, I
 think you're wrong about that.


 I have just check web pages for several popular programming 
 languages and have
 found zero using twitter instead of a news feed. Popular? 
 Applying general
 statistics (internet users) to an extremely narrow specialized 
 group of people
 (programming language consumers) is not going to work.


 Watch the news - many times the news reporters will remark that 
 they not only get their breaking news from twitter, they'll 
 show the tweets as part of the broadcast.

 Twitter for news is mainstream.



 It is a service that belongs to specific corporation and is 
 completely
 controlled by one providing no means for federation and/or 
 self-hosting. Random
 move from Twitter and D web site can loose its only news feed. 
 Outsourcing
 primary infrastructure does not smell good.


 If twitter ceases to be useful, we'll move to something else. 
 Note that we also rely on github and Amazon S3. We do self-host 
 this n.g., which has been nice in keeping it fairly free of 
 spam & trolls.



 Which mostly highlights how awesome some members of D 
 community are :) But why
 not lower entry barrier?


 Because somebody has to step up and do the work for that. Note 
 that there is no paid IT infrastructure staff. Change is driven 
 by somebody self-appointing themselves champion and driving 
 their agenda forward.



 By the way, I have already asked a question in that
 regard - if someone comes up with a more dynamic web site 
 implementation which
 is still based on D stack, will it be accepted?


 If it is obviously awesome, sure. If it isn't, or if it is only 
 marginally better, or same only different, then no.


FYI, Twitter is blocked here in China. Web pages which need to 
parse Twitter or other blocked services related stuff become 
unresponsive for a long time before showing other stuff normally.
Jul 15 2013
prev sibling parent reply "Borden" <2013 bordenrhodes.com> writes:
On Sunday, 14 July 2013 at 20:35:45 UTC, Walter Bright wrote:

 3. HTML, PDF, Ebook, and CHM outputs are generated from Ddoc.


Walter, with respect, I know you're too smart to be saying 
something silly like this. Surely you know that ebooks and CHM 
are specially-compiled HTML files. To imply that DDoc, and not 
HTML, is the common denominator between these outputs brings me 
to the acme of frustration as I have said over and over again 
that, at the very least, ebooks depend upon good HTML output.

To this end, I have tried for months to help bring dlang.org up 
to HTML 5 standard if, for no other end, to be able to compile 
the spec into an epub format. I even toed the github waters by 
submitting a trivially simple PR which, for the past months, has 
gone completely ignored.

In the meantime, my offers on help with other dlang.org PRs have 
also gone ignored. The thread in which I keep offering to help 
(Dlang spec rewrite) has gone ignored. To argue that 
contributions are not languishing or that volunteers are not 
being ignored necessarily means that I do not exist.

If I have learnt one thing in the past few months, it is that any 
attempt to dispute using DDoc to program an entire website is a 
fool's exercise. Despite vocal objections from the plebian 
masses, the DDoc architects and maintainers will stubbornly 
defend its usefulness. One can hardly blame them: wouldn't any of 
us defend code that we had carefully designed or write?

Therefore, dlang.org will stay, for better or worse, in DDoc. 
It's not worth arguing. As for willing contributors, it seems to 
me that the maintainers have an agenda to which they are 
adhering. Contributions focussed on other areas are diversions.

Have I said anything that is factually incorrect?
Jul 23 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/23/2013 2:23 AM, Borden wrote:

 On Sunday, 14 July 2013 at 20:35:45 UTC, Walter Bright wrote:

 3. HTML, PDF, Ebook, and CHM outputs are generated from Ddoc.


 Walter, with respect, I know you're too smart to be saying something silly like
 this. Surely you know that ebooks and CHM are specially-compiled HTML files. To
 imply that DDoc, and not HTML, is the common denominator between these outputs
 brings me to the acme of frustration as I have said over and over again that,
at
 the very least, ebooks depend upon good HTML output.


It's true that they are based on HTML output. However, and this is a big 
however, they need significantly different HTML output than one puts on a web 
site. This is currently accomplished by changing the macro definitions that
Ddoc 
uses, and by carefully recoding the Ddoc source to use those macros. While 
generating ebooks is often billed as "just pipe your website HTML through our 
converter program!" the reality is that you'll get more or less utter garbage
if 
you try that.

I've published several ebooks that also exist as web pages, so I'm familiar
with 
the process.


 To this end, I have tried for months to help bring dlang.org up to HTML 5
 standard if, for no other end, to be able to compile the spec into an epub
 format. I even toed the github waters by submitting a trivially simple PR
which,
 for the past months, has gone completely ignored.


I assume this one is it?

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

I posted a response. (But in general, PR's that are flagged as "We can’t 
automatically merge this pull request" tend to not get much attention. Despite 
that, we can and should do better.)

Can you please make some PR's which illustrate your work in converting it to
HTML 5?



 In the meantime, my offers on help with other dlang.org PRs have also gone
 ignored. The thread in which I keep offering to help (Dlang spec rewrite) has
 gone ignored. To argue that contributions are not languishing or that
volunteers
 are not being ignored necessarily means that I do not exist.


http://forum.dlang.org/post/ypcykidvradkrhnobaey forum.dlang.org

has quite a few responses; more than most threads.



 If I have learnt one thing in the past few months, it is that any attempt to
 dispute using DDoc to program an entire website is a fool's exercise. Despite
 vocal objections from the plebian masses, the DDoc architects and maintainers
 will stubbornly defend its usefulness. One can hardly blame them: wouldn't any
 of us defend code that we had carefully designed or write?

 Therefore, dlang.org will stay, for better or worse, in DDoc. It's not worth
 arguing. As for willing contributors, it seems to me that the maintainers have
 an agenda to which they are adhering. Contributions focussed on other areas are
 diversions.


Of course we have an agenda :-)

The arguments were (I thought) well laid out in that thread and responded to. 
Reasonable people can disagree - it doesn't mean that one side is irrational.
Jul 23 2013
next sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Tuesday, 23 July 2013 at 21:00:08 UTC, Walter Bright wrote:

 But in general, PR's that are flagged as "We can’t 
 automatically merge this pull request" tend to not get much 
 attention. Despite that, we can and should do better.


Only committers see that notice. Contributors who do not have 
commit access do not see that notice. If you need a pull request 
author to update their pull request, you need to let them know 
explicitly.
Jul 23 2013
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/23/2013 4:57 PM, Vladimir Panteleev wrote:

 On Tuesday, 23 July 2013 at 21:00:08 UTC, Walter Bright wrote:

 But in general, PR's that are flagged as "We can’t automatically merge this
 pull request" tend to not get much attention. Despite that, we can and should
 do better.


 Only committers see that notice. Contributors who do not have commit access do
 not see that notice. If you need a pull request author to update their pull
 request, you need to let them know explicitly.


Ah, I had no idea that was true. Thanks for letting me know!
Jul 23 2013
parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Tuesday, July 23, 2013 17:42:30 Walter Bright wrote:

 On 7/23/2013 4:57 PM, Vladimir Panteleev wrote:

 On Tuesday, 23 July 2013 at 21:00:08 UTC, Walter Bright wrote:

 But in general, PR's that are flagged as "We can’t automatically merge
 this
 pull request" tend to not get much attention. Despite that, we can and
 should do better.


 
 Only committers see that notice. Contributors who do not have commit
 access do not see that notice. If you need a pull request author to
 update their pull request, you need to let them know explicitly.


 
 Ah, I had no idea that was true. Thanks for letting me know!


Agreed. I didn't realize that that was the case either. Thanks Vladimir!

- Jonathan M Davis
Jul 23 2013
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-07-24 01:57, Vladimir Panteleev wrote:


 Only committers see that notice. Contributors who do not have commit
 access do not see that notice. If you need a pull request author to
 update their pull request, you need to let them know explicitly.


I thought I he was referring to the auto tester? Anyway, the auto tester 
will indicate if the merge failed. Or if it failed to compile, run and 
run the tests.

-- 
/Jacob Carlborg
Jul 23 2013
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Wednesday, 24 July 2013 at 06:44:25 UTC, Jacob Carlborg wrote:

 On 2013-07-24 01:57, Vladimir Panteleev wrote:


 Only committers see that notice. Contributors who do not have 
 commit
 access do not see that notice. If you need a pull request 
 author to
 update their pull request, you need to let them know 
 explicitly.


 I thought I he was referring to the auto tester? Anyway, the 
 auto tester will indicate if the merge failed. Or if it failed 
 to compile, run and run the tests.


This does not apply to the dlang.org repo, which is not being 
tested.
Jul 24 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-07-24 12:16, Vladimir Panteleev wrote:


 This does not apply to the dlang.org repo, which is not being tested.


Right. It should though, then it can catch merge and compile errors.

-- 
/Jacob Carlborg
Jul 24 2013
prev sibling parent reply "Borden" <2013 bordenrhodes.com> writes:
Better late than never (the last couple weeks have been very 
busy):

On Tuesday, 23 July 2013 at 21:00:08 UTC, Walter Bright wrote:

 It's true that they are based on HTML output. However, and this 
 is a big however, they need significantly different HTML output 
 than one puts on a web site. This is currently accomplished by 
 changing the macro definitions that Ddoc uses, and by carefully 
 recoding the Ddoc source to use those macros. While generating 
 ebooks is often billed as "just pipe your website HTML through 
 our converter program!" the reality is that you'll get more or 
 less utter garbage if you try that.

 I've published several ebooks that also exist as web pages, so 
 I'm familiar with the process.


I don't entirely agree with this, although I understand where 
you're coming from. The cost/benefit of settling this firmly 
favours the costs, so I'll let it slide.


 I assume this one is it?

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

 I posted a response. (But in general, PR's that are flagged as 
 "We can’t automatically merge this pull request" tend to not 
 get much attention. Despite that, we can and should do better.)

 Can you please make some PR's which illustrate your work in 
 converting it to HTML 5?


Well, I can't, as I've said a few times, because I was instructed 
to wait for 
https://github.com/D-Programming-Language/dlang.org/pull/271 to 
get merged, which, I'm told, will shorten my workload 
considerably. I realise, since complaining about it, that you've 
commented on that PR. Maybe, if I have some time, I'll try to 
tackle it so that it'll automerge (which is tricky because merges 
are a moving target).


 http://forum.dlang.org/post/ypcykidvradkrhnobaey forum.dlang.org

 has quite a few responses; more than most threads.


But I'm afraid that's analogous to saying "Whilst it is true that 
we haven't come around to fix your collapsed roof, we've picked 
up when you called more often than we have for other customers, 
so I don't see what you're upset about."


 The arguments were (I thought) well laid out in that thread and 
 responded to. Reasonable people can disagree - it doesn't mean 
 that one side is irrational.


My training is in business, not computer science. One learns in 
business school that the successful companies satisfy the needs 
of a particular market. When the customers' needs drift from what 
the business produces - as invariably happens in almost all 
markets - the business can either adapt to its changing 
environment or invite competitors to do its job for them.

Therefore, regardless of how irrational your customers are, there 
is often a benefit to giving them what they want.
Aug 10 2013
parent Walter Bright <newshound2 digitalmars.com> writes:
On 8/10/2013 6:06 AM, Borden wrote:

 Therefore, regardless of how irrational your customers are, there is often a
 benefit to giving them what they want.


Rarely do all customers want the same thing.
Aug 10 2013
prev sibling next sibling parent reply "John Colvin" <john.loughran.colvin gmail.com> writes:
Anyone know what happen to the prototype that someone made using 
vibe.d?

It looked really good, and worked a lot faster than the current 
one. It was roughly modelled on the php docs.
Jul 15 2013
parent reply "Dicebot" <public dicebot.lv> writes:
On Monday, 15 July 2013 at 11:20:30 UTC, John Colvin wrote:

 Anyone know what happen to the prototype that someone made 
 using vibe.d?

 It looked really good, and worked a lot faster than the current 
 one. It was roughly modelled on the php docs.


This one: 
http://vibed.org/temp/d-programming-language.org/phobos/index.html 
?
Well, as far as I understand there were still some minor 
remaining issues and Sonke did not have time to continue tweaking 
it.

It does not use vibe.d though but "ddox" - a bit more intelligent 
ddoc spin-off (http://code.dlang.org/packages/ddox). Same static 
HTML files are generated there.
Jul 15 2013
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 15.07.2013 13:32, schrieb Dicebot:

 On Monday, 15 July 2013 at 11:20:30 UTC, John Colvin wrote:

 Anyone know what happen to the prototype that someone made using vibe.d?

 It looked really good, and worked a lot faster than the current one.
 It was roughly modelled on the php docs.


 
 This one:
 http://vibed.org/temp/d-programming-language.org/phobos/index.html ?
 Well, as far as I understand there were still some minor remaining
 issues and Sonke did not have time to continue tweaking it.
 
 It does not use vibe.d though but "ddox" - a bit more intelligent ddoc
 spin-off (http://code.dlang.org/packages/ddox). Same static HTML files
 are generated there.


The status is that I made two pull requests about five months ago and
not much happened since then in terms of response. This is why I didn't
really continue to (actively) search for any remaining issues.

https://github.com/D-Programming-Language/dlang.org/pull/267
https://github.com/D-Programming-Language/tools/pull/43
Jul 15 2013
prev sibling next sibling parent reply "Flamaros" <flamaros.xavier gmail.com> writes:
On Sunday, 14 July 2013 at 04:56:46 UTC, Val Markovic wrote:


 There's some low-hanging fruit with the site that shouldn't be 
 too hard to
 fix: there's an incredibly annoying "content flash" after any 
 page is
 loaded (it loads fine, you see the text, then the text 
 disappears for a
 second, then appears again).


The flash content bother me, because it breaks my scroll.

I think this web site is too much oriented on documentation. The 
home page must display news about D language, it will be great to 
have videos of DConf on it directly.

The documentation need to be a specific section that allow us to 
browse all versions (documentation is related to a specific 
version of the compiler).
Jul 15 2013
next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Monday, 15 July 2013 at 12:33:55 UTC, Flamaros wrote:

 The documentation need to be a specific section that allow us 
 to browse all versions (documentation is related to a specific 
 version of the compiler).


That is actually a good call. No reason why documentation part 
should be done in same way as rest of the website if styling 
stays the same.
Jul 15 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-07-15 14:46, Dicebot wrote:


 That is actually a good call. No reason why documentation part should be
 done in same way as rest of the website if styling stays the same.


Yes, exactly. Consider Ruby on Rails:

Main page: http://rubyonrails.org/
Guides: http://guides.rubyonrails.org/
API reference: http://api.rubyonrails.org/

They all look different. Different content works with different styles.

-- 
/Jacob Carlborg
Jul 15 2013
prev sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Jul 15, 2013 at 02:33:53PM +0200, Flamaros wrote:

 On Sunday, 14 July 2013 at 04:56:46 UTC, Val Markovic wrote:
 

There's some low-hanging fruit with the site that shouldn't be too
hard to fix: there's an incredibly annoying "content flash" after any
page is loaded (it loads fine, you see the text, then the text
disappears for a second, then appears again).


 
 The flash content bother me, because it breaks my scroll.


I turn off JS for dlang.org, and it's much more navigable. Seriously,
whatever it is that's causing that, needs to be removed. AFAICT, it's
just to generate the useless blob of links at the top of the page. We
need a *real* index, not a blob of links.



 I think this web site is too much oriented on documentation. The
 home page must display news about D language, it will be great to
 have videos of DConf on it directly.


I agree that news should be posted on the front page. I disagree that
it's too documentation-oriented, though. It *should* be documentation
oriented. Too many websites these days pay too much attention to frills
without delivering real content. I don't want the D website to turn into
that.



 The documentation need to be a specific section that allow us to
 browse all versions (documentation is related to a specific version
 of the compiler).


+1, docs for past releases should be available somewhere. (And by that I
mean somewhere navigable on a browser, not a .zip file download.)


T

-- 
Жил-был король когда-то, при нём блоха жила.
Jul 15 2013
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 15 July 2013 at 14:42:17 UTC, H. S. Teoh wrote:

 AFAICT, it's just to generate the useless blob of links
 at the top of the page.


I'm pretty sure the flash is hypenate.js. The links can mess up 
scrolling though as they appear.


 We need a *real* index, not a blob of links.


And, of course, it should be done server side. A while ago, I had 
a little program that generated one from the html.

It would end up looking like this:
http://arsdnet.net/d-web-site/std_stdio.html


This just takes ddoc generated html, parses it, and modifies it 
to add the table, so it can be done as a simple post processor in 
the makefile. It is probably out of date now, but if someone else 
is willing to go through the pull request and makefile editing 
hassle, I'll update the code and give it to you.


 Too many websites these days pay too much attention to frills
 without delivering real content.


Speaking of frills, that same folder on my box still has the code 
to add recent  (cached for 8 hours, so not 100% up to date) 
commits and announcements to a site:

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

(This predates the new dlang.org design). If we want the html to 
remain static, a way to do this would be to just link a <script> 
to the main site and have containers with fixed heights and 
static links. If js is enabled, the containers get filled up, and 
the fixed height ensures the page doesn't jump. If not, the 
static links still show so the space isn't wasted.

idk if it is worth it, I lean toward meh, but it would be pretty 
easily doable.
Jul 15 2013
prev sibling next sibling parent reply "Brad Anderson" <eco gnuk.net> writes:
On Sunday, 14 July 2013 at 04:56:46 UTC, Val Markovic wrote:

 There's some low-hanging fruit with the site that shouldn't be 
 too hard to
 fix: there's an incredibly annoying "content flash" after any 
 page is
 loaded (it loads fine, you see the text, then the text 
 disappears for a
 second, then appears again). I've cursed at this more than a 
 dozen times;
 it's especially annoying on any mobile browser.


https://github.com/D-Programming-Language/dlang.org/pull/352
Jul 15 2013
parent reply "Brad Anderson" <eco gnuk.net> writes:
On Monday, 15 July 2013 at 19:27:38 UTC, Brad Anderson wrote:

 On Sunday, 14 July 2013 at 04:56:46 UTC, Val Markovic wrote:

 There's some low-hanging fruit with the site that shouldn't be 
 too hard to
 fix: there's an incredibly annoying "content flash" after any 
 page is
 loaded (it loads fine, you see the text, then the text 
 disappears for a
 second, then appears again). I've cursed at this more than a 
 dozen times;
 it's especially annoying on any mobile browser.


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


Superseded by:

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

Everything but Chrome and Opera should be faster sitewide (Andrei 
has rsynced dlang.org already with these changes).  Chrome and 
Opera, unfortunately, do not support CSS3 hyphens so they still 
use the slow hyphenator.js.
Jul 15 2013
parent reply captaindet <2krnk gmx.net> writes:
On 2013-07-15 20:48, Brad Anderson wrote:

 unfortunately, do not support CSS3 hyphens so they still use the slow
 hyphenator.js.


pls remove hyphenator.js altogehter. i see everyone complaining about it and no
one wanting it. the words in the english language are usually short enough so
that hyphenation is not really necessary.

cheers,

det
Jul 16 2013
next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jul 16, 2013 at 10:16:28AM -0500, captaindet wrote:

 On 2013-07-15 20:48, Brad Anderson wrote:

unfortunately, do not support CSS3 hyphens so they still use the slow
hyphenator.js.


 
 pls remove hyphenator.js altogehter. i see everyone complaining about
 it and no one wanting it. the words in the english language are
 usually short enough so that hyphenation is not really necessary.


[...]

+1. If people are using browsers that don't support hyphenation, then so
be it. They will just get slightly more line-wrapping, that's all. No
harm done. This is too tiny a detail to pay such a big price (slow
loading, flashing, scrolling disruption, etc.) for.

(I'm one of those people whose browsers don't support hyphenation. That
doesn't make the site any less useful (I turned off JS on dlang.org
because hyphenator.js is so annoying -- the only difference I noticed
was that the site is significantly more usable that way). This is really
a nice-to-have feature that doesn't deserve the price we're paying for
it, not an indispensible feature.)


T

-- 
First Rule of History: History doesn't repeat itself -- historians merely
repeat each other.
Jul 16 2013
prev sibling parent reply Val Markovic <val markovic.io> writes:
Having hyphenator.js on the site slows down the browsing experience
immensely, especially on mobile. I know I personally avoid the
dlang.orgsite on my Galaxy Nexus and on my Nexus 7 because of this
reason.

Since the whole web is right-aligned and users would much rather have a
site that loads fast and without content flashes than a site with
hyphenation, I believe the library should be removed.

I say this as someone who is a typography nut and loves hyphenation. A
printed book without it is not worth buying. But the cost of implementing
it in JS for web pages is too high. There's a reason why no major website
uses this approach.


On Tue, Jul 16, 2013 at 9:27 AM, H. S. Teoh <hsteoh quickfur.ath.cx> wrote:


 On Tue, Jul 16, 2013 at 10:16:28AM -0500, captaindet wrote:

 On 2013-07-15 20:48, Brad Anderson wrote:

unfortunately, do not support CSS3 hyphens so they still use the slow
hyphenator.js.


 pls remove hyphenator.js altogehter. i see everyone complaining about
 it and no one wanting it. the words in the english language are
 usually short enough so that hyphenation is not really necessary.


 [...]

 +1. If people are using browsers that don't support hyphenation, then so
 be it. They will just get slightly more line-wrapping, that's all. No
 harm done. This is too tiny a detail to pay such a big price (slow
 loading, flashing, scrolling disruption, etc.) for.

 (I'm one of those people whose browsers don't support hyphenation. That
 doesn't make the site any less useful (I turned off JS on dlang.org
 because hyphenator.js is so annoying -- the only difference I noticed
 was that the site is significantly more usable that way). This is really
 a nice-to-have feature that doesn't deserve the price we're paying for
 it, not an indispensible feature.)


 T

 --
 First Rule of History: History doesn't repeat itself -- historians merely
 repeat each other.
Jul 16 2013
next sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Tuesday, 16 July 2013 at 20:10:15 UTC, Val Markovic wrote:

 Having hyphenator.js on the site slows down the browsing 
 experience
 immensely, especially on mobile. I know I personally avoid the
 dlang.orgsite on my Galaxy Nexus and on my Nexus 7 because of 
 this
 reason.

 Since the whole web is right-aligned and users would much 
 rather have a
 site that loads fast and without content flashes than a site 
 with
 hyphenation, I believe the library should be removed.

 I say this as someone who is a typography nut and loves 
 hyphenation. A
 printed book without it is not worth buying. But the cost of 
 implementing
 it in JS for web pages is too high. There's a reason why no 
 major website
 uses this approach.


Hyphenation is ok, but it's way over-eager on dlang.org

I have my thesis in front of me (LaTeXe) and there's roughly one 
hyphenation (is that even the right word?) per page, clever 
spacing manages the rest to get fully justified text. 
dlang.org/index.html has 26 full-width lines and 10 are 
hypenated! Even if you like hyphenation, that's just bad 
typesetting.

hyphenate.js needs to go. It's far too slow and the results 
aren't very good.
Jul 16 2013
prev sibling parent reply "Kagamin" <spam here.lot> writes:
Didn't see hypenation on the web before, looks alien to me. From 
the typesetting point of view I find manpages with a larger font 
pleasure to read.
http://man7.org/linux/man-pages/man3/fclose.3.html
They are neither justified nor hyphenated.
Jul 22 2013
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Jul 22, 2013 at 09:59:57PM +0200, Kagamin wrote:

 Didn't see hypenation on the web before, looks alien to me. From the
 typesetting point of view I find manpages with a larger font
 pleasure to read.
 http://man7.org/linux/man-pages/man3/fclose.3.html
 They are neither justified nor hyphenated.


Exactly. While justification/hyphenation are nice to have, they are
really only peripheral benefits. We should not be paying such a big
price for them. I really have a hard time understanding the rationale
behind trying to make hyphenation work, when the time could be much
better spent improving the D docs that newbies keep complaining about.


T

-- 
This sentence is false.
Jul 22 2013
parent reply "Brad Anderson" <eco gnuk.net> writes:
On Monday, 22 July 2013 at 20:49:09 UTC, H. S. Teoh wrote:

 On Mon, Jul 22, 2013 at 09:59:57PM +0200, Kagamin wrote:

 Didn't see hypenation on the web before, looks alien to me. 
 From the
 typesetting point of view I find manpages with a larger font
 pleasure to read.
 http://man7.org/linux/man-pages/man3/fclose.3.html
 They are neither justified nor hyphenated.


 Exactly. While justification/hyphenation are nice to have, they 
 are
 really only peripheral benefits. We should not be paying such a 
 big
 price for them. I really have a hard time understanding the 
 rationale
 behind trying to make hyphenation work, when the time could be 
 much
 better spent improving the D docs that newbies keep complaining 
 about.


 T


My recent changes to hyphenation were because Andrei vetoed my 
attempt to remove hyphenation so I spent some time trying to make 
it as bearable as possible.  Not much time has gone into it (and 
I'm not a great or qualified technical writer in any case).
Jul 22 2013
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Jul 22, 2013 at 11:48:10PM +0200, Brad Anderson wrote:

 On Monday, 22 July 2013 at 20:49:09 UTC, H. S. Teoh wrote:

On Mon, Jul 22, 2013 at 09:59:57PM +0200, Kagamin wrote:

Didn't see hypenation on the web before, looks alien to me. From the
typesetting point of view I find manpages with a larger font
pleasure to read.
http://man7.org/linux/man-pages/man3/fclose.3.html They are neither
justified nor hyphenated.


Exactly. While justification/hyphenation are nice to have, they are
really only peripheral benefits. We should not be paying such a big
price for them. I really have a hard time understanding the rationale
behind trying to make hyphenation work, when the time could be much
better spent improving the D docs that newbies keep complaining
about.




[...]

 My recent changes to hyphenation were because Andrei vetoed my
 attempt to remove hyphenation so I spent some time trying to make it
 as bearable as possible.  Not much time has gone into it (and I'm
 not a great or qualified technical writer in any case).


I think the best approach at this point is to leave CSS hyphenation
alone, and just remove/disable hyphenator.js. Removing *all* hyphenation
seems be a bit too heavy-handed.


T

-- 
I am a consultant. My job is to make your job redundant. -- Mr Tom
Jul 22 2013
parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 22 July 2013 at 22:35:20 UTC, H. S. Teoh wrote:

 On Mon, Jul 22, 2013 at 11:48:10PM +0200, Brad Anderson wrote:

 On Monday, 22 July 2013 at 20:49:09 UTC, H. S. Teoh wrote:

On Mon, Jul 22, 2013 at 09:59:57PM +0200, Kagamin wrote:

Didn't see hypenation on the web before, looks alien to me. 
From the
typesetting point of view I find manpages with a larger font
pleasure to read.
http://man7.org/linux/man-pages/man3/fclose.3.html They are 
neither
justified nor hyphenated.


Exactly. While justification/hyphenation are nice to have, 
they are
really only peripheral benefits. We should not be paying such 
a big
price for them. I really have a hard time understanding the 
rationale
behind trying to make hyphenation work, when the time could 
be much
better spent improving the D docs that newbies keep 
complaining
about.




 [...]

 My recent changes to hyphenation were because Andrei vetoed my
 attempt to remove hyphenation so I spent some time trying to 
 make it
 as bearable as possible.  Not much time has gone into it (and 
 I'm
 not a great or qualified technical writer in any case).


 I think the best approach at this point is to leave CSS 
 hyphenation
 alone, and just remove/disable hyphenator.js. Removing *all* 
 hyphenation
 seems be a bit too heavy-handed.


 T


That's exactly what the current state of the pull request is.
Jul 22 2013
prev sibling next sibling parent reply Martin Nowak <code dawg.eu> writes:
On 07/14/2013 05:19 AM, Val Markovic wrote:

  2. Looking at the Network data in the Chrome DevTools, realize the site
     isn't using a CDN. Make a note of mentioning this to the site
     maintainers; using a CDN is critical to performance and ever since
     CloudFlare came on the scene (fast & free CDN that's also trivial to
     set up) there's no excuse not to use one.


Yes, I get 40kB/s download rate and it takes 4s to load an uncompressed 
HTML file.
Compressing http://dlang.org/phobos/std_algorithm.html could save 
139.9KiB (82% reduction).


  4. Record a JavaScript profile of the site with the DevTools JS
     profiler and the new Flame view. With this information and the
     Timeline profile, realize that hypenate.js is probably the culprit
     of the content flash bug. Still have to verify this, it might be
     something else.


I takes more than 1s to run and is the dominating time waster.
https://github.com/D-Programming-Language/dlang.org/pull/352
Jul 22 2013
parent "Joseph Rushton Wakeling" <joseph.wakeling webdrake.net> writes:
On Monday, 22 July 2013 at 15:40:47 UTC, Martin Nowak wrote:

 On 07/14/2013 05:19 AM, Val Markovic wrote:

 2. Looking at the Network data in the Chrome DevTools, realize 
 the site
    isn't using a CDN. Make a note of mentioning this to the 
 site
    maintainers; using a CDN is critical to performance and 
 ever since
    CloudFlare came on the scene (fast & free CDN that's also 
 trivial to
    set up) there's no excuse not to use one.


 Yes, I get 40kB/s download rate and it takes 4s to load an 
 uncompressed HTML file.
 Compressing http://dlang.org/phobos/std_algorithm.html could 
 save 139.9KiB (82% reduction).


Not just about speed but also total data transfer, this is 
important for anyone using e.g. a mobile or tablet device with 3G 
data rather than wifi (as I was yesterday, working on a train:-)
Jul 23 2013
prev sibling next sibling parent reply "Ruslan Mullakhmetov" <nobody example.com> writes:
On Sunday, 14 July 2013 at 04:56:46 UTC, Val Markovic wrote:


 So, Andrei also mentioned how the community needs to improve the
 dlang.orgsite and make it a first-class priority. It's the 
 point of
 contact for
 newcomers so it's very important we get it right. Since I know a
 thing-or-two about web development, I decided to look into 
 improving the
 site.



Let me put my two cents at this thread, hope it would be useful.

(1) The thread went (from the start) to discussion of technical 
details, not content discussion, and users are interested in 
content itself, which, IMHO is not optimally organized.

(2) Flashing and slow responses are annoying but not so crucial 
(as from my experience), thought somebody waits for up to 7 
seconds to load web page - agree, that should be fixed, but 
again, i do not have such problem or didn't noticed (why?).

(3) dlang.org content organisation:
     (3.1) start page describes the language - very good, but it 
would be better if it also contains clear links (the big big 
buttons) to overview, download page, tutorial, documentation;
     (3.2) as were already mentioned the documentation should be 
extracted to dedicated site (either subdomain or subfolder) 
mainly to remove unnecessary at this section main site 
navigation. technically it would be better because documentation 
for sure have different markup / layout / page structure and 
probably would have different presentation. As for me I loved 
http://www.erlang.org/doc/man/edoc.html - clear, navigable, 
lightweight;
     (3.3) explicit language tutorial section would be great 
benefit (not doc->book->tutorial), language tour like for go 
language would be excellent.
     (3.4) explicit getting started page (infrastructure preparing)
     (3.4) are articles part of documentation?

(4) design and appearance:
     (4.1) fixed width layout - more readable, all typesetting 
books recommends line to be no more then 66 characters long;
     (4.2) scrolling navigation pane is annoying.
     (4.3) more lightweight and readable design: lighter 
background tones and darker foreground tones (people get used to 
read black symbols on white paper), thiner or zero borders, more 
explicit headers.

(5) external and outdated content: there are different d specific 
content outside dlang.org (i.e. source.org) containing tutorials, 
articles, source codes that is outdated and doesn't even compile. 
this mislead newbie, gets him irritated and force to quit 
learning language. if it is possible this content should be 
revised and incorporated to dlang.org and removed, because it 
breaks down all language marketing.

This just my thought that i hope could be useful, cause i'm a 
visual person type and got easily embarrassed by a lot of content 
especially when it is not well-formed =)
Aug 10 2013
next sibling parent reply "Brad Anderson" <eco gnuk.net> writes:
On Saturday, 10 August 2013 at 17:29:40 UTC, Ruslan Mullakhmetov 
wrote:

 (2) Flashing and slow responses are annoying but not so crucial 
 (as from my experience), thought somebody waits for up to 7 
 seconds to load web page - agree, that should be fixed, but 
 again, i do not have such problem or didn't noticed (why?).


This was mitigated somewhat by some updates to hyphenate.js and 
the Jump To generation that were made.  Now it's just slow.  The 
larger the page the longer it takes so it's most noticeable on 
big pages (I used the changelog page for testing because it's 
huge).
Aug 10 2013
parent reply "Kapps" <opantm2+spam gmail.com> writes:
On Saturday, 10 August 2013 at 18:22:53 UTC, Brad Anderson wrote:

 On Saturday, 10 August 2013 at 17:29:40 UTC, Ruslan 
 Mullakhmetov wrote:

 (2) Flashing and slow responses are annoying but not so 
 crucial (as from my experience), thought somebody waits for up 
 to 7 seconds to load web page - agree, that should be fixed, 
 but again, i do not have such problem or didn't noticed (why?).


 This was mitigated somewhat by some updates to hyphenate.js and 
 the Jump To generation that were made.  Now it's just slow.  
 The larger the page the longer it takes so it's most noticeable 
 on big pages (I used the changelog page for testing because 
 it's huge).


The documentation is still almost unusable for me. If I load a 
tab to view any documentation (example link: 

freeze Firefox (26, Nightly, happened with 25 and previous 
versions as well) completely for 10-20 seconds until it pops up 
asking if I want to stop hyphenate.js because it's taking too 
long. I had to block it with Adblock Plus for the documentation 
to be actually feasible to use. And this is on a fairly high end 
computer.
Aug 10 2013
parent reply Jeff Nowakowski <jeff dilacero.org> writes:
On 08/10/2013 04:32 PM, Kapps wrote:

 The documentation is still almost unusable for me. If I load a tab to
 view any documentation (example link:

 Firefox (26, Nightly, happened with 25 and previous versions as well)
 completely for 10-20 seconds until it pops up asking if I want to stop
 hyphenate.js because it's taking too long. I had to block it with
 Adblock Plus for the documentation to be actually feasible to use. And
 this is on a fairly high end computer.



It's not important that some users find it unusable. What's more 
important is that users get hyphenation, whether they like it or not.
Aug 10 2013
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sat, Aug 10, 2013 at 05:59:08PM -0400, Jeff Nowakowski wrote:

 On 08/10/2013 04:32 PM, Kapps wrote:

The documentation is still almost unusable for me. If I load a tab to
view any documentation (example link:

Firefox (26, Nightly, happened with 25 and previous versions as well)
completely for 10-20 seconds until it pops up asking if I want to
stop hyphenate.js because it's taking too long. I had to block it
with Adblock Plus for the documentation to be actually feasible to
use. And this is on a fairly high end computer.


 
 
 It's not important that some users find it unusable. What's more
 important is that users get hyphenation, whether they like it or
 not.


I assume you meant that sarcastically, 'cos this hyphenate.js problem
has been plaguing us for how long now, and nobody wants to fix it. :-(

We keep talking about not adding more features to D that don't pull
their own weight, but here's hyphenate.js, that causes all sorts of
problems that users are endlessly complaining about, yet only provides
functionality of marginal value (that hardly anybody even notices,
except when it screws up, like hyphenating identifiers where it
shouldn't). But everyone who tries to do something about it gets
stonewalled.

I guess I'll just continue using dlang.org with JS turned off. *shrug*


T

-- 
Many open minds should be closed for repairs. -- K5 user
Aug 10 2013
prev sibling parent "Craig Dillabaugh" <cdillaba cg.scs.carleton.ca> writes:
On Saturday, 10 August 2013 at 17:29:40 UTC, Ruslan Mullakhmetov
wrote:

 clip

 Let me put my two cents at this thread, hope it would be useful.

 (1) The thread went (from the start) to discussion of technical 
 details, not content discussion, and users are interested in 
 content itself, which, IMHO is not optimally organized.

 clip


Motiviated by Ruslan's comments I thought I would make a
suggestion I had been thinking of with regards to the Forums. The
Forums organization seems a bit out of date. For example there
are a number of topics that are rarely ever receive posts, but
they appear before busy forums, such as D.learn. I wonder if this
might be one of the reasons why obvious learner questions get
posted to digitialmars.D on occassion. Any easy way to deal with
this would be to sort forums by post count rather than
alphabetically, but that has its own issues.


Perhaps the D forums could be split into two separate headings:

1. D Programming - general D related programming questions could
go here. It could include:
-  D.learn (More focused for newer D users)
-  D.phobos (questions about use of standard library)
-  D.programming (more advanced questions)
-  Debugging/Profiling (was digitalmars.D.debugger - on first
reading sounds like the forum is

2. D Development (this isn't a great name - but it would include
forums
more focused on the Development of the D language). Some topics
might
include:
- current digitalmars.D forum
- announce
- digitalmars.D.bugs
- digitalmars.D.ldc
- D.gnu
- dmd-beta
- dmd-concurrency
- dmd-internals
- phobos
- D-runtime

I exclusively use the Forum's and perhaps such a reorganization
would be too much trouble for folks who uses newreaders/email,
but I thought I would but the suggestion out there.
Aug 14 2013
prev sibling parent reply "Flamaros" <flamaros.xavier gmail.com> writes:
I found a nice documentation website :
http://docs.autodesk.com/FBX/2014/ENU/FBX-SDK-Documentation/index.html?url=cpp_ref/_common_2_common_8cxx-example.html,topicNumber=cpp_ref__common_2_common_8cxx_example_htmlc507b7ce-aa2f-4c44-b08f-90c94f43730b

There is all sources of sample, and code is highlighted with link 
to methods docs.
I think it will be a good thing to have real unittest linked with 
the documentation of D, just because instead embedded samples we 
are sure that is executable as it (no missing import, syntax 
error,...).
It seems that is a bad idea to have specific code samples for the 
documentation, it's generally out of date,... Is it feasible to 
have docs that extract chunks of real unittest as samples?
Aug 14 2013
parent "Kapps" <opantm2+spam gmail.com> writes:
On Wednesday, 14 August 2013 at 15:25:09 UTC, Flamaros wrote:

 I found a nice documentation website :
 http://docs.autodesk.com/FBX/2014/ENU/FBX-SDK-Documentation/index.html?url=cpp_ref/_common_2_common_8cxx-example.html,topicNumber=cpp_ref__common_2_common_8cxx_example_htmlc507b7ce-aa2f-4c44-b08f-90c94f43730b

 There is all sources of sample, and code is highlighted with 
 link to methods docs.
 I think it will be a good thing to have real unittest linked 
 with the documentation of D, just because instead embedded 
 samples we are sure that is executable as it (no missing 
 import, syntax error,...).
 It seems that is a bad idea to have specific code samples for 
 the documentation, it's generally out of date,... Is it 
 feasible to have docs that extract chunks of real unittest as 
 samples?


D has documented unit tests (Documented Unittests section at 
http://dlang.org/unittest.html) but they're a relatively new 
feature so most of the documentation doesn't yet use them.
Aug 14 2013