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: http://dlang.org/phobos/std_parallelism.html#.Task 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: http://dlang.org/phobos/std_parallelism.html#.Task 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. http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
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.
 
 http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
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.
 
 http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
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
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 Snke 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 Snke 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 Snke 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/phobos-prerelease/core_memory.html#.GC.malloc 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