www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Some feedback on the website.

reply deadalnix <deadalnix gmail.com> writes:
Navigation:

The navigation can get very confusing. The forum and the site 
look the same, but the logo in the top right bring back to the 
site index/forum index . That is not what is expected. If it 
looks the same, it should probably be doing the same.

Especially since the forum index is in the breadcrumb.

On the forum, the link to the website is in fact in the left bar, 
as last position. It is probably out of screen on my laptop 
screen (15').

On the website, the forum is hidden in the community menu in the 
middle of the left bar called community. If it warrant its own 
domain name, it should probably not be hidden.

Generally, the importance of various items doesn't seems to make 
any logical sense. What is logo worthy somewhere is hidden in a 
menu somewhere else, or vice versa.

Both left bar kind of look the same but aren't. That's quite 
bizarre and looks amateurish. On the website, categories in the 
left bar, there are + and - sign that looks like button to 
open/close the category, but they aren't button. It breaks common 
expectations.

Search :

The same confusion can be found in the search. One can search the 
whole D website, including the forum, while the navigation 
clearly split the 2 as very different entities.

There is no way to search the spec.

HTTPS:

Forum widgets on the front page are broken in https.
Various links are still in http.
Some function prompt security warning :
  - Forum certification
  - Search Function

Home page:

This is a mess. There is way too much here. There is an attention 
budget and it is important to manage it well.

The usual for a programming language goes as follow :
  - Logo, color as per branding.
  - Language name, quick blurb about what it is, usually ending 
with a link to tutorial.
  - Big fat download button.
  - Some sample code. The one we have on the front page is way too 
big. It should be a piece of code that someone with 0 experience 
in the language can understand.
  - A menu with quick access to what more experienced users want : 
stdlib reference, code repository, wiki, forum, language spec, 
news, this kind of thing.

Some examples:
http://www.scala-lang.org/
https://nodejs.org/en/
https://developer.apple.com/swift/
https://golang.org/
https://www.rust-lang.org/

Our is just messed up. The download link is there, but just 
doesn't stand out (same presentation as this week in D, videos 
from DConf, as big as the changelog).

The code sample is so big that is doesn't fit on my laptop screen 
(15'). It uses all kind of feature that don't belong as a first 
exposure. When you learn English, you start with "Brian is in the 
kitchen" not Shakespeare.

All of this is quite damaging to D's brand.

Even even though I'm not a webdev, I've been working in growth 
for a long time and these things matter. I don't know DDoc, and 
I'm not sure this is a very smart move. That raise the barrier to 
contribute to the website. The intersection of people that know 
webdev and DDoc is just mostly existent.

The time I can spend on this is quite limited due to SDC, work 
and personal life. Learning DDoc is just too big of a barrier. 
Yet I can provide support to anyone that is willing to help.

Last but not least, it wouldn't hurt to hire a designer to have 
something slick.
Dec 14 2015
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-15 08:07, deadalnix wrote:

[snip]

 All of this is quite damaging to D's brand.

 Even even though I'm not a webdev, I've been working in growth for a
 long time and these things matter. I don't know DDoc, and I'm not sure
 this is a very smart move. That raise the barrier to contribute to the
 website. The intersection of people that know webdev and DDoc is just
 mostly existent.

 The time I can spend on this is quite limited due to SDC, work and
 personal life. Learning DDoc is just too big of a barrier. Yet I can
 provide support to anyone that is willing to help.

 Last but not least, it wouldn't hurt to hire a designer to have
 something slick.


I agree with all this, especially the last part about Ddoc.

-- 
/Jacob Carlborg
Dec 15 2015
parent reply Gary Willoughby <dev nomad.so> writes:
On Tuesday, 15 December 2015 at 08:26:44 UTC, Jacob Carlborg 
wrote:

 On 2015-12-15 08:07, deadalnix wrote:

 [snip]

 All of this is quite damaging to D's brand.

 Even even though I'm not a webdev, I've been working in growth 
 for a
 long time and these things matter. I don't know DDoc, and I'm 
 not sure
 this is a very smart move. That raise the barrier to 
 contribute to the
 website. The intersection of people that know webdev and DDoc 
 is just
 mostly existent.

 The time I can spend on this is quite limited due to SDC, work 
 and
 personal life. Learning DDoc is just too big of a barrier. Yet 
 I can
 provide support to anyone that is willing to help.

 Last but not least, it wouldn't hurt to hire a designer to have
 something slick.


 I agree with all this, especially the last part about Ddoc.


We've all said time and time again if ddoc wasn't used for the 
entire site more people would help with it. Ddoc makes sense for 
the documentation but not everything else.

I thought Sociomantic were re-designing and sorting the site out?
Dec 15 2015
next sibling parent reply tcak <1ltkrs+3wyh1ow7kzn1k sharklasers.com> writes:
On Tuesday, 15 December 2015 at 08:31:40 UTC, Gary Willoughby 
wrote:

 On Tuesday, 15 December 2015 at 08:26:44 UTC, Jacob Carlborg 
 wrote:

 On 2015-12-15 08:07, deadalnix wrote:

 [snip]

 All of this is quite damaging to D's brand.

 Even even though I'm not a webdev, I've been working in 
 growth for a
 long time and these things matter. I don't know DDoc, and I'm 
 not sure
 this is a very smart move. That raise the barrier to 
 contribute to the
 website. The intersection of people that know webdev and DDoc 
 is just
 mostly existent.

 The time I can spend on this is quite limited due to SDC, 
 work and
 personal life. Learning DDoc is just too big of a barrier. 
 Yet I can
 provide support to anyone that is willing to help.

 Last but not least, it wouldn't hurt to hire a designer to 
 have
 something slick.


 I agree with all this, especially the last part about Ddoc.


 We've all said time and time again if ddoc wasn't used for the 
 entire site more people would help with it. Ddoc makes sense 
 for the documentation but not everything else.

 I thought Sociomantic were re-designing and sorting the site 
 out?


The harder it is made for people to contribute the system for 
fixations, the lesser changes are seen.

It bothers me so much to report a bug on https://issues.dlang.org 
. The reason is that the password stops working for me. Firefox 
saves the username and password. I try to use it after 2 months, 
and whops, system says it isn't available.

Another issue is contributing the website's design. I reported a 
problem on the forum that is about the title problem of web page. 
http://forum.dlang.org/thread/pymfyjuckxbvjolxlczg forum.dlang.org Still the
problem will be fixed.

Now I am asking, IF I was to make some changes for web site's 
look, and post a picture of them (CSS changes mostly), would it 
be okay to discuss it here, and apply them in short notice? If a 
change would take 1 week, that doesn't work. I am
offering help here.
Dec 15 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/15/15 5:54 AM, tcak wrote:

 The harder it is made for people to contribute the system for fixations,
 the lesser changes are seen.


I don't think we've had many contributions via the "Improve this page" 
button.


 It bothers me so much to report a bug on https://issues.dlang.org . The
 reason is that the password stops working for me. Firefox saves the
 username and password. I try to use it after 2 months, and whops, system
 says it isn't available.

 Another issue is contributing the website's design. I reported a problem
 on the forum that is about the title problem of web page.
 http://forum.dlang.org/thread/pymfyjuckxbvjolxlczg forum.dlang.org Still
 the problem will be fixed.

 Now I am asking, IF I was to make some changes for web site's look, and
 post a picture of them (CSS changes mostly), would it be okay to discuss
 it here, and apply them in short notice? If a change would take 1 week,
 that doesn't work. I am
 offering help here.


Yes, the css has grown long in the teeth. Just replacing it with 
something else is needed, even if it's not an actual improvement.

A related idea is to investigate the use of 
http://sourcefoundry.org/hack/ for the code samples. Takers?


Andrei
Dec 15 2015
next sibling parent reply deadalnix <deadalnix gmail.com> writes:
On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu 
wrote:

 On 12/15/15 5:54 AM, tcak wrote:

 The harder it is made for people to contribute the system for 
 fixations,
 the lesser changes are seen.


 I don't think we've had many contributions via the "Improve 
 this page" button.


I don't know how representative it is, but once in a while, i 
forgot all of this is in DDoc, I notice something, what to do a 
quick patch, and end up being reminded this is in DDoc and I have 
no idea how to fix the thing, because suddenly, what looked like 
a quick fix end up being learning a new macro language.
Dec 15 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/15/2015 04:45 PM, deadalnix wrote:

 On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote:

 On 12/15/15 5:54 AM, tcak wrote:

 The harder it is made for people to contribute the system for fixations,
 the lesser changes are seen.


 I don't think we've had many contributions via the "Improve this page"
 button.


 I don't know how representative it is, but once in a while, i forgot all
 of this is in DDoc, I notice something, what to do a quick patch, and
 end up being reminded this is in DDoc and I have no idea how to fix the
 thing, because suddenly, what looked like a quick fix end up being
 learning a new macro language.


It seems knowing ddoc is part of knowing D. -- Andrei
Dec 15 2015
next sibling parent reply deadalnix <deadalnix gmail.com> writes:
On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei 
Alexandrescu wrote:

 It seems knowing ddoc is part of knowing D. -- Andrei


I just cargo cult something when I contribute to phobos/druntime. 
One cannot know everything.

Also, ddoc always appeared to me like a big NIH syndrome.
Dec 15 2015
next sibling parent reply ZombineDev <valid_email he.re> writes:
On Wednesday, 16 December 2015 at 02:01:02 UTC, deadalnix wrote:

 On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei 
 Alexandrescu wrote:

 It seems knowing ddoc is part of knowing D. -- Andrei


 I just cargo cult something when I contribute to 
 phobos/druntime. One cannot know everything.

 Also, ddoc always appeared to me like a big NIH syndrome.


Well DDoc may have it's disadvantages, but I'm certain that the 
documentation would have been far worse if it wasn't for it.

What I like about it:
+ Good defaults for sections
+ Params section is checked at compile-time and has nice syntax
+ Everything that is not builtin can be implemented as a macro.
+ Recently added feature that allows you to wrap code with ` ` 
like in markdown

What I don't like about it:
+ It relies too much on macros for some of the stuff that could 
have been builtin
+ This makes reading the docs in the source code of some phobos 
function harder, because you need to mentally expand the macros
+ The macro syntax probably should have been something like 
${MACRO ...} because ( and ) are more often used symbols and 
syntax should be optimized for them (so you don't have to escape 
them).

In general I prefer markdown's syntax for things like lists, 
links, tables, bold and italic text, because it is more easily 
readable and writable by humans.
Dec 16 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 12:21 AM, ZombineDev wrote:

 Well DDoc may have it's disadvantages, but I'm certain that the documentation
 would have been far worse if it wasn't for it.


No need to speculate :-) Before Ddoc, the Phobos documentation was horrific, 
probably the worst I'd ever seen. It was so bad it was unusual for there to be 
any correct documentation for a particular function, or even anything at all.

Ddoc utterly transformed that, almost overnight. It's hard to underestimate the 
positive impact Ddoc has had on D documentation.
Dec 16 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 01:00:19PM -0800, Walter Bright via Digitalmars-d wrote:

 On 12/16/2015 12:21 AM, ZombineDev wrote:

Well DDoc may have it's disadvantages, but I'm certain that the
documentation would have been far worse if it wasn't for it.


 
 No need to speculate :-) Before Ddoc, the Phobos documentation was
 horrific, probably the worst I'd ever seen. It was so bad it was
 unusual for there to be any correct documentation for a particular
 function, or even anything at all.
 
 Ddoc utterly transformed that, almost overnight. It's hard to
 underestimate the positive impact Ddoc has had on D documentation.


I don't think anybody is questioning the value of ddoc as a
*documentation generator*. The issue here is whether it has the same
value as a *website programming language*. Very different things.


T

-- 
"640K ought to be enough" -- Bill G. (allegedly), 1984. "The Internet is not a
primary goal for PC usage" -- Bill G., 1995. "Linux has no impact on
Microsoft's strategy" -- Bill G., 1999.
Dec 16 2015
parent JohnCK <johnck gmail.com> writes:
On Wednesday, 16 December 2015 at 21:30:32 UTC, H. S. Teoh wrote:

 I don't think anybody is questioning the value of ddoc as a 
 *documentation generator*. The issue here is whether it has the 
 same value as a *website programming language*. Very different 
 things.


That I agree!

JohnCK.
Dec 16 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/15/15 9:01 PM, deadalnix wrote:

 On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Alexandrescu wrote:

 It seems knowing ddoc is part of knowing D. -- Andrei


 I just cargo cult something when I contribute to phobos/druntime. One
 cannot know everything.


Very reasonable, thanks. But that comes with an implied non-nagging 
agreement :o).


 Also, ddoc always appeared to me like a big NIH syndrome.


What would you have done instead?


Andrei
Dec 16 2015
next sibling parent reply Pradeep Gowda <pradeep btbytes.com> writes:
On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei 
Alexandrescu wrote:

 On 12/15/15 9:01 PM, deadalnix wrote:

 On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Also, 
 ddoc always appeared to me like a big NIH syndrome.


 What would you have done instead?


While I like ddoc for inlined documentation, I believe that using 
a easy to learn, and well supported (in IDEs, editors, github, 
familiar to programmers coming from any other language 
background) format like Markdown is the way to go.

I'm very partial to using pandoc (http://pandoc.org/) as a 
universal processor for converting markdown to various output 
formats. Rust used pandoc as their processor till they wrote 
their own toolchain. (writing markdown parsers appears to be 
right of passage to some...).

Of course, there are multiple implementations of what "markdown", 
but http://commonmark.org/ is a step in the right direction 
(created by the author of Pandoc, with others).
Dec 16 2015
next sibling parent Rikki Cattermole <alphaglosined gmail.com> writes:
On 17/12/15 3:23 AM, Pradeep Gowda wrote:
snip

 I'm very partial to using pandoc (http://pandoc.org/) as a universal
 processor for converting markdown to various output formats. Rust used
 pandoc as their processor till they wrote their own toolchain. (writing
 markdown parsers appears to be right of passage to some...).


I've considered writing a markdown parser for D.
Compliant with leanpub's Markua flavour.

Unfortunately without a good PDF library, its just not worth it for me.
Dec 16 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 09:23 AM, Pradeep Gowda wrote:

 On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:

 On 12/15/15 9:01 PM, deadalnix wrote:

 On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Also, ddoc
 always appeared to me like a big NIH syndrome.


 What would you have done instead?


 While I like ddoc for inlined documentation, I believe that using a easy
 to learn, and well supported (in IDEs, editors, github, familiar to
 programmers coming from any other language background) format like
 Markdown is the way to go.

 I'm very partial to using pandoc (http://pandoc.org/) as a universal
 processor for converting markdown to various output formats. Rust used
 pandoc as their processor till they wrote their own toolchain. (writing
 markdown parsers appears to be right of passage to some...).

 Of course, there are multiple implementations of what "markdown", but
 http://commonmark.org/ is a step in the right direction (created by the
 author of Pandoc, with others).


I think Markdown postdates 2001. So at this point, would it be worth it 
switching over to Markdown? -- Andrei
Dec 16 2015
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 16 December 2015 at 14:42:08 UTC, Andrei 
Alexandrescu wrote:

 I think Markdown postdates 2001. So at this point, would it be 
 worth it switching over to Markdown? -- Andrei


I think this thread has gotten sidetracked: the question about 
the web site and the question of ddoc are separate things.

Regular ddoc's strength is its integration with D source files. 
But the web pages aren't D source files. They are stand-alone 
files that just happen to use ddoc. They could be changed to use 
something else very easily without changing ddoc at all.


On the topic of ddoc though, my worries with it aren't syntax 
related. I'm reasonably happy with the syntax right now. 
Cross-referencing, automatic linking, and tables of contents are 
the missing features if you ask me... and the major bug is that 
it honors conditional compilation, so building the docs on a 
Linux box can result in the Windows functions being left out of 
the generated page, and vice versa!

And you know, there, I think we are still better off enhancing 
what we have than throwing it out. Cross referencing for example, 
in the compiler, means it can automatically emit some kind of 
link with the full name of the symbol done with scope resolution.




So I ask everyone to please remember that we can change website 
.dd files to .whatever files without changing ddoc and let's not 
forget ddoc's already existing strengths and weaknesses when 
talking about changing it.
Dec 16 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 10:13 AM, Adam D. Ruppe wrote:

 And you know, there, I think we are still better off enhancing what we
 have than throwing it out. Cross referencing for example, in the
 compiler, means it can automatically emit some kind of link with the
 full name of the symbol done with scope resolution.


I have a pretty cool idea on how to do cross referencing and other 
global things simply.

All we need is that ddoc generates plaintext wrapped in a macro. For 
example, consider the input:

====
This is a $(D ddoc) sentence with a lil $(B bold) in the mix.
====

Right now the generated output consists of the raw text interspersed 
with the expansion of the macros. What we need is this:

====
$(DDOC_RAWTEXT This is a )$(D ddoc)$(DDOC_RAWTEXT  sentence with a lil 
)$(B bold)$(DDOC_RAWTEXT  in the mix.)
====

Expansion would proceed normally. The default value is:

DDOC_RAWTEXT=$0

With this change to ddoc it becomes easy to define filters that 
eliminate all text and tags except those of interest. For example, 
generating a list of all URLs for verification purposes is trivial. 
Cross-referencing, glossary, etc. etc. become easy to automated.

Another cool project!


Andrei
Dec 16 2015
prev sibling parent reply Jack Stouffer <jack jackstouffer.com> writes:
On Wednesday, 16 December 2015 at 14:42:08 UTC, Andrei 
Alexandrescu wrote:

 I think Markdown postdates 2001. So at this point, would it be 
 worth it switching over to Markdown? -- Andrei


Honestly, no. For three reasons

1. DDoc isn't hard. It took me all of ten minutes to understand 
it and make my first contribution to the website

2. Markdown is good for creating *simple* content. Once you need 
anything custom you start adding in your own things and you're 
right back where you started. This would become a problem with 
all of the extra macros that we have in the website (e.g. 
$(NOT_EBOOK)) which are needed in some pages. How would one 
represent $(NOT_EBOOK) in Markdown?

3. "Who wants to spend hours and hours of work writing a DDoc to 
Markdown converter or manually convert all existing pages? Do we 
have any volunteers?"
Dec 16 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 7:32 AM, Jack Stouffer wrote:

 3. "Who wants to spend hours and hours of work writing a DDoc to Markdown
 converter or manually convert all existing pages? Do we have any volunteers?"


I can't even get consistent documentation of the parameters to a function:

For example:



What are 'fun' and 'Args' supposed to be? No example(s).

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

Not a single appearance of 'Params:' or 'Returns:. Inconsistent use of 
'Example:' and 'Examples:'. Many missing examples. Etc.

There's plenty to be done to improve things that converting all the pages to 
another format will not help with.
Dec 16 2015
parent reply Meta <jared771 gmail.com> writes:
On Wednesday, 16 December 2015 at 21:57:05 UTC, Walter Bright 
wrote:

 On 12/16/2015 7:32 AM, Jack Stouffer wrote:

 3. "Who wants to spend hours and hours of work writing a DDoc 
 to Markdown
 converter or manually convert all existing pages? Do we have 
 any volunteers?"


 I can't even get consistent documentation of the parameters to 
 a function:

 For example:



 What are 'fun' and 'Args' supposed to be? No example(s).

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

 Not a single appearance of 'Params:' or 'Returns:. Inconsistent 
 use of 'Example:' and 'Examples:'. Many missing examples. Etc.

 There's plenty to be done to improve things that converting all 
 the pages to another format will not help with.


There's also weird stuff like this, with an outer template and a 
documented inner template function.
Dec 16 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 10:00:50PM +0000, Meta via Digitalmars-d wrote:

 On Wednesday, 16 December 2015 at 21:57:05 UTC, Walter Bright wrote:


[...]

There's plenty to be done to improve things that converting all the
pages to another format will not help with.




While I'm on the fence about the value of ddoc as a website programming
language (not as a documentation generator, where it is excellent IMO),
I'm doubtful of the value of converting wholesale to a different format
at this present time.  That's a lot of effort and drain of our scant
resources, with only unverifiable claims of increased participation from
nebulous crowds who so far haven't showed any signs of interest in
participating yet.  It's something we could perhaps consider in the long
term, but right now there are far more important things we need to work
on. Like actually improving what docs are currently there.



 There's also weird stuff like this, with an outer template and a
 documented inner template function.
 



This is a limitation of ddoc that needs to be fixed.  Historically,
template functions used to be written like this:

	template amap(Args...)
	{
		auto amap(Args args) {
			implementation();
		}
	}

Then a shorthand was introduced (the so-called "eponymous template"
syntax), such that the above incantation could be abbreviated to:

	auto amap(Args...)(Args args) {
		implementation();
	}

It would appear that ddoc came after eponymous templates became the
norm, so currently, ddoc only understands ddoc comments attached to the
latter syntax, while it fails to recognize that the former syntax is
actually equivalent.  Several other functions in Phobos suffer from the
resulting formatting disparity, IIRC map(), and maybe reduce(), and one
or two others. It's rare enough that we don't encounter it very often,
but the functions affected happen to be ones that are likely to be
frequently used, so we really ought to fix this limitation in ddoc.


T

-- 
Valentine's Day: an occasion for florists to reach into the wallets of nominal
lovers in dire need of being reminded to profess their hypothetical love for
their long-forgotten.
Dec 16 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 2:32 PM, H. S. Teoh via Digitalmars-d wrote:

 I'm doubtful of the value of converting wholesale to a different format
 at this present time.  That's a lot of effort and drain of our scant
 resources, with only unverifiable claims of increased participation from
 nebulous crowds who so far haven't showed any signs of interest in
 participating yet.


Exactly.

We'll never get anywhere chasing people who say "I'll help only if you convert 
to my way of doing things." I've done enough of that in the past, and concluded 
they're just seeing how long you'll dance to their tune and have no real 
intention of ever helping - there will just be another excuse.
Dec 16 2015
next sibling parent reply BLM768 <blm768 gmail.com> writes:
On Wednesday, 16 December 2015 at 23:01:47 UTC, Walter Bright 
wrote:

 Exactly.

 We'll never get anywhere chasing people who say "I'll help only 
 if you convert to my way of doing things." I've done enough of 
 that in the past, and concluded they're just seeing how long 
 you'll dance to their tune and have no real intention of ever 
 helping - there will just be another excuse.


It's funny how much "better" one's own ideas seem until one 
realizes that implementing them usually takes just as much effort 
as with someone else's idea, and work is almost always the 
limiting factor.

On the subject of "one's own ideas", here's mine, FWIW:

First, my background thoughts. We seem to have four main 
"sections" of the site: the forums (built on DFeed), the wiki 
(built on MediaWiki), the language docs (DDoc), and the "main" 
site (in DDoc/HTML). The first three are using technologies which 
were explicitly designed for what they do, and they work quite 
nicely. The only thing left is the "main" site (the download 
page, articles, etc.), which doesn't fit into the models of the 
first two technologies and is somewhat clumsy for some people to 
edit because it's built on more than just "common" Web standards.

I can think of a couple of ideas for making the main page more 
palatable to Web developers. One is to make as much of it as 
possible in plain old static HTML. Stuff like the articles rarely 
changes, after all. Another idea is to use a Web application 
framework. There's a significant advantage there: we can have one 
master "layout" template, and almost any content we want (forums, 
DDoc-generated HTML, static HTML, and so on) can be rendered in 
that template with relatively minimal code. There are lots of 
frameworks that shouldn't be hard to use. I'm sure that someone 
has already suggested doing it in vibe.d, and that probably got 
shot down due to a technical issue or something, but it would be 
interesting from a PR standpoint.
Dec 16 2015
next sibling parent reply BLM768 <blm768 gmail.com> writes:
On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote:

 [snip]


...and as I read some older posts, I see that mine is completely 
redundant. ;)

Seriously, though, I'm willing to help prototype something. I've 
got time before the next semester starts.
Dec 16 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/15 6:47 PM, BLM768 wrote:

 On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote:

 [snip]


 ...and as I read some older posts, I see that mine is completely
 redundant. ;)

 Seriously, though, I'm willing to help prototype something. I've got
 time before the next semester starts.


If you have some time and motivation to improve the documentation, 
there's tremendous opportunity for impact. So much low-hanging fruit, 
all well before we explore switching to a different way of building the 
site. And whatever improvements you make won't compete with future 
changes. There's so much opportunity there it hurts. -- Andrei
Dec 17 2015
next sibling parent reply deadalnix <deadalnix gmail.com> writes:
On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei 
Alexandrescu wrote:

 On 12/16/15 6:47 PM, BLM768 wrote:

 On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote:

 [snip]


 ...and as I read some older posts, I see that mine is 
 completely
 redundant. ;)

 Seriously, though, I'm willing to help prototype something. 
 I've got
 time before the next semester starts.


 If you have some time and motivation to improve the 
 documentation, there's tremendous opportunity for impact. So 
 much low-hanging fruit, all well before we explore switching to 
 a different way of building the site. And whatever improvements 
 you make won't compete with future changes. There's so much 
 opportunity there it hurts. -- Andrei


Yes, I'm kind of disappointed I brought up ddoc in there, because 
everything has been ignored now, while in there, there are many 
thing more important than using ddoc or not.

And I'd say there is also way more impact changes to do than 
cleaning the doc as you mention. Searching the doc is late in the 
tunnel. Clearing the home page has much higher impact options.

But, to start, let's take action. Andrei, does dlang.org has any 
kind of analytic setup ? If not, would you mind setting up 
something as google analytic ? That should give us data on what 
changes are impactful.
Dec 17 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/17/15 4:17 PM, deadalnix wrote:

 But, to start, let's take action. Andrei, does dlang.org has any kind of
 analytic setup ?


We use webalizer. -- Andrei
Dec 17 2015
parent reply deadalnix <deadalnix gmail.com> writes:
On Thursday, 17 December 2015 at 22:28:25 UTC, Andrei 
Alexandrescu wrote:

 On 12/17/15 4:17 PM, deadalnix wrote:

 But, to start, let's take action. Andrei, does dlang.org has 
 any kind of
 analytic setup ?


 We use webalizer. -- Andrei


I would suggest using something more powerful. Log analysis is 
one thing, but modern tools can do more.

If you are not comfortable with sending data to google, I suggest 
using piwik : https://piwik.org/ . Some more setup, but you are 
100% in control of the data.
Dec 17 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/17/15 5:32 PM, deadalnix wrote:

 On Thursday, 17 December 2015 at 22:28:25 UTC, Andrei Alexandrescu wrote:

 On 12/17/15 4:17 PM, deadalnix wrote:

 But, to start, let's take action. Andrei, does dlang.org has any kind of
 analytic setup ?


 We use webalizer. -- Andrei


 I would suggest using something more powerful. Log analysis is one
 thing, but modern tools can do more.

 If you are not comfortable with sending data to google, I suggest using
 piwik : https://piwik.org/ . Some more setup, but you are 100% in
 control of the data.


I've used piwik, too. I think we're in good shape with analytics. 
Exploring alternative analytics engines would be a distraction. I just 
looked over the analytics and what we need now is good content and 
beautiful css. -- Andrei
Dec 17 2015
prev sibling parent reply BLM768 <blm768 gmail.com> writes:
On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei 
Alexandrescu wrote:

 If you have some time and motivation to improve the 
 documentation, there's tremendous opportunity for impact. So 
 much low-hanging fruit, all well before we explore switching to 
 a different way of building the site. And whatever improvements 
 you make won't compete with future changes. There's so much 
 opportunity there it hurts. -- Andrei


As long as the main page still works, then yeah, that's first 
priority.

Is there a particular spot that stands out as needing the most 
improvement? I'm no Phobos expert, but I can at least fill any 
glaring holes.
Dec 17 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/17/2015 06:33 PM, BLM768 wrote:

 On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei Alexandrescu wrote:

 If you have some time and motivation to improve the documentation,
 there's tremendous opportunity for impact. So much low-hanging fruit,
 all well before we explore switching to a different way of building
 the site. And whatever improvements you make won't compete with future
 changes. There's so much opportunity there it hurts. -- Andrei


 As long as the main page still works, then yeah, that's first priority.

 Is there a particular spot that stands out as needing the most
 improvement? I'm no Phobos expert, but I can at least fill any glaring
 holes.


There's a bunch to do.

* Many functions don't have "Parameters:", "Returns:", or "Throws:" 
sections. Those that respectively take parameters, return non-void, or 
throw, should have one each.

* All functions should have an example.

* "Examples:" is a historical error. All instances should be "Example:". 
Just one diff making that change throughout would be a meaningful 
contribution.

* Overloaded functions should be collected together, connected with "/// 
ditto".

* Examples on the site and on the library pages should be editable and 
runnable just like the one on the homepage.

* Eliminating those redundant macros that everybody's talking about.


Andrei
Dec 17 2015
next sibling parent BLM768 <blm768 gmail.com> writes:
On Thursday, 17 December 2015 at 23:50:34 UTC, Andrei 
Alexandrescu wrote:

 * "Examples:" is a historical error. All instances should be 
 "Example:". Just one diff making that change throughout would 
 be a meaningful contribution.


Like so?

https://github.com/blm768/phobos/commit/5f08c058abd2bafe91056d5223d45ed5c07a748c

Sed for the win! (With manual review of the changes, of course.)

I'll open a pull request in a moment.
Dec 17 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-18 00:50, Andrei Alexandrescu wrote:


 * Many functions don't have "Parameters:", "Returns:", or "Throws:"
 sections. Those that respectively take parameters, return non-void, or
 throw, should have one each.


I think we need to be better at enforcing this in the pull requests. I 
see a lot of this [2] in PR's.


 * All functions should have an example.

 * "Examples:" is a historical error. All instances should be "Example:".
 Just one diff making that change throughout would be a meaningful
 contribution.


The documentation for Ddco mentions "Examples:" [1]. Does it have a 
special meaning or is it just a convention?

[1] http://dlang.org/spec/ddoc.html
[2] 
https://github.com/D-Programming-Language/phobos/pull/3855#discussion_r46769338

-- 
/Jacob Carlborg
Dec 17 2015
parent reply Jakob Ovrum <jakobovrum gmail.com> writes:
On Friday, 18 December 2015 at 07:37:40 UTC, Jacob Carlborg wrote:

 On 2015-12-18 00:50, Andrei Alexandrescu wrote:


 * Many functions don't have "Parameters:", "Returns:", or 
 "Throws:"
 sections. Those that respectively take parameters, return 
 non-void, or
 throw, should have one each.


 I think we need to be better at enforcing this in the pull 
 requests. I see a lot of this [2] in PR's.


After further changes I was able to add `Params:` and `Returns:` 
with some valuable information, but it also comes with a fair 
amount of redundancy. I think a lot of our current functions have 
more than adequately documented parameters and return values, 
just without using sections. Some redundancy can be a good thing, 
but for most of those functions I don't see how simple-mindedly 
adding purely redundant information is impactful.

The important thing is not those sections but that parameters and 
return values are documented.
Dec 18 2015
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-12-19 06:01, Jakob Ovrum wrote:


 After further changes I was able to add `Params:` and `Returns:` with
 some valuable information, but it also comes with a fair amount of
 redundancy.


Ok, cool. I missed that.

-- 
/Jacob Carlborg
Dec 19 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/19/15 12:01 AM, Jakob Ovrum wrote:

 After further changes I was able to add `Params:` and `Returns:` with
 some valuable information, but it also comes with a fair amount of
 redundancy. I think a lot of our current functions have more than
 adequately documented parameters and return values, just without using
 sections. Some redundancy can be a good thing, but for most of those
 functions I don't see how simple-mindedly adding purely redundant
 information is impactful.

 The important thing is not those sections but that parameters and return
 values are documented.


Agreed there's got to be measure in everything. I'm thinking in those 
cases the existing documentation should be reformatted with the standard 
sections.

When you do standard-formatted documentation for many functions at once, 
it seems kinda trite. But for folks who work on some program and want to 
look up one function, reliance on a standard uniform format is very 
helpful.


Andrei
Dec 19 2015
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Sat, Dec 19, 2015 at 09:58:44AM -0500, Andrei Alexandrescu via Digitalmars-d
wrote:

 On 12/19/15 12:01 AM, Jakob Ovrum wrote:

After further changes I was able to add `Params:` and `Returns:` with
some valuable information, but it also comes with a fair amount of
redundancy. I think a lot of our current functions have more than
adequately documented parameters and return values, just without
using sections. Some redundancy can be a good thing, but for most of
those functions I don't see how simple-mindedly adding purely
redundant information is impactful.

The important thing is not those sections but that parameters and
return values are documented.


 
 Agreed there's got to be measure in everything. I'm thinking in those
 cases the existing documentation should be reformatted with the
 standard sections.
 
 When you do standard-formatted documentation for many functions at
 once, it seems kinda trite. But for folks who work on some program and
 want to look up one function, reliance on a standard uniform format is
 very helpful.


[...]

Yes, Walter has said the same thing before. Where the description is too
short to warrant being in both a standard section and in prose, put it
in the standard section. I'd even propose that it's OK to leave the
function description blank if the info in the standard Params: and
Returns: sections already fully define what it does.  This isn't as
literary, but we're writing reference documentation, not an essay
contest, and consistently having information in standard sections makes
it more useful as a reference.


T

-- 
"Hi." "'Lo."
Dec 19 2015
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Dec 17, 2015 at 06:50:34PM -0500, Andrei Alexandrescu via Digitalmars-d
wrote:
[...]

 * "Examples:" is a historical error. All instances should be "Example:".
 Just one diff making that change throughout would be a meaningful
 contribution.


[...]

I'm pretty sure ddoc'd unittests show up as "Examples:". Or was this
changed recently?


T

-- 
Give a man a fish, and he eats once. Teach a man to fish, and he will sit
forever.
Dec 18 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/18/2015 10:19 AM, H. S. Teoh via Digitalmars-d wrote:

 On Thu, Dec 17, 2015 at 06:50:34PM -0500, Andrei Alexandrescu via
Digitalmars-d wrote:
 [...]

 * "Examples:" is a historical error. All instances should be "Example:".
 Just one diff making that change throughout would be a meaningful
 contribution.


 [...]

 I'm pretty sure ddoc'd unittests show up as "Examples:". Or was this
 changed recently?


It should get changed to singular because it's grammatically incorrect. 
Most examples shown feature exactly one instance of using the 
demonstrated artifact. So it's incorrect to write "Examples:" followed 
by one example.

Conversely, if there are multiple uses of the discussed artifact, then 
"Example:" is not incorrect - it's one example featuring several uses.


Andrei
Dec 18 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 06:43 PM, BLM768 wrote:

 One is to make as much of it as possible in plain old static HTML. Stuff
 like the articles rarely changes, after all.


But I dislike typing HTML. DDoc improves on that significantly.


 Another idea is to use a
 Web application framework. There's a significant advantage there: we can
 have one master "layout" template, and almost any content we want
 (forums, DDoc-generated HTML, static HTML, and so on) can be rendered in
 that template with relatively minimal code.


Ironically Ddoc does exactly that, and quite nicely.


Andrei
Dec 16 2015
next sibling parent BLM768 <blm768 gmail.com> writes:
On Wednesday, 16 December 2015 at 23:49:52 UTC, Andrei 
Alexandrescu wrote:

 But I dislike typing HTML. DDoc improves on that significantly.


Fair enough. Vibe.d has diet templates, though. They're pretty 
nice.

As long as the pages are mainly static anyway, though, it's all 
plain boring HTML to the client no matter what's used on the back 
end.


 Ironically Ddoc does exactly that, and quite nicely.


I thought about that, too. It's great for static content, but 
doesn't dynamic content become kind of tricky? Given that the 
forum sidebar operates differently from the main page sidebar 
(most noticeably in the giant image link at the top), I'd guess 
that it's not using the same DDoc template. (I haven't looked at 
the source, though.) Of course, it would need custom template 
code for the forum menu, so there's really not much to share with 
the main site...
Dec 16 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 3:49 PM, Andrei Alexandrescu wrote:

 On 12/16/2015 06:43 PM, BLM768 wrote:

 Another idea is to use a
 Web application framework. There's a significant advantage there: we can
 have one master "layout" template, and almost any content we want
 (forums, DDoc-generated HTML, static HTML, and so on) can be rendered in
 that template with relatively minimal code.


 Ironically Ddoc does exactly that, and quite nicely.


It also takes a bit of using it to realize that.
Dec 16 2015
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 3:43 PM, BLM768 wrote:

 One is to make as much of it as possible in plain old static HTML.


I've done that before, a lot. Ddoc cut the work involved in that in half, and I 
mean in half. It also made it easy to change the look of a whole site, rather 
than being a mess of tedium.

No way I'm going back to that.
Dec 16 2015
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright 
wrote:

 I've done that before, a lot. Ddoc cut the work involved in 
 that in half, and I mean in half.


So does a simple `cat head.html body.html foot.html > 
output.html` loop. There's plenty of ways to achieve this.
Dec 16 2015
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 4:04 PM, Adam D. Ruppe wrote:

 On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright wrote:

 I've done that before, a lot. Ddoc cut the work involved in that in half, and
 I mean in half.


 So does a simple `cat head.html body.html foot.html > output.html` loop.
There's
 plenty of ways to achieve this.



Give me some credit, Adam :-)
Dec 16 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 07:04 PM, Adam D. Ruppe wrote:

 On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright wrote:

 I've done that before, a lot. Ddoc cut the work involved in that in
 half, and I mean in half.


 So does a simple `cat head.html body.html foot.html > output.html` loop.
 There's plenty of ways to achieve this.


Hmmmmmmmm... that's not so simple. -- Andrei
Dec 16 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 02:21:03 UTC, Andrei 
Alexandrescu wrote:

 Hmmmmmmmm... that's not so simple. -- Andrei


Well, it would complicate a bit as you add more to it (like 
changing the title on other pages...) but not a whole lot.

It is certainly simpler than the current dlang.org build process! 
There's over 1,000 lines of makefile for it.


Though, I actually run some kind of processor over my generated 
ddoc most the time anyway, and now I am really tempted to just go 
ahead and ditch the ddoc part since it doesn't add *that* much. 
At least for standalone pages.
Dec 16 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 6:34 PM, Adam D. Ruppe wrote:

 Well, it would complicate a bit as you add more to it (like changing the title
 on other pages...) but not a whole lot.


You don't use it like I do. I use it to do abstractions, like sections, lists, 
etc., and then just change the markup to completely change the html generated.
Dec 16 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 00:55, Walter Bright wrote:


 I've done that before, a lot. Ddoc cut the work involved in that in
 half, and I mean in half. It also made it easy to change the look of a
 whole site, rather than being a mess of tedium.

 No way I'm going back to that.


No sane person would use raw HTML. I hope no one takes that suggestion 
serious.

-- 
/Jacob Carlborg
Dec 16 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 07:53:02 UTC, Jacob Carlborg 
wrote:

 No sane person would use raw HTML. I hope no one takes that 
 suggestion serious.


HTML + a couple simple helper tools is a different story though. 
That's basically what ddoc is anyway, but it has the weird 
behavior of just thinly wrapping html in macros.... $(DIVID $(B 
$(LINK2 seriously wtf))

In IRC I mentioned XSLT as a bit of a joke, but it solves the 
problem of reusing skeleton layouts too.

There's LOTS of ways to do this, and the language in which the 
doc pages are written is different than the framework which 
brings them all together and does other post processing.
Dec 17 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 00:43, BLM768 wrote:


 On the subject of "one's own ideas", here's mine, FWIW:

 First, my background thoughts. We seem to have four main "sections" of
 the site: the forums (built on DFeed), the wiki (built on MediaWiki),
 the language docs (DDoc), and the "main" site (in DDoc/HTML). The first
 three are using technologies which were explicitly designed for what
 they do, and they work quite nicely. The only thing left is the "main"
 site (the download page, articles, etc.), which doesn't fit into the
 models of the first two technologies and is somewhat clumsy for some
 people to edit because it's built on more than just "common" Web standards.


Exactly, this is spot on.


 I can think of a couple of ideas for making the main page more palatable
 to Web developers. One is to make as much of it as possible in plain old
 static HTML. Stuff like the articles rarely changes, after all.


This is an horrible idea. No sane person would use raw HTML. The only 
advantage is that it's HTML so there's documentation available.


 Another idea is to use a Web application framework. There's a significant
 advantage there: we can have one master "layout" template, and almost
 any content we want (forums, DDoc-generated HTML, static HTML, and so
 on) can be rendered in that template with relatively minimal code. There
 are lots of frameworks that shouldn't be hard to use. I'm sure that
 someone has already suggested doing it in vibe.d, and that probably got
 shot down due to a technical issue or something, but it would be
 interesting from a PR standpoint.


That's exactly what we should do. Ddoc already can do some of this, just 
not in a good way.

-- 
/Jacob Carlborg
Dec 16 2015
parent BLM768 <blm768 gmail.com> writes:
On Thursday, 17 December 2015 at 07:51:42 UTC, Jacob Carlborg 
wrote:

 On 2015-12-17 00:43, BLM768 wrote:

 One is to make as much of it as possible in plain old
 static HTML. Stuff like the articles rarely changes, after all.


 This is an horrible idea. No sane person would use raw HTML. 
 The only advantage is that it's HTML so there's documentation 
 available.


Yeah. I didn't think that one through.

The idea I had in my head was to build a template in (mostly) raw 
HTML, write each article as an HTML snippet, and use either a 
framework or a build script to paste them together, so it's not 
_completely_ raw, just enough so you actually see the HTML. The 
main thing was to move away from building all the tags with 
macros.

But yeah, I didn't express that clearly enough (or think through 
it properly).
Dec 17 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 00:01, Walter Bright wrote:


 Exactly.

 We'll never get anywhere chasing people who say "I'll help only if you
 convert to my way of doing things." I've done enough of that in the
 past, and concluded they're just seeing how long you'll dance to their
 tune and have no real intention of ever helping - there will just be
 another excuse.


I already help, and I use Ddoc, that's how I know it's crap ;). I wrote 
the documentation for interfacing with Objective-C [1]. It was very 
frustrating, especially since the PDF generator broke because latex 
can't handle underscores as in "D_ObjectiveC". I did get some help in 
the pull request but not from someone that knew how this actually 
worked. It was most guesses.

If a more widely tool had been used I might have been able to find out 
how this actually works and fixed it. Instead I had to revert to use a 
hack like wrapping the text in the $(D_CODE) macro.

Of course, you will always have the issues you mention above. But if you 
choose a tool that is created for web design and is widely used you will 
most likely have less of these issues. Most importantly, when something 
doesn't work there's documentation online to get help from.

[1] http://dlang.org/spec/objc_interface.html

-- 
/Jacob Carlborg
Dec 16 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 11:49 PM, Jacob Carlborg wrote:

 I already help, and I use Ddoc, that's how I know it's crap ;).


You're not one of the people I was referring to, since you do help.


 I wrote the
 documentation for interfacing with Objective-C [1]. It was very frustrating,
 especially since the PDF generator broke because latex can't handle underscores
 as in "D_ObjectiveC". I did get some help in the pull request but not from
 someone that knew how this actually worked. It was most guesses.

 If a more widely tool had been used I might have been able to find out how this
 actually works and fixed it. Instead I had to revert to use a hack like
wrapping
 the text in the $(D_CODE) macro.


Your issue with Ddoc is that the latex pdf generator you used was broken? Latex 
meets your critera as being very widely used. Use another pdf generator. Nobody 
has chained you to Latex.



 Of course, you will always have the issues you mention above. But if you choose
 a tool that is created for web design and is widely used you will most likely
 have less of these issues. Most importantly, when something doesn't work
there's
 documentation online to get help from.


Amazon broke the PDF reader in their latest Kindle. I filed a bug report, but 
there's nothing I can do about it, and Amazon hasn't/won't fix it. They've sold 
millions of the things.

Jacob, I've adapted several books for Ddoc on their way to being Kindle ebooks. 
Ddoc works fine for the formatting. The WORK is simply not the formatting, it's 
the text creation/editting. If you're spending the bulk of your time fiddling 
with Ddoc rather than text creation, I suspect you've gone off the rails
somewhere.
Dec 17 2015
parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 12:45, Walter Bright wrote:


 You're not one of the people I was referring to, since you do help.


So do it for those who do help and not for those how don't ;)


 Your issue with Ddoc is that the latex pdf generator you used was
 broken? Latex meets your critera as being very widely used. Use another
 pdf generator. Nobody has chained you to Latex.


I could care less about generating a PDF. But apparently someone cared 
and added it to the process of building dlang.org. So if you're willing 
to remove that or replace Latex with something else, please go ahead.


 Jacob, I've adapted several books for Ddoc on their way to being Kindle
 ebooks. Ddoc works fine for the formatting. The WORK is simply not the
 formatting, it's the text creation/editting. If you're spending the bulk
 of your time fiddling with Ddoc rather than text creation, I suspect
 you've gone off the rails somewhere.


Well, see for yourself [1]. None of the comments are related to the 
content. The content is the easy part.

[1] https://github.com/D-Programming-Language/dlang.org/pull/1039

-- 
/Jacob Carlborg
Dec 17 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/17/2015 11:47 PM, Jacob Carlborg wrote:

 Well, see for yourself [1]. None of the comments are related to the content.
The
 content is the easy part.

 [1] https://github.com/D-Programming-Language/dlang.org/pull/1039


I did have a look. Most of the PR is code and content, not markup. And most of 
the markup that is there is straightforward, like marking pages with $(P ... ).

I've written quite a bit of the dlang site.
Dec 18 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-12-18 12:07, Walter Bright wrote:


 I did have a look. Most of the PR is code and content, not markup. And
 most of the markup that is there is straightforward, like marking pages
 with $(P ... ).


I'm talking about the comments in the PR, not the contents of the PR. It 
shows that the problems I had was with Ddoc and styling, not the content.

-- 
/Jacob Carlborg
Dec 19 2015
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 05:32 PM, H. S. Teoh via Digitalmars-d wrote:

 While I'm on the fence about the value of ddoc as a website programming
 language (not as a documentation generator, where it is excellent IMO),
 I'm doubtful of the value of converting wholesale to a different format
 at this present time.  That's a lot of effort and drain of our scant
 resources, with only unverifiable claims of increased participation from
 nebulous crowds who so far haven't showed any signs of interest in
 participating yet.  It's something we could perhaps consider in the long
 term, but right now there are far more important things we need to work
 on. Like actually improving what docs are currently there.


Very very very wise words. Thanks! -- Andrei
Dec 16 2015
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-12-16 23:32, H. S. Teoh via Digitalmars-d wrote:


 This is a limitation of ddoc that needs to be fixed.  Historically,
 template functions used to be written like this:

 	template amap(Args...)
 	{
 		auto amap(Args args) {
 			implementation();
 		}
 	}

 Then a shorthand was introduced (the so-called "eponymous template"
 syntax), such that the above incantation could be abbreviated to:

 	auto amap(Args...)(Args args) {
 		implementation();
 	}

 It would appear that ddoc came after eponymous templates became the
 norm, so currently, ddoc only understands ddoc comments attached to the
 latter syntax, while it fails to recognize that the former syntax is
 actually equivalent.  Several other functions in Phobos suffer from the
 resulting formatting disparity, IIRC map(), and maybe reduce(), and one
 or two others. It's rare enough that we don't encounter it very often,
 but the functions affected happen to be ones that are likely to be
 frequently used, so we really ought to fix this limitation in ddoc.


How would Ddoc know that you want to document the function and not the 
template? Just assume so if there's only one symbol in the template? It 
still needs to be possible to individually document the template and the 
function, and least when there's more than one symbol in the template.

-- 
/Jacob Carlborg
Dec 17 2015
prev sibling parent Marc =?UTF-8?B?U2Now7x0eg==?= <schuetzm gmx.net> writes:
On Wednesday, 16 December 2015 at 22:32:25 UTC, H. S. Teoh wrote:

 On Wed, Dec 16, 2015 at 10:00:50PM +0000, Meta via 
 Digitalmars-d wrote:

 There's also weird stuff like this, with an outer template and 
 a documented inner template function.
 



 This is a limitation of ddoc that needs to be fixed.  
 Historically, template functions used to be written like this:

 	template amap(Args...)
 	{
 		auto amap(Args args) {
 			implementation();
 		}
 	}

 Then a shorthand was introduced (the so-called "eponymous 
 template" syntax), such that the above incantation could be 
 abbreviated to:

 	auto amap(Args...)(Args args) {
 		implementation();
 	}

 It would appear that ddoc came after eponymous templates became 
 the norm, so currently, ddoc only understands ddoc comments 
 attached to the latter syntax, while it fails to recognize that 
 the former syntax is actually equivalent.  Several other 
 functions in Phobos suffer from the resulting formatting 
 disparity, IIRC map(), and maybe reduce(), and one or two 
 others. It's rare enough that we don't encounter it very often, 
 but the functions affected happen to be ones that are likely to 
 be frequently used, so we really ought to fix this limitation 
 in ddoc.


I think in this particular case it can only be done with a nested 
template, because there are two variadic parameters.
Dec 17 2015
prev sibling parent reply Guillaume Piolat <first.last gmail.com> writes:
On Wednesday, 16 December 2015 at 14:23:54 UTC, Pradeep Gowda 
wrote:

 I'm very partial to using pandoc (http://pandoc.org/) as a 
 universal processor for converting markdown to various output 
 formats. Rust used pandoc as their processor till they wrote 
 their own toolchain. (writing markdown parsers appears to be 
 right of passage to some...).


pandoc comes with an unbelievable amount of dependencies.

Notably the LaTeX dependency: on Mac the LaTeX distribution is a 
whopping 2gb download.

It seems nice in theory, but in practice pandoc takes things like 
\newpage (latex code fragments) in their Markdown input. And 
Markdown already accepts HTML tags! I much prefer DDoc.
Dec 16 2015
parent Pradeep Gowda <pradeep btbytes.com> writes:
On Wednesday, 16 December 2015 at 15:02:24 UTC, Guillaume Piolat 
wrote:

 On Wednesday, 16 December 2015 at 14:23:54 UTC, Pradeep Gowda 
 wrote:
 pandoc comes with an unbelievable amount of dependencies.

 Notably the LaTeX dependency: on Mac the LaTeX distribution is 
 a whopping 2gb download.

 It seems nice in theory, but in practice pandoc takes things 
 like \newpage (latex code fragments) in their Markdown input. 
 And Markdown already accepts HTML tags! I much prefer DDoc.


I use pandoc everyday.

This is provably false. You do not need LaTeX to use pandoc.
On linux and mac it's a self-contained binary. (I don't use 
windows, so i don't know).

This is how i use it everyday:

1. write markdown and convert to docx for sharing with coworkers. 
Not a single line of LaTeX
2. just finished writing a paper in IEEE format using just 
pandoc, which i converted to latex and yet did not have to use a 
single inline latex command in the main document.
2. write my website/notes in markdown and convert to HTML using 
hakyll which uses pandoc as a library. No Latex there either.
Dec 16 2015
prev sibling parent reply deadalnix <deadalnix gmail.com> writes:
On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei 
Alexandrescu wrote:

 Also, ddoc always appeared to me like a big NIH syndrome.


 What would you have done instead?


Honestly for D code itself, ddoc does just fine, but for the 
website, plain html or some known template format like . This is 
what people know.
Dec 16 2015
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 06:47:26PM +0000, deadalnix via Digitalmars-d wrote:

 On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:

Also, ddoc always appeared to me like a big NIH syndrome.


What would you have done instead?


 
 Honestly for D code itself, ddoc does just fine, but for the website,
 plain html or some known template format like . This is what people
 know.


Using ddoc for the website may be NIH, but the ability to easily display
snippets of D code without jumping through hoops is a big plus. Trying
to do syntax-highlighted D code in plain HTML (or any other web
authoring system, for that matter) is an exercise in masochism.

Having said that, though, using ddoc for the website leads to other
problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the
associated relative/absolute URL nightmare that a proper web authoring
system would have taken care of by default).


T

-- 
Жил-был король когда-то, при нём блоха жила.
Dec 16 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 02:12 PM, H. S. Teoh via Digitalmars-d wrote:

   the ongoing fiasco with XREF, LREF, whatever-REF and the
 associated relative/absolute URL nightmare


What's the issue there? -- Andrei
Dec 16 2015
next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 02:33:15PM -0500, Andrei Alexandrescu via Digitalmars-d
wrote:

 On 12/16/2015 02:12 PM, H. S. Teoh via Digitalmars-d wrote:

  the ongoing fiasco with XREF, LREF, whatever-REF and the
associated relative/absolute URL nightmare


 
 What's the issue there? -- Andrei


See:

	https://github.com/D-Programming-Language/phobos/pull/3852
	https://github.com/D-Programming-Language/dlang.org/pull/1082

and their associated bugzilla tickets.


T

-- 
People say I'm arrogant, and I'm proud of it.
Dec 16 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-12-16 20:33, Andrei Alexandrescu wrote:


 What's the issue there? -- Andrei


One problem is that it doesn't work for symbols arbitrary nested 
packages. That is, XREF only forks for "a.b.c" not "a.b.c.d".

-- 
/Jacob Carlborg
Dec 16 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-16 20:12, H. S. Teoh via Digitalmars-d wrote:


 Using ddoc for the website may be NIH, but the ability to easily display
 snippets of D code without jumping through hoops is a big plus. Trying
 to do syntax-highlighted D code in plain HTML (or any other web
 authoring system, for that matter) is an exercise in masochism.


There's DScanner [1].

[1] https://github.com/Hackerpilot/Dscanner/#syntax-highlighting

-- 
/Jacob Carlborg
Dec 16 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 16 December 2015 at 19:44:13 UTC, Jacob Carlborg 
wrote:

 There's DScanner [1].

 [1] https://github.com/Hackerpilot/Dscanner/#syntax-highlighting


Aye, and post-processing html to clean up the edge cases, reuse 
headers, etc. is really easy to do - easier than running 
bleeding-edge dmd over a makefile that requires three repos...
Dec 16 2015
prev sibling next sibling parent carljv <carljv gmail.com> writes:
On Wednesday, 16 December 2015 at 19:12:04 UTC, H. S. Teoh wrote:

 On Wed, Dec 16, 2015 at 06:47:26PM +0000, deadalnix via 
 Digitalmars-d wrote:

 [...]


 Using ddoc for the website may be NIH, but the ability to 
 easily display snippets of D code without jumping through hoops 
 is a big plus. Trying to do syntax-highlighted D code in plain 
 HTML (or any other web authoring system, for that matter) is an 
 exercise in masochism.


Re. syntax highlighting -- it looks like Pygments supports D. 
http://pygments.org/languages/
Dec 16 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote:

 Having said that, though, using ddoc for the website leads to other
 problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the
 associated relative/absolute URL nightmare that a proper web authoring
 system would have taken care of by default).


Annoying, and maybe you have to spend a couple minutes picking the right one if 
you've forgotten for the moment => absolute nightmare? Come on.
Dec 17 2015
parent reply John Colvin <john.loughran.colvin gmail.com> writes:
On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright 
wrote:

 On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote:

 Having said that, though, using ddoc for the website leads to 
 other
 problems (e.g., the ongoing fiasco with XREF, LREF, 
 whatever-REF and the
 associated relative/absolute URL nightmare that a proper web 
 authoring
 system would have taken care of by default).


 Annoying, and maybe you have to spend a couple minutes picking 
 the right one if you've forgotten for the moment => absolute 
 nightmare? Come on.


How does a user who happens to spot a mistake in the docs and 
wants to help work this out?
Dec 17 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/17/2015 5:44 AM, John Colvin wrote:

 On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote:

 On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote:

 Having said that, though, using ddoc for the website leads to other
 problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the
 associated relative/absolute URL nightmare that a proper web authoring
 system would have taken care of by default).


 Annoying, and maybe you have to spend a couple minutes picking the right one
 if you've forgotten for the moment => absolute nightmare? Come on.


 How does a user who happens to spot a mistake in the docs and wants to help
work
 this out?


1. he can file a bugzilla issue

2. he can click on the "Improve this page"

3. to find out what LREF does:

     grep LREF *.ddoc

If what a trivial text macro does is beyond his ken, and/or using grep, I
wonder 
if he should be improving programming documentation at all. I do expect this to 
be part of the baseline knowledge a programmer should have. I wouldn't expect
an 
accountant to know this stuff.
Dec 17 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright 
wrote:

 3. to find out what LREF does:

     grep LREF *.ddoc


So, you're working on Phobos and see a LREF macro.

me arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc
me arsd:~/d/dmd2/src/phobos$

....where is it?

I happen to know it is hidden in the dlang.org repo, but would 
someone who saw a problem in the Phobos docs know that? They seem 
to be generated from the source code.... except when they aren't.

You can't assume everybody knows all the institutional knowledge 
you do!
Dec 17 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/17/2015 11:43 AM, Adam D. Ruppe wrote:

 On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote:

 3. to find out what LREF does:

     grep LREF *.ddoc


 So, you're working on Phobos and see a LREF macro.

 me arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc
 me arsd:~/d/dmd2/src/phobos$

 ....where is it?

 I happen to know it is hidden in the dlang.org repo, but would someone who saw
a
 problem in the Phobos docs know that? They seem to be generated from the source
 code.... except when they aren't.


That has nothing to do with Ddoc, and is more about the organization of the 
files on github. Switching to another framework does nothing for that.

BTW, when I was working on Phobos docs, Phobos had its own std.ddoc in the 
Phobos repo.


 You can't assume everybody knows all the institutional knowledge you do!


1. digitalmars.D.learn
2. Linux: locate std.ddoc
Dec 17 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 19:51:19 UTC, Walter Bright 
wrote:

 That has nothing to do with Ddoc, and is more about the 
 organization of the files on github. Switching to another 
 framework does nothing for that.


Well, I basically agree with that.

I know it is hard to keep track of whose position is what in a 
thread like this, but my problem isn't with ddoc per se, it is 
more that the current process is very complicated and pretty 
opaque.

I have more hatred toward the makefiles than toward the doc 
format.


 BTW, when I was working on Phobos docs, Phobos had its own 
 std.ddoc in the Phobos repo.


std.ddoc was destroyed ages ago, the file no longer exists!
Dec 17 2015
parent John Colvin <john.loughran.colvin gmail.com> writes:
On Thursday, 17 December 2015 at 20:21:00 UTC, Adam D. Ruppe 
wrote:

 On Thursday, 17 December 2015 at 19:51:19 UTC, Walter Bright 
 wrote:

 That has nothing to do with Ddoc, and is more about the 
 organization of the files on github. Switching to another 
 framework does nothing for that.


 Well, I basically agree with that.

 I know it is hard to keep track of whose position is what in a 
 thread like this, but my problem isn't with ddoc per se, it is 
 more that the current process is very complicated and pretty 
 opaque.


Yes. This. And tbh it's the opaqueness that's the biggest problem.
Dec 18 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/17/15 2:43 PM, Adam D. Ruppe wrote:

 On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote:

 3. to find out what LREF does:

     grep LREF *.ddoc


 So, you're working on Phobos and see a LREF macro.

 me arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc
 me arsd:~/d/dmd2/src/phobos$

 ....where is it?

 I happen to know it is hidden in the dlang.org repo, but would someone
 who saw a problem in the Phobos docs know that? They seem to be
 generated from the source code.... except when they aren't.

 You can't assume everybody knows all the institutional knowledge you do!


A document discussing this kind of stuff would be golden. Maybe a good 
topic for next week's TWiD? -- Andrei
Dec 17 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 19:51:33 UTC, Andrei 
Alexandrescu wrote:

 A document discussing this kind of stuff would be golden. Maybe 
 a good topic for next week's TWiD? -- Andrei


If someone writes it, certainly, but I barely know it myself. I 
have only successfully build the dlang.org site locally once and 
that was after you walked through it and I forgot it all since 
then (except that I remember all the negative emotion of the 
process like frustration)

Our documentation is lacking documentation...

BTW, on the topic of TWiD, I actually do write it in DDoc, but 
there's also a post-processor I run on the generated HTML to make 
up for the lack of things like indexes and some links, and I 
still feel it is a bit of a pain to use. Missing parenthesis 
often leak through to show macros in the end, and having to 
replace $ in links (your message IDs always have them so when I 
link to your threads, I do a $ -> $(DOLLAR) find/replace, but 
gotta be careful to run it only once!)

I'm not unhappy with it and don't want to change it, but I'm not 
terribly happy with it either and kinda wish I did it differently.

Overall, my feeling is just... meh. Ddoc is good for inline 
documentation, and it can become awesome if we do a little more 
work to it (and yes, I might do it myself if I can ever find the 
time), but for stand-alone pages... meh, it gets the job done, at 
least with a bit of help.
Dec 17 2015
prev sibling parent earthfront <earthfront safetymail.info> writes:
On Thursday, 17 December 2015 at 13:44:31 UTC, John Colvin wrote:

 On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright 
 wrote:

 On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote:

 Having said that, though, using ddoc for the website leads to 
 other
 problems (e.g., the ongoing fiasco with XREF, LREF, 
 whatever-REF and the
 associated relative/absolute URL nightmare that a proper web 
 authoring
 system would have taken care of by default).


 Annoying, and maybe you have to spend a couple minutes picking 
 the right one if you've forgotten for the moment => absolute 
 nightmare? Come on.


 How does a user who happens to spot a mistake in the docs and 
 wants to help work this out?


This is happening to me right now.
I have a live editor open in github to edit the template doc 
page. I'm trying to link to std.traits and cannot find how. 
FULL_XREF is used on the same page, but I don't know what 
arguments it can accept.
Mar 20 2016
prev sibling next sibling parent Sebastiaan Koppe <mail skoppe.eu> writes:
On Wednesday, 16 December 2015 at 18:47:26 UTC, deadalnix wrote:

 On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei 
 Alexandrescu wrote:

 What would you have done instead?


 Honestly for D code itself, ddoc does just fine, but for the 
 website, plain html or some known template format like . This 
 is what people know.


Yep. Completely agree.
Dec 16 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 10:47 AM, deadalnix wrote:

 Honestly for D code itself, ddoc does just fine, but for the website, plain
html
 or some known template format like . This is what people know.



I've never heard of .
Dec 17 2015
parent reply jmh530 <john.michael.hall gmail.com> writes:
On Thursday, 17 December 2015 at 19:31:10 UTC, Walter Bright 
wrote:

 On 12/16/2015 10:47 AM, deadalnix wrote:

 Honestly for D code itself, ddoc does just fine, but for the 
 website, plain html
 or some known template format like . This is what people know.



 I've never heard of .


My feedback: add the ability to edit posts in the forum
Dec 17 2015
parent reply Anon <anon anon.anon> writes:
On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote:

 My feedback: add the ability to edit posts in the forum


You can't edit email.
Dec 17 2015
parent reply jmh530 <john.michael.hall gmail.com> writes:
On Thursday, 17 December 2015 at 20:08:32 UTC, Anon wrote:

 On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote:

 My feedback: add the ability to edit posts in the forum


 You can't edit email.


So your point is that the Dlang forum is implemented more like a 
mailing list than a forum? This means that your point is really 
that it would be a lot of work to implement this feature (perhaps 
even migrating to a different type of framework).
Dec 17 2015
next sibling parent JohnCK <j j.com> writes:
On Thursday, 17 December 2015 at 23:30:46 UTC, jmh530 wrote:

 On Thursday, 17 December 2015 at 20:08:32 UTC, Anon wrote:

 On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote:

 My feedback: add the ability to edit posts in the forum


 You can't edit email.




Maybe I can answer your questions:


 So your point is that the Dlang forum is implemented more like 
 a mailing list than a forum?


Yes.


 This means that your point is really that it would be a lot of 
 work to implement this feature (perhaps even migrating to a 
 different type of framework).


I think shouldn't count on that.

JohnCK.
Dec 17 2015
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Dec 17, 2015 at 11:30:46PM +0000, jmh530 via Digitalmars-d wrote:

 On Thursday, 17 December 2015 at 20:08:32 UTC, Anon wrote:

On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote:

My feedback: add the ability to edit posts in the forum


You can't edit email.


 
 So your point is that the Dlang forum is implemented more like a
 mailing list than a forum? This means that your point is really that
 it would be a lot of work to implement this feature (perhaps even
 migrating to a different type of framework).


Some of us (including myself) do not use the forum.dlang.org interface
at all, but actually receive messages in email form. I prefer it that
way because I find the online forum interface klunky and inefficient to
use (though most would disagree), whereas in email form I can navigate
and manage discussion threads with far greater efficiency. I would hate
to have to actually start up a resource-hogging browser just to read
forum posts.


T

-- 
Making non-nullable pointers is just plugging one hole in a cheese grater. --
Walter Bright
Dec 17 2015
parent reply JohnCK <j j.com> writes:
On Friday, 18 December 2015 at 00:43:11 UTC, H. S. Teoh wrote:

 ... I find the online forum interface klunky and inefficient to 
 use (though most would disagree),


One thing that bothers me sometimes is the waste of space, as  
you can see in this SS, there are 2 versions, the original with 
highlights and the other that I modified.

http://i.imgur.com/lx2qA7d.png

JohnCK.
Dec 17 2015
parent JohnCK <j j.com> writes:
On Friday, 18 December 2015 at 01:17:26 UTC, JohnCK wrote:

 On Friday, 18 December 2015 at 00:43:11 UTC, H. S. Teoh wrote:

 ... I find the online forum interface klunky and inefficient 
 to use (though most would disagree),


 One thing that bothers me sometimes is the waste of space, as  
 you can see in this SS, there are 2 versions, the original with 
 highlights and the other that I modified.

 http://i.imgur.com/lx2qA7d.png

 JohnCK.


Maybe what I said above sound silly, but I'd like to take and say 
that I forgot to explain that space is very important on tiny 
screens like Tablets, in my case Galaxy Tab 3 - 7" inches.

And I'd to take the opportunity to point out another problem that 
I've found in some pages like:

1) On the menu -> resources -> New Library reference preview, 
some links are not working, example:

https://dlang.org/library/std/algorithm/comparison.html  <- In 
the top of the page there is:  This is submodule of 
"std.algorithm" <- Wrong link.

And the same thing is happening for the other pages like: 
https://dlang.org/library/std/algorithm/iteration.html and goes 
on...

2) Finally, in this page: 
https://dlang.org/phobos/std_algorithm.html, someone use align 
text set as "JUSTIFY", see how beautiful is in my Tablet:

http://i.imgur.com/bJKy6p7.png  (I highlighted in red).

JohnCK.
Dec 18 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-16 02:15, Andrei Alexandrescu wrote:


 It seems knowing ddoc is part of knowing D. -- Andrei


I'm wondering how you can think it's perfectly acceptable to invent our 
own (crappy) language for documentation and at the same time loudly 
complain that SDLang is use for Dub config files and not a (more widely) 
standardized format.

-- 
/Jacob Carlborg
Dec 16 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/15 3:00 AM, Jacob Carlborg wrote:

 On 2015-12-16 02:15, Andrei Alexandrescu wrote:


 It seems knowing ddoc is part of knowing D. -- Andrei


 I'm wondering how you can think it's perfectly acceptable to invent our
 own (crappy) language for documentation and at the same time loudly
 complain that SDLang is use for Dub config files and not a (more widely)
 standardized format.


What standardized format was dominant in 2001? Thanks! -- Andrei
Dec 16 2015
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-12-16 14:50, Andrei Alexandrescu wrote:


 What standardized format was dominant in 2001? Thanks! -- Andrei


2001? According to the changelog Ddoc was added 2005 [1]. I hadn't 
really started to use D back then and barely programming at all. I would 
say Javadoc, Doxygen or Markdown, without knowing how standardized they 
were back then (if they existed).

But most important, Ddoc should not be used for website. I would prefer 
a template language with a proper server side language. Something like 
Haml, which allows to use filters where Markdown is one of the filters 
[2]. Good when writing longer texts. vibe.d's diet templates seems to be 
a good choice, it's indirectly based on Haml. Not sure if it supports 
filters though.

[1] http://www.digitalmars.com/d/1.0/changelog1.html#new0132
[2] http://haml.info/docs/yardoc/file.REFERENCE.html#filters

-- 
/Jacob Carlborg
Dec 16 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 5:50 AM, Andrei Alexandrescu wrote:

 On 12/16/15 3:00 AM, Jacob Carlborg wrote:

 On 2015-12-16 02:15, Andrei Alexandrescu wrote:


 It seems knowing ddoc is part of knowing D. -- Andrei


 I'm wondering how you can think it's perfectly acceptable to invent our
 own (crappy) language for documentation and at the same time loudly
 complain that SDLang is use for Dub config files and not a (more widely)
 standardized format.


 What standardized format was dominant in 2001? Thanks! -- Andrei


To be fair, Ddoc came along later.

But Jacob has a good point. I looked at 2 other systems in common use at the 
time - Javadoc, which I thought was aesthetically ugly, and Doxygen, which is 
aesthetically ugly and way overly complex, as well as being C++ specific.

I wanted a system that looked good even without processing, i.e. it looked good 
in the the source code for basic use. Javadoc, Doxygen, both failed at that.

Ddoc looks good in its basic use, is ridiculously simple, and has proven 
powerful enough to generate html, pdf, Latex, and Kindle ebook results from the 
same source.

Ddoc has its shortcomings, too, like unittest. But it has achieved its goal, 
like unittest, which is to be so easy to use and built in that it it becomes 
completely natural to use it.

I regard unittest and Ddoc as being extremely successful in that they have 
transformed D programming. (This is true of Javadoc as well, but not for
Doxygen.)

BTW, I've also used Ddoc to create several ebooks which I've published on 
Amazon, and for all the web sites I've created. It works very nicely for that.
I 
don't think Doxygen nor Javadoc is useable in that way. It's kinda weird to run 
a history book through dmd to get an ebook out, but also kinda cool :-)
Dec 16 2015
prev sibling parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote:

 On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei 
 Alexandrescu wrote:

 On 12/15/15 5:54 AM, tcak wrote:

 The harder it is made for people to contribute the system for 
 fixations,
 the lesser changes are seen.


 I don't think we've had many contributions via the "Improve 
 this page" button.


 I don't know how representative it is, but once in a while, i 
 forgot all of this is in DDoc, I notice something, what to do a 
 quick patch, and end up being reminded this is in DDoc and I 
 have no idea how to fix the thing, because suddenly, what 
 looked like a quick fix end up being learning a new macro 
 language.


DDoc itself is very simple. The problem is the endless number of 
macros we use on dlang.org. E.g. all the different ways to link 
to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, 
XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, 
COREMODREF, OBJREF... There is also no strong reason to use e.g. 
DIVCID instead of plain HTML.
Dec 16 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 03:05 PM, Vladimir Panteleev wrote:

 DDoc itself is very simple. The problem is the endless number of macros
 we use on dlang.org.


I see that as a blessing.


 E.g. all the different ways to link to something:
 A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, XREF2, CXREF,
 ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, OBJREF...


If some of these are unnecessary, they can be easily fixed. There's no 
problem with breaking other people's code etc.

Which would you eliminate?


 There is also
 no strong reason to use e.g. DIVCID instead of plain HTML.


I agree. I added that more for completeness, easier typing, and so I can 
rely on editors showing the closing paren.


Andrei
Dec 16 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-12-16 21:59, Andrei Alexandrescu wrote:


 If some of these are unnecessary, they can be easily fixed. There's no
 problem with breaking other people's code etc.

 Which would you eliminate?


A sane doc generation system would need at most two 
macros/syntaxes/functions to create links. One macro accepting a symbol 
name (fully qualified or not) used for cross-referencing and one macro 
used for page and external links, accepting a relative or an absolute URL.

It's also possible to manged without any of these at all. The doc tool 
could automatically do cross-referencing and detect URL's.

-- 
/Jacob Carlborg
Dec 16 2015
prev sibling next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 08:05:03PM +0000, Vladimir Panteleev via Digitalmars-d
wrote:

 On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote:

On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote:

On 12/15/15 5:54 AM, tcak wrote:

The harder it is made for people to contribute the system for
fixations, the lesser changes are seen.


I don't think we've had many contributions via the "Improve this
page" button.


I don't know how representative it is, but once in a while, i forgot
all of this is in DDoc, I notice something, what to do a quick patch,
and end up being reminded this is in DDoc and I have no idea how to
fix the thing, because suddenly, what looked like a quick fix end up
being learning a new macro language.


 
 DDoc itself is very simple. The problem is the endless number of
 macros we use on dlang.org. E.g. all the different ways to link to
 something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF,
 XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF,
 OBJREF... There is also no strong reason to use e.g. DIVCID instead of
 plain HTML.


Yeah, this is like spaghetti code written with C macros, where all macro
names are in the same namespace, there is no scoping (everything is
global), and undocumented so nobody knows what's already there or when
to use what, and reinvents their own unhelpfully-named macros. Worse
yet, sometimes people write their own implementations of existing macros
with the same name so it's far from obvious which macro is actually in
force when a particular part of the website is being processed -- this
actually happens in the dlang.org repo: try grepping for XREF or LREF
sometime, and see how many different definitions there are, for example.
Or how many different macros there are for generating hyperlinks -- when
should each one be used? Who knows. Read the code^Wmacro definitions to
find out.

Also, the lack of flexibility in number of macro arguments means you end
up with LINK, LINK2, LINK3, etc., with no obvious indication what the
difference is and where you should use which macro. It's like a
worst-case scenario C library that has printf1, printf2, printf3, ...,
instead of printf, fprintf, snprintf, etc., and people are expected to
remember which numerical suffix does what.

It's relatively easy to keep track of this in single-person projects --
Walter's using ddoc for creating ebooks, for example -- but in large
collaborative projects these seemingly-minor issues lead to spaghetti
macro-ni soup. The messy, inconsistent tangle that is the dlang.org
macros constitute a high barrier-to-entry for would-be contributors.
Mostly people just end up copy-n-pasting stuff without understanding
what's really going on.  We're at the ironical situation where ddoc
macros need their usage documented -- by another ddoc page? :-P


T

-- 
There is no gravity. The earth sucks.
Dec 16 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote:

 Also, the lack of flexibility in number of macro arguments means you end
 up with LINK, LINK2, LINK3, etc., with no obvious indication what the
 difference is and where you should use which macro.


(Well the obvious indication is the number innit :o).)

A _simple_ way to handle arity might be worth adding to ddoc. Any ideas?


Andrei
Dec 16 2015
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 06:18:22PM -0500, Andrei Alexandrescu via Digitalmars-d
wrote:

 On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote:

Also, the lack of flexibility in number of macro arguments means you
end up with LINK, LINK2, LINK3, etc., with no obvious indication what
the difference is and where you should use which macro.


 
 (Well the obvious indication is the number innit :o).)


But does the number mean the number of arguments, or the number of
arguments past the mandatory arguments, or an incremental poor man's
macro version number, or ...?

I think some agreed-on common naming conventions for ddoc macros
(perhaps just restricted to dlang.org / phobos / etc.) would go a long
way in alleviating this issue. Right now it's just a random grab-bag
where it's every man for himself and anything goes.



 A _simple_ way to handle arity might be worth adding to ddoc. Any
 ideas?


[...]

Allow overloading by number of arguments, maybe? (This sounds
suspiciously like a slippery slope, though...)

Or allow argument list slicing, D-style?  Not sure if this would solve
all the necessary cases.


T

-- 
Answer: Because it breaks the logical sequence of discussion. / Question: Why
is top posting bad?
Dec 16 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 06:29 PM, H. S. Teoh via Digitalmars-d wrote:

 Allow overloading by number of arguments, maybe? (This sounds
 suspiciously like a slippery slope, though...)


That'll have trouble with $0 and $+.


 Or allow argument list slicing, D-style?  Not sure if this would solve
 all the necessary cases.


Overall I think a few additions to the macro engine could be very 
beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to 
expand b if a is nonempty and c otherwise.


Andrei
Dec 16 2015
next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 06:46:46PM -0500, Andrei Alexandrescu via Digitalmars-d
wrote:

 On 12/16/2015 06:29 PM, H. S. Teoh via Digitalmars-d wrote:

Allow overloading by number of arguments, maybe? (This sounds
suspiciously like a slippery slope, though...)


 
 That'll have trouble with $0 and $+.


Not if we adopt the rule that if there are more arguments than the
overload with the most number of arguments, then that overload is
invoked.

OTOH, I just realized that macro definitions don't indicate the number
of parameters. Perhaps overloads should be defined with different
syntax? E.g.:

	// old syntax:
	NON_OVERLOADABLE = blah $0 blah $1 blah $+

	// new (additional) syntax:
	OVERLOADABLE(a) = blah $a blah
	OVERLOADABLE(a,b) = blah $a blah $b blah
	OVERLOADABLE(a,b,c) = blah $a blah $b blah $c blah

Having parameter names will also help readability; currently, with $1,
$2, $3 it's non-obvious what each parameter is supposed to be without
reading the macro definition.

The old parameterless syntax then can be reserved for truly variadic
macros.



Or allow argument list slicing, D-style?  Not sure if this would
solve all the necessary cases.


 
 Overall I think a few additions to the macro engine could be very
 beneficial. E.g. while working on dconf.org I could use $(IF a, b, c)
 to expand b if a is nonempty and c otherwise.


[...]

This will make ddoc Turing-complete, which may or may not be what you
want. :-D

(Although IIRC ddoc does impose a limit on recursion depth, so perhaps
it won't *quite* be Turing complete just yet...)


T

-- 
I think the conspiracy theorists are out to get us...
Dec 16 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 00:46, Andrei Alexandrescu wrote:


 Overall I think a few additions to the macro engine could be very
 beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to
 expand b if a is nonempty and c otherwise.


Oh, God, please no. Just use vibe.d and be done with it. We obviously 
need a proper programming language to generate dconf.org.

-- 
/Jacob Carlborg
Dec 17 2015
next sibling parent reply wobbles <grogan.colin gmail.com> writes:
On Thursday, 17 December 2015 at 08:06:28 UTC, Jacob Carlborg 
wrote:

 On 2015-12-17 00:46, Andrei Alexandrescu wrote:


 Overall I think a few additions to the macro engine could be 
 very
 beneficial. E.g. while working on dconf.org I could use $(IF 
 a, b, c) to
 expand b if a is nonempty and c otherwise.


 Oh, God, please no. Just use vibe.d and be done with it. We 
 obviously need a proper programming language to generate 
 dconf.org.


That would be a whole re-write of the website though.

It would be preferable of course. The official D site being run 
through one of it's more popular libraries (it's most popular 
library maybe?) can only be a good thing.
Dec 17 2015
parent Sebastiaan Koppe <mail skoppe.eu> writes:
On Thursday, 17 December 2015 at 08:15:49 UTC, wobbles wrote:

 That would be a whole re-write of the website though.


We could of course also use ddoc and write a generator to 
whatever template language we like. The rest is peanuts.
Dec 17 2015
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 08:06:28 UTC, Jacob Carlborg 
wrote:

 We obviously need a proper programming language to generate 
 dconf.org.


I can't agree with this. I think there's too many conditionals 
already. Build the docs on posix and you miss out on Windows 
functions. Ugh.
Dec 17 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/17/15 3:06 AM, Jacob Carlborg wrote:

 Oh, God, please no. Just use vibe.d and be done with it. We obviously
 need a proper programming language to generate dconf.org.


We are already using vibe.d for the Phobos page-per-name documentation. 
As far as I can tell the initiative has been a qualified success.

The main problem there is that there are not enough folks to maintain 
the vibe-related artifacts. Basically when Sönke is busy with something 
else, any issue may wait indefinitely. (I haven't followed that lately, 
possibly things have improved as of late.)

In order to make the use of vibe.d entirely successful across dlang.org 
and dconf.org, we need to show robust gains from using it for Phobos. As 
virtually the sole maintainer of dconf.org, I'd feel definitely 
motivated to use vibe.d if there was good evidence of thriving 
collaboration around the use of it on http://dlang.org/library.

Jacob, are you willing to ramp up you contribution to the vibe.d-related 
parts of Phobos? That would go a long way toward convincing everyone of 
the productivity gains of using it instead of ddoc (or others).


Andrei
Dec 17 2015
parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 23:40, Andrei Alexandrescu wrote:


 We are already using vibe.d for the Phobos page-per-name documentation.
 As far as I can tell the initiative has been a qualified success.


What's left/stopping us from using this as the default documentation?


 The main problem there is that there are not enough folks to maintain
 the vibe-related artifacts. Basically when Sönke is busy with something
 else, any issue may wait indefinitely. (I haven't followed that lately,
 possibly things have improved as of late.)

 In order to make the use of vibe.d entirely successful across dlang.org
 and dconf.org, we need to show robust gains from using it for Phobos. As
 virtually the sole maintainer of dconf.org, I'd feel definitely
 motivated to use vibe.d if there was good evidence of thriving
 collaboration around the use of it on http://dlang.org/library.

 Jacob, are you willing to ramp up you contribution to the vibe.d-related
 parts of Phobos? That would go a long way toward convincing everyone of
 the productivity gains of using it instead of ddoc (or others).


I would like to but I'm very busy as well. In addition to that I have 
basically no knowledge of the internals of the vibe.d related parts. I 
had a look at some PR's for Dub (I think) that Sönke called out for help 
with. I didn't feel I could add much help to that.

Is there anything more specific you're thinking about?

-- 
/Jacob Carlborg
Dec 18 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/18/15 3:06 AM, Jacob Carlborg wrote:

 On 2015-12-17 23:40, Andrei Alexandrescu wrote:


 We are already using vibe.d for the Phobos page-per-name documentation.
 As far as I can tell the initiative has been a qualified success.


 What's left/stopping us from using this as the default documentation?


As I said: a growing number of people able and willing to maintain and 
improve it. -- Andrei
Dec 18 2015
next sibling parent Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
On Friday, 18 December 2015 at 13:15:54 UTC, Andrei Alexandrescu 
wrote:

 As I said: a growing number of people able and willing to 
 maintain and improve it. -- Andrei


Which would grow "tremendously" if it was using an online 
interface backed by a database.
Dec 18 2015
prev sibling next sibling parent Dragos Carp <dragoscarp gmail.com> writes:
On Friday, 18 December 2015 at 13:15:54 UTC, Andrei Alexandrescu 
wrote:

 On 12/18/15 3:06 AM, Jacob Carlborg wrote:

 On 2015-12-17 23:40, Andrei Alexandrescu wrote:


 We are already using vibe.d for the Phobos page-per-name 
 documentation.
 As far as I can tell the initiative has been a qualified 
 success.


 What's left/stopping us from using this as the default 
 documentation?


 As I said: a growing number of people able and willing to 
 maintain and improve it. -- Andrei


Two issues with the ddox generated documentation:

1. `static if` code is not shown [1]
2. probably some aliases are too early "resolved"
   Look for the type of sz that would be wrong on 32-bit:

     http://dlang.org/library-prerelease/core/memory/gc.malloc.html

[1] https://github.com/rejectedsoftware/ddox/issues/86
Dec 18 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-18 14:15, Andrei Alexandrescu wrote:


 As I said: a growing number of people able and willing to maintain and
 improve it. -- Andrei


I'm not sure if there's some miscommunications here.

But more contributors will not magically help. There most be a reason 
for why Ddox is not the default documentation. Some features that are 
missing, some parts that are not good enough or similar. There needs to 
be a list of criteria for when Ddox can be made default. The 
contributors can work on these tasks that will improve Ddox which will 
eventually lead to making Ddox default.

I'm asking for specifics. If nobody has the answer for this we don't 
know why Ddox is not good enough. And if we don't know that we can't 
really know that it's not good enough. And if that's the case it could 
be made the default right now.

-- 
/Jacob Carlborg
Dec 19 2015
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Saturday, 19 December 2015 at 10:54:36 UTC, Jacob Carlborg 
wrote:

 On 2015-12-18 14:15, Andrei Alexandrescu wrote:


 As I said: a growing number of people able and willing to 
 maintain and
 improve it. -- Andrei


 I'm not sure if there's some miscommunications here.

 But more contributors will not magically help. There most be a 
 reason for why Ddox is not the default documentation. Some 
 features that are missing, some parts that are not good enough 
 or similar. There needs to be a list of criteria for when Ddox 
 can be made default. The contributors can work on these tasks 
 that will improve Ddox which will eventually lead to making 
 Ddox default.

 I'm asking for specifics. If nobody has the answer for this we 
 don't know why Ddox is not good enough. And if we don't know 
 that we can't really know that it's not good enough. And if 
 that's the case it could be made the default right now.


There is no definitive answer for when something is "good 
enough", but to get you started:

https://github.com/rejectedsoftware/ddox/issues

Note that many of these are essentially DMD JSON output 
bugs/limitations.
Dec 20 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-12-21 04:44, Vladimir Panteleev wrote:


 There is no definitive answer for when something is "good enough"


If nobody knows what it takes to make Ddox the default, how do we know 
that it's not already good enough?


 but to get you started:

 https://github.com/rejectedsoftware/ddox/issues


Finally :)

-- 
/Jacob Carlborg
Dec 21 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 3:18 PM, Andrei Alexandrescu wrote:

 On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote:

 Also, the lack of flexibility in number of macro arguments means you end
 up with LINK, LINK2, LINK3, etc., with no obvious indication what the
 difference is and where you should use which macro.


 (Well the obvious indication is the number innit :o).)

 A _simple_ way to handle arity might be worth adding to ddoc. Any ideas?


Note that Ddoc macros already support CDR/CAR. These are already used to great 
effect with the TROW macro. I suggest exploring this before new features.
Dec 16 2015
prev sibling parent reply John Colvin <john.loughran.colvin gmail.com> writes:
On Wednesday, 16 December 2015 at 20:05:03 UTC, Vladimir 
Panteleev wrote:

 On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote:

 On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei 
 Alexandrescu wrote:

 On 12/15/15 5:54 AM, tcak wrote:

 The harder it is made for people to contribute the system 
 for fixations,
 the lesser changes are seen.


 I don't think we've had many contributions via the "Improve 
 this page" button.


 I don't know how representative it is, but once in a while, i 
 forgot all of this is in DDoc, I notice something, what to do 
 a quick patch, and end up being reminded this is in DDoc and I 
 have no idea how to fix the thing, because suddenly, what 
 looked like a quick fix end up being learning a new macro 
 language.


 DDoc itself is very simple. The problem is the endless number 
 of macros we use on dlang.org. E.g. all the different ways to 
 link to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, 
 LREF, XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, 
 COREMODREF, OBJREF... There is also no strong reason to use 
 e.g. DIVCID instead of plain HTML.


The number of macros bothers me, but mostly it's the complete 
lack of documentation and guidelines on where/how to use them*.
It's pretty unreasonable to expect someone submitting a passing 
doc fix to
1) find where the macros are defined
2) decipher them
3) use the "right" one**
It's just too much unpleasant work for people to bother with.

*If there is documentation and guidelines on this and I don't 
know about it, consider what it would be like for someone who 
doesn't spend many hours a week on the various subdomains of 
dlang.org: it might as well not exist!

**there must be some reasons for the existence of all of those 
macros, so presumably there are good and bad choices for certain 
situations, even if nothing is obviously broken using the bad 
choice. Sure, we might say "submit something naïve and then 
people will help you fix it", but that's still a barrier to 
entry; 1) how were they supposed to know we felt that way about 
submissions? 2) people don't like looking stupid.
Dec 17 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/17/2015 4:27 AM, John Colvin wrote:

 The number of macros bothers me, but mostly it's the complete lack of
 documentation and guidelines on where/how to use them*.
 It's pretty unreasonable to expect someone submitting a passing doc fix to
 1) find where the macros are defined
 2) decipher them
 3) use the "right" one**
 It's just too much unpleasant work for people to bother with.

 *If there is documentation and guidelines on this and I don't know about it,
 consider what it would be like for someone who doesn't spend many hours a week
 on the various subdomains of dlang.org: it might as well not exist!

 **there must be some reasons for the existence of all of those macros, so
 presumably there are good and bad choices for certain situations, even if
 nothing is obviously broken using the bad choice. Sure, we might say "submit
 something naïve and then people will help you fix it", but that's still a
 barrier to entry; 1) how were they supposed to know we felt that way about
 submissions? 2) people don't like looking stupid.


Documentation in the std.ddoc files would certainly help. $(COMMENT this is 
comment) is a convention that works well. PRs to add explanatory comments are 
welcome.
Dec 17 2015
prev sibling parent reply Jack Stouffer <jack jackstouffer.com> writes:
On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu 
wrote:

 Yes, the css has grown long in the teeth. Just replacing it 
 with something else is needed, even if it's not an actual 
 improvement.


I have to disagree with you heavily on this point. Changing the 
look and feel of a site just for the sake of change is a lot of 
work for little gain. The issue with the site is not the CSS in 
the majority of cases but the content.

Also, you saying "even if it's not an actual improvement"  is a 
real head scratcher for me. We need a change even if it makes 
things worse?


 A related idea is to investigate the use of 
 http://sourcefoundry.org/hack/ for the code samples. Takers?


This would be rather simple to implement, but custom fonts make 
pages load slower, on average 100-150ms. When the front page 
already takes 2secs+ to load entirely, I would want to do some 
optimizations first before this happens.

Some easy wins which could net a 500ms+ speedup:

* use gzip on everything
* minify and concatenate css files
* minify and concatenate js files
* use cache busting plus long cache times in HTTP headers

Unfortunately, all of these require the server admin (whoever 
that is) to do it and can't be done via PR.
Dec 15 2015
next sibling parent Jack Stouffer <jack jackstouffer.com> writes:
On Tuesday, 15 December 2015 at 22:45:30 UTC, Jack Stouffer wrote:

 * use gzip on everything
 * minify and concatenate css files
 * minify and concatenate js files
 * use cache busting plus long cache times in HTTP headers


I made bug reports for all of these

https://issues.dlang.org/show_bug.cgi?id=15451
https://issues.dlang.org/show_bug.cgi?id=15449
https://issues.dlang.org/show_bug.cgi?id=15448
Dec 15 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/15/2015 05:45 PM, Jack Stouffer wrote:

 On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote:

 Yes, the css has grown long in the teeth. Just replacing it with
 something else is needed, even if it's not an actual improvement.


 I have to disagree with you heavily on this point. Changing the look and
 feel of a site just for the sake of change is a lot of work for little
 gain.


This is easy to refute because only one counter-example is needed. I 
made a bunch of non-improvement changes in early 2014. The success was 
tremendous. -- Andrei
Dec 15 2015
next sibling parent Ola Fosheim =?UTF-8?B?R3LDuHN0YWQ=?= writes:
On Wednesday, 16 December 2015 at 01:18:03 UTC, Andrei 
Alexandrescu wrote:

 This is easy to refute because only one counter-example is 
 needed. I made a bunch of non-improvement changes in early 
 2014. The success was tremendous. -- Andrei


Was it? How did you measure the success?
Dec 15 2015
prev sibling parent deadalnix <deadalnix gmail.com> writes:
On Wednesday, 16 December 2015 at 01:18:03 UTC, Andrei 
Alexandrescu wrote:

 On 12/15/2015 05:45 PM, Jack Stouffer wrote:

 On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei 
 Alexandrescu wrote:

 Yes, the css has grown long in the teeth. Just replacing it 
 with
 something else is needed, even if it's not an actual 
 improvement.


 I have to disagree with you heavily on this point. Changing 
 the look and
 feel of a site just for the sake of change is a lot of work 
 for little
 gain.


 This is easy to refute because only one counter-example is 
 needed. I made a bunch of non-improvement changes in early 
 2014. The success was tremendous. -- Andrei


Yeah that is important. That's the difference between and iPhone 
and other phones. It does the exact same thing, yet people are 
willing to pay $200 more.
Dec 15 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/15/2015 05:45 PM, Jack Stouffer wrote:

 Also, you saying "even if it's not an actual improvement"  is a real
 head scratcher for me. We need a change even if it makes things worse?


It's visuals, not engineering. Put your artist hat on. "Not better" does 
not mean "worse". -- Andrei
Dec 15 2015
prev sibling parent Jack Stouffer <jack jackstouffer.com> writes:
On Tuesday, 15 December 2015 at 10:54:09 UTC, tcak wrote:

 It bothers me so much to report a bug on 
 https://issues.dlang.org . The reason is that the password 
 stops working for me. Firefox saves the username and password. 
 I try to use it after 2 months, and whops, system says it isn't 
 available.


Never had this happen to me. What browser and OS are you using, 
because issues.dlang.org runs on bugzilla, which is a very 
popular piece of software that is used all over the place.


 Another issue is contributing the website's design. I reported 
 a problem on the forum that is about the title problem of web 
 page. 
 http://forum.dlang.org/thread/pymfyjuckxbvjolxlczg forum.dlang.org Still the
problem will be fixed.


I made a PR for that issue 
https://github.com/D-Programming-Language/dlang.org/pull/1167

It has yet to be reviewed by someone with merge rights.


 Now I am asking, IF I was to make some changes for web site's 
 look, and post a picture of them (CSS changes mostly), would it 
 be okay to discuss it here, and apply them in short notice? If 
 a change would take 1 week, that doesn't work. I am
 offering help here.


Sorry, but it's completely infeasible for anyone to propose a 
sweeping style change and expect it to go through quickly, 
especially sense I can guarantee that there are going to be 
issues with the first draft you make. If you were to make a PR, 
I'd expect it to be either accepted or rejected after maybe two 
months of deliberation, if you're lucky. This is the nature of 
volunteer work.
Dec 15 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/15/15 3:31 AM, Gary Willoughby wrote:

 We've all said time and time again if ddoc wasn't used for the entire
 site more people would help with it. Ddoc makes sense for the
 documentation but not everything else.


I'm not sure about this. There are very very many potential improvements 
that are important, easy to do, not related to the use of ddoc, and 
don't get done.


 I thought Sociomantic were re-designing and sorting the site out?


Not for the time being.


Andrei
Dec 15 2015
parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-15 14:15, Andrei Alexandrescu wrote:


 I'm not sure about this. There are very very many potential improvements
 that are important, easy to do, not related to the use of ddoc, and
 don't get done.


One still most likely need to build the site, which is kind of a pain to do.

-- 
/Jacob Carlborg
Dec 15 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/15 2:56 AM, Jacob Carlborg wrote:

 On 2015-12-15 14:15, Andrei Alexandrescu wrote:


 I'm not sure about this. There are very very many potential improvements
 that are important, easy to do, not related to the use of ddoc, and
 don't get done.


 One still most likely need to build the site, which is kind of a pain to
 do.


Building the site mimicks building dmd, druntime, and phobos. It's an 
invocation of make. What are the difficulties? -- Andrei
Dec 16 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 16 December 2015 at 13:49:22 UTC, Andrei 
Alexandrescu wrote:

 One still most likely need to build the site, which is kind of 
 a pain to
 do.


 Building the site mimicks building dmd, druntime, and phobos. 
 It's an invocation of make. What are the difficulties? -- Andrei


Building dmd, druntime, and phobos is a big pain in the butt too.

To check a change to the documentation right now, you first need 
to download and build git dmd (which depends on an existing dmd). 
Then druntime and phobos with it. Only then are you in a position 
to build the website since it depends on running the compiler 
over phobos which often depends on bleeding edge dmd.

Maybe that's easy if you're already running bleeding edge 
everything, but it is an awful lot of process when you just want 
to eyeball a quick visual change.

(and there's all the stuff about git branches being out of sync 
for me too because I'm a more casual contributor)

When I make doc changes, I tend to just do it blind on the 
website and hope it works because it isn't worth spending half an 
hour setting up just to paste in an example or something.


...and then the auto-tester is awfully whiny so the pull request 
needs more adjustment and I'm left dropping f-bombs and vowing to 
never try contributing to upstream D again.
Dec 16 2015
parent mate <aiueo aiueo.aiueo> writes:
On Wednesday, 16 December 2015 at 15:19:12 UTC, Adam D. Ruppe 
wrote:

 On Wednesday, 16 December 2015 at 13:49:22 UTC, Andrei 
 Alexandrescu wrote:

 One still most likely need to build the site, which is kind 
 of a pain to
 do.


 Building the site mimicks building dmd, druntime, and phobos. 
 It's an invocation of make. What are the difficulties? -- 
 Andrei


 Building dmd, druntime, and phobos is a big pain in the butt 
 too.

 To check a change to the documentation right now, you first 
 need to download and build git dmd (which depends on an 
 existing dmd). Then druntime and phobos with it. Only then are 
 you in a position to build the website since it depends on 
 running the compiler over phobos which often depends on 
 bleeding edge dmd.

 Maybe that's easy if you're already running bleeding edge 
 everything, but it is an awful lot of process when you just 
 want to eyeball a quick visual change.

 (and there's all the stuff about git branches being out of sync 
 for me too because I'm a more casual contributor)

 When I make doc changes, I tend to just do it blind on the 
 website and hope it works because it isn't worth spending half 
 an hour setting up just to paste in an example or something.


 ...and then the auto-tester is awfully whiny so the pull 
 request needs more adjustment and I'm left dropping f-bombs and 
 vowing to never try contributing to upstream D again.


Indeed the effort required to make a simple change to the website 
is unacceptable.

Independent from the ddoc discussion, this could be solved with a 
server showing the code of a given page of the site, allowing 
editing and showing the resulting modification.
Dec 16 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/15/2015 12:31 AM, Gary Willoughby wrote:

 We've all said time and time again if ddoc wasn't used for the entire site more
 people would help with it. Ddoc makes sense for the documentation but not
 everything else.


I'm not so sure. There are lots of tools to develop websites. Let's say A, B, 
and C. If we picked "B", we most assuredly would have analogous threads here 
saying "I won't use anything but A" and "Everybody else uses C."



 more people would help with it.


I've heard all sorts of excuses for decades about why people won't chip in, and 
I know they are excuses because when the excuse is fixed, they still won't chip 
in. This excuse sounds the same as the rest.

The thing is, if you know html, then you know Ddoc. Ddoc is just a stupidly 
simple text-substitution macro system a programmer should be able to learn in a 
few minutes.

I do agree that the macros defined in the site's .ddoc files are ridiculously 
overlapping, redundant, etc. That all could use a redesign and an overhaul, but 
that isn't Ddoc's fault. It's just like any piece of crap code that has
suffered 
from too many quick&dirty hacks layered on to it.
Dec 16 2015
next sibling parent reply JohnCK <johnck gmail.com> writes:
On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright 
wrote:

 I'm not so sure...


Like they say: "A father will never agree that his child is ugly!"

:)

John.
Dec 16 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 03:59 PM, JohnCK wrote:

 On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:

 I'm not so sure...


 Like they say: "A father will never agree that his child is ugly!"


To me it seems he's making a few good points. -- Andrei
Dec 16 2015
parent reply JohnCK <johnck gmail.com> writes:
On Wednesday, 16 December 2015 at 21:06:48 UTC, Andrei 
Alexandrescu wrote:

 On 12/16/2015 03:59 PM, JohnCK wrote:

 On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright 
 wrote:

 I'm not so sure...


 Like they say: "A father will never agree that his child is 
 ugly!"


 To me it seems he's making a few good points. -- Andrei


Ops, just to clarify, I
Dec 16 2015
parent JohnCK <johnck gmail.com> writes:
On Wednesday, 16 December 2015 at 21:18:43 UTC, JohnCK wrote:

 On Wednesday, 16 December 2015 at 21:06:48 UTC, Andrei 
 Alexandrescu wrote:

 On 12/16/2015 03:59 PM, JohnCK wrote:

 On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright 
 wrote:

 I'm not so sure...


 Like they say: "A father will never agree that his child is 
 ugly!"


 To me it seems he's making a few good points. -- Andrei


 Ops, just to clarify, I


Ops again, so just to clarify, I'm not saying the ddocs is that 
ugly, but let's face it, like others said it has some flaws or 
otherwise it wouldn't be so discussed every time.

JohnCK.
Dec 16 2015
prev sibling next sibling parent reply deadalnix <deadalnix gmail.com> writes:
On Wednesday, 16 December 2015 at 20:59:46 UTC, JohnCK wrote:

 On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright 
 wrote:

 I'm not so sure...


 Like they say: "A father will never agree that his child is 
 ugly!"

 :)

 John.


Please don't go there. This is not about if ddoc is good or not, 
this is about making the website better.

In that regard, I think it is fair to asses that people that know 
webdev don't know ddoc an vice versa. So using ddoc is probably 
not the best bet here.
Dec 16 2015
next sibling parent JohnCK <johnck gmail.com> writes:
On Wednesday, 16 December 2015 at 21:17:43 UTC, deadalnix wrote:

 On Wednesday, 16 December 2015 at 20:59:46 UTC, JohnCK wrote:

 On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright 
 wrote:

 I'm not so sure...


 Like they say: "A father will never agree that his child is 
 ugly!"

 :)

 John.


 Please don't go there...


Dude just read my message above. Furthermore It was just a joke 
with Walter.

JohnCK.
Dec 16 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/16/2015 04:17 PM, deadalnix wrote:

 In that regard, I think it is fair to asses that people that know webdev
 don't know ddoc an vice versa. So using ddoc is probably not the best
 bet here.


Yah, agreed (though I have to say it's not that fair to my tushy :o)). 
-- Andrei
Dec 16 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/16/2015 12:59 PM, JohnCK wrote:

 On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:

 I'm not so sure...


 Like they say: "A father will never agree that his child is ugly!"

 :)


I've pontificated before about design mistakes in D that I've made. I also
think 
that a lot of the dmd code I wrote is ugly crap.
Dec 16 2015
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 03:04:51PM -0800, Walter Bright via Digitalmars-d wrote:

 On 12/16/2015 12:59 PM, JohnCK wrote:

On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:

I'm not so sure...


Like they say: "A father will never agree that his child is ugly!"

:)


 
 I've pontificated before about design mistakes in D that I've made. I
 also think that a lot of the dmd code I wrote is ugly crap.


It would be interesting to hear what you think are design mistakes.

And also, perhaps for the longer term, how you'd have done things
differently if you could turn back time. :-)


T

-- 
Questions are the beginning of intelligence, but the fear of God is the
beginning of wisdom.
Dec 16 2015
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 16, 2015 at 12:54:35PM -0800, Walter Bright via Digitalmars-d wrote:
[...]

 I do agree that the macros defined in the site's .ddoc files are
 ridiculously overlapping, redundant, etc. That all could use a
 redesign and an overhaul, but that isn't Ddoc's fault. It's just like
 any piece of crap code that has suffered from too many quick&dirty
 hacks layered on to it.


I think you hit the nail on the head. The current dlang.org macros are a
gigantic, inconsistent mess. I think some serious refactoring is in
order here.


T

-- 
MACINTOSH: Most Applications Crash, If Not, The Operating System Hangs
Dec 16 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-12-16 21:54, Walter Bright wrote:


 I'm not so sure. There are lots of tools to develop websites. Let's say
 A, B, and C. If we picked "B", we most assuredly would have analogous
 threads here saying "I won't use anything but A" and "Everybody else
 uses C."


Anything that is explicitly created for web development would be better.


 I've heard all sorts of excuses for decades about why people won't chip
 in, and I know they are excuses because when the excuse is fixed, they
 still won't chip in. This excuse sounds the same as the rest.

 The thing is, if you know html, then you know Ddoc. Ddoc is just a
 stupidly simple text-substitution macro system a programmer should be
 able to learn in a few minutes.


I know HTML, and I know there's no problem with underscores in HTML. Yet 
Ddoc is causing issues with underscores because Latex is used to 
generate the PDF [1].

[1] http://forum.dlang.org/post/n4tpdd$2kun$1 digitalmars.com

-- 
/Jacob Carlborg
Dec 17 2015
prev sibling next sibling parent reply anonymous <anonymous example.com> writes:
On 15.12.2015 08:07, deadalnix wrote:

 The navigation can get very confusing. The forum and the site look the
 same, but the logo in the top right bring back to the site index/forum
 index . That is not what is expected. If it looks the same, it should
 probably be doing the same.


Agreed. And the phobos pages have yet another navigation variant that 
looks similar but has different elements.


 On the website, the forum is hidden in the community menu in the middle
 of the left bar called community. If it warrant its own domain name, it
 should probably not be hidden.


The accordion menus have been introduced somewhat recently (early 2015 
IIRC) to make the menu more structured, less crowded. Recently, a number 
of things have been suggested to be put at the top level. The problem 
is, if we put everything at the top level, we end up with an overcrowded 
menu again.

Not saying that the forum shouldn't be at the top. But if we move it up, 
we should probably move something else down.


 On the website, categories in the left bar, there are
 + and - sign that looks like button to open/close the category, but they
 aren't button. It breaks common expectations.


Not sure what you're asking for here. The +/- signs are part of a button 
that expands/collapses the sub menus. What behavior would you expect/prefer?


 There is no way to search the spec.


Is implemented and merged. The site just hasn't been updated yet.

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


 Home page:


[...]

 Our is just messed up. The download link is there, but just doesn't
 stand out (same presentation as this week in D, videos from DConf, as
 big as the changelog).


I agree, others don't. See discussion on 
<https://github.com/D-Programming-Language/dlang.org/pull/1139> where I 
originally proposed this download button: 
<https://cloud.githubusercontent.com/assets/9287500/10711239/4fb76968-7a75-11e5-8677-8a27eebdc952.png>.

Now, I don't want to complain about people not liking the design. And I 
pulled the design changes back rather quickly, because the functionality 
was supposed to be the subject of the PR. A big, flashy download button 
has not exactly been rejected.
Dec 15 2015
parent reply deadalnix <deadalnix gmail.com> writes:
On Tuesday, 15 December 2015 at 11:13:51 UTC, anonymous wrote:

 I agree, others don't. See discussion on 
 <https://github.com/D-Programming-Language/dlang.org/pull/1139> 
 where I originally proposed this download button: 
 <https://cloud.githubusercontent.com/assets/9287500/10711239/4fb76968-7a75-11e5-8677-8a27eebdc952.png>.

 Now, I don't want to complain about people not liking the 
 design. And I pulled the design changes back rather quickly, 
 because the functionality was supposed to be the subject of the 
 PR. A big, flashy download button has not exactly been rejected.


I get more and more irritated by how non factual the whole IT 
scene is. Why does it boils down to opinion ?

A good rule of thumb: if you can't notice and click on the button 
immediately while drunk, it is not big and obvious enough.

The proposed design is better that what we have now, but it is 
still clumsy. There are box into box, and way too much infos.

It is not opinion, it is what works. If one is of different 
opinion, there is an easy way to settle: do an A/B test and 
settle. I can tell you, on that one the result that would come 
out of this are fairly obvious.
Dec 15 2015
parent reply anonymous <anonymous example.com> writes:
On 15.12.2015 22:50, deadalnix wrote:

 I get more and more irritated by how non factual the whole IT scene is.
 Why does it boils down to opinion ?

 A good rule of thumb: if you can't notice and click on the button
 immediately while drunk, it is not big and obvious enough.

 The proposed design is better that what we have now, but it is still
 clumsy. There are box into box, and way too much infos.

 It is not opinion, it is what works. If one is of different opinion,
 there is an easy way to settle: do an A/B test and settle. I can tell
 you, on that one the result that would come out of this are fairly obvious.


What "works" means is still debatable. Is it a goal to get users to the 
download quickly, or are other things equally or more important?

Also, we don't really have the resources to do studies on these things, 
do we? So when you say that it's obviously this way and someone else 
says it's obviously that way, we're back to opinions.

Also, to reiterate, a more noticeable download button is not off the 
table. I pulled back all style changes in that PR to focus on the 
functionality first (which I kinda gave up on by now, too, because it 
turned out to be more difficult than I had hoped).
Dec 15 2015
parent deadalnix <deadalnix gmail.com> writes:
On Tuesday, 15 December 2015 at 22:17:33 UTC, anonymous wrote:

 What "works" means is still debatable. Is it a goal to get 
 users to the download quickly, or are other things equally or 
 more important?


Download is the first step in your tunnel. If one can't get to 
the download step, one can't use D. And if one can't use D, one 
doesn't care about everything else on the website.


 Also, we don't really have the resources to do studies on these 
 things, do we? So when you say that it's obviously this way and 
 someone else says it's obviously that way, we're back to 
 opinions.


Ignoring metrics is always more expensive. Also, I'm not stating 
opinion and preference here. Personally, I don't care about the 
download button, I already downloaded things. But that's a 
classic tunnel optimization.


 Also, to reiterate, a more noticeable download button is not 
 off the table. I pulled back all style changes in that PR to 
 focus on the functionality first (which I kinda gave up on by 
 now, too, because it turned out to be more difficult than I had 
 hoped).
Dec 15 2015
prev sibling next sibling parent dnewbie <d d.com> writes:
On Tuesday, 15 December 2015 at 07:07:23 UTC, deadalnix wrote:

 Navigation:

 The navigation can get very confusing. The forum and the site 
 look the same, but the logo in the top right bring back to the 
 site index/forum index .


I thought that only I had saw this. Yes it's wrong. To go to 
homepage from the forum you need to look at the bottom (D Home 
link), for me this is very wrong and certainly not the standard 
for most sites.

I really think that D "heads" should hire a webdesigner!

Ron.
Dec 15 2015
prev sibling next sibling parent reply Wyatt <wyatt.epp gmail.com> writes:
On Tuesday, 15 December 2015 at 07:07:23 UTC, deadalnix wrote:

 Home page:

 This is a mess. There is way too much here. There is an 
 attention budget and it is important to manage it well.


I think you're overstating it: it's a bit busy, but I think it 
can be fixed.


 The usual for a programming language goes as follow :
  - Logo, color as per branding.


Yeah, we should probably incorporate the red more.


  - Language name, quick blurb about what it is, usually ending 
 with a link to tutorial.


We have the language name twice!  Do we need a longer blurb?  
None of your examples seem to link to an official tutorial at 
all, so we're ahead of the game there. (Sort of.  It's on a 
different domain and doesn't match "D style".)


  - Big fat download button.


It's right in the middle of the page.  Should we wrap it in 
<blink> to make it more obvious? (Seriously: I agree it should be 
bigger.  Changelog link smaller and underneath instead.)


  - Some sample code. The one we have on the front page is way 
 too big. It should be a piece of code that someone with 0 
 experience in the language can understand.


The RPN example is too big.  The sort lines example is nice.  Is 
there some sort of rotation here?  Go kinda gets it right with 
the dropdown.  Scala's tiles are poorly telegraphed.


  - A menu with quick access to what more experienced users want 
 : stdlib reference, code repository, wiki, forum, language 
 spec, news, this kind of thing.


So, the stuff on the sidebar?


 Some examples:
 http://www.scala-lang.org/


Well, I guess it's pretty?  Examples aren't obvious and the 
documentation uses a completely different colour scheme for 
Reasons(?).


 https://nodejs.org/en/


Thoroughly useless bootstrap placeholder.


 https://developer.apple.com/swift/


What on earth?  There's no download at all, no obvious doc link, 
way too much verticality, and they've overdone it on the 
whitespace.  I guess they only care about people with high-dollar 
Apple screens.


 https://golang.org/


Ugly but functional.  Decent layout, though I still don't get 
this fetish for top links.


 https://www.rust-lang.org/


Slightly better than Go.  Could we stop pretending 1024x768 is 
The Best Resolution?


 Last but not least, it wouldn't hurt to hire a designer to have 
 something slick.


I think the biggest issues are the sidebar cleanliness and the 
main content having a single-column design.  I like the _idea_ of 
having the discussion boxouts in the right column, but it comes 
at the expense of the rest of the content and contributes to the 
fatigue.

-Wyatt
Dec 15 2015
parent deadalnix <deadalnix gmail.com> writes:
On Tuesday, 15 December 2015 at 16:15:49 UTC, Wyatt wrote:

 On Tuesday, 15 December 2015 at 07:07:23 UTC, deadalnix wrote:

 Home page:

 This is a mess. There is way too much here. There is an 
 attention budget and it is important to manage it well.


 I think you're overstating it: it's a bit busy, but I think it 
 can be fixed.


I work in growth, I've seen numbers.
Dec 15 2015
prev sibling parent Pradeep Gowda <pradeep btbytes.com> writes:
On Tuesday, 15 December 2015 at 07:07:23 UTC, deadalnix wrote:


 The usual for a programming language goes as follow :
  - Logo, color as per branding.
  - Language name, quick blurb about what it is, usually ending 
 with a link to tutorial.
  - Big fat download button.
  - Some sample code. The one we have on the front page is way 
 too big. It should be a piece of code that someone with 0 
 experience in the language can understand.
  - A menu with quick access to what more experienced users want 
 : stdlib reference, code repository, wiki, forum, language 
 spec, news, this kind of thing.


1. https://www.python.org/
2. https://www.ruby-lang.org/en/

I think the above two websites do a better job of fitting your 
requirements than Scala's homepage etc., Let not the dynamic 
typed nature of the language(s) dissuade you from learning how to 
build a very popular language **community**.
Dec 15 2015