Why I'm hesitating to switch to D

[James Fisher]

I'm a casual follower of development on D. In my opinion, it's the
cleanest, most complete multi-paradigm language currently out there -- from
what I can see, I would describe the language as *done*. However, I, like
many others, am not switching to it. Why? Because a perfect language does
not a perfect development environment make: everything *surrounding* the
language is a complete mess. Here's my non-comprehensive laundry list in
the hope it's useful to someone.


*# Package management*

This one's *really* important. The front page of
digitalmars.org/d/describes it as having "... the programmer
productivity of modern languages
like Ruby and Python". The language, maybe, but this statement is
absolutely not true while there is no associated package manager.

I've followed the "two standard libraries" debacle with some confusion (I'm
still not clear what's being done about it). But this isn't actually that
important, and D needs to learn from other languages/platforms (Python pip,
Ruby gems, NodeJS npm, Go goinstall, Haskell cabal, etc.) that a massive
"batteries included" standard library is no substitute for a world-class
package manager. IMO the big-standard-library is a slightly outdated
concept in an age where we're always able to pull stuff from the net in an
instant. A big stdlib means a big platform installation, no matter the size
of the task, and yet no stdlib can be so big as to satisfy all needs.

The productivity gain that comes from being able to execute "dinstall
<somepackage>", and then having it magically available, is *immense*. When
I need to get a job done, I'll often choose an inferior manager-installable
library over a superior one where I have to hunt it out, download the
tar.gz, read the README, make, make install, realise dependencies are
missing, install them too, then fix everything that's broken. Having a
package manager is also crucial to getting people to bother sharing their
code with others.

The closest thing to a central repository seems to be
http://www.dsource.org/. But this is all wrong. People don't want to use a
language-specific site to host their project under SVN. They want to use
GitHub/Bitbucket/Google code/etc. Dsource.org should just maintain a list
of packages for an installer -- say, like http://search.npmjs.org/. That D
projects are hosted on a D-exclusive site tells me that D has a closed
community.

Yet D has a working module and package system, so a working package manager
should be a small task!


*# Community fragmentation*

Where is the D community? I see:

http://www.digitalmars.com/d/ -- seems to be official
http://www.d-programming-language.org/ -- also seems to be official!

I would guess that d-programming-language.org is meant to deprecate the
digitalmars page, but there's no statement to that effect on either site.

There's a whole host of other sites that seem to have spawned, I guess
because whatever *is* the official center is unsatisfactory:

http://www.dprogramming.com/
http://www.dsource.org/
etc.

Some real effort has to go into rounding up the herd. (The move to git and
GitHub is an excellent one in this regard.)


*# It's unsearchable!*

This one is really trivial. There's an important reason that other
languages have squiffy names: searchability. Googling for "d <query>" is
useless, and "d language <query>" is still awful. Other languages that
suffer from the same affliction have the convention of appending "lang" as a
suffix -- "golang", for example -- and this works well. It seems that
"dlang" has not caught on. I see there's a site at http://dlang.org/ (yes,
yet another one!). Whois says it's owned by http://oscarbrynolf.com/. The
(seemingly recent?) move to GitHub and new website would have been a chance
to get this right. Prepending "d programming language" to every search I
make is still absolutely horrible.


*# No marketing or brand awareness*

OK, I can live with this. But make no mistake: it *does* seriously cut down
on the people migrating to it. Take a look at the "free images" offered at
http://digitalmars.com/d/dlinks.html -- this is a marketers nightmare! That
list *literally* makes me shudder. I'm not saying that D requires another
generic Web 2.0 HTML5 look with gradients and rounded corners that one sees
on the latest fashionable projects. I *am* saying that it needs something
consistent and clean, and currently it, seemingly willfully, has neither.
(BTW, I've done some web design work before, e.g. http://hsk.org.uk/ -- I'd
be willing to help out.)

For comparative illustration:

http://python.org/ -- clean, no showiness.
http://www.ruby-lang.org/en/ -- a bit busy, but consistent.
http://golang.org/ -- very clean, well organized.
http://haskell.org/ <http://haskell.org/haskellwiki/Haskell>


The point I want to get across here is: the problem with the D programming
language *is not that there are problems with the D programming language.*
The language and compiler (from what I know) have been world-class for some
time. I've seen a few conversations where people using D get quite
indignant that people are interested in Go, Rust, etc. D is not getting new
users because it doesn't look like it *wants* new users: it dresses
sloppily, it doesn't make itself findable easily, and it doesn't have
infrastructure for new users to share and benefit from sharing.


James Fisher
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110628/613f8a51/attachment-0001.html>

[Andrej Mitrovic]

All of your problems are solvable by getting more people involved in
contributing to D. And, as far as I can tell, the existing
contributors are working at their 100% capacity even though they might
not have enough free time for themselves.

Things are improving for D, it just needs more time and more contributors.

[David Gileadi]

Post by James Fisher
I *am* saying
that it needs something consistent and clean, and currently it,
seemingly willfully, has neither. (BTW, I've done some web design work
before, e.g. http://hsk.org.uk/ -- I'd be willing to help out.)

I've done a little web design too, although it's definitely not my
strong suit. I quite like the look of the site you posted; you seem to
be pretty good at it.

I felt largely the same as you about how the D language presents itself,
which prompted me to offer to help with the site design. The design
that ended up at d-programming-language.org grew out of that.

I'm sure that any help and improvements you'd like to contribute would
be welcomed.

[Walter Bright]

Thanks for taking the time to do a detailed writeup on your opinions. I think
it's great feedback.

1. We all (well, almost all) agree on the need for a package manager. There are
some recent threads on getting this going.

2. The "two standard libraries" debacle it pretty much in the past now. D2 going
forward has one standard library, Phobos.

3. For searching, I recommend "D programming" with the quotes. It works pretty
good in google. I also harangue people who write about D to include the phrase
"D programming language" at least once on their pages. This helps a lot. On
twitter we use #d_lang to tie things together.

4. The official website for D is now http://www.d-programming-language.org.

5. I know I suck at web site design, which is why David Gileadi helped us out by
designing the d-programming-language.org look & feel.

6. The dlinks page is ancient, and it's been a long time since I even looked at
it. I agree it needs a revamp.

7. The d-programming-language.org site is on github - this means that you can
create pull requests for it! Please do for anything specific you can contribute to.

[James Fisher]

On Tue, Jun 28, 2011 at 10:09 PM, Walter Bright

Post by Walter Bright
Thanks for taking the time to do a detailed writeup on your opinions. I
think it's great feedback.

Well, thanks!

1. We all (well, almost all) agree on the need for a package manager. There

Post by Walter Bright
are some recent threads on getting this going.

Ah. Is this<http://www.digitalmars.com/d/archives/digitalmars/D/More_on_the_necessity_and_difficulty_of_a_package_management_system_127873.html>the
main thread you mean?

Post by Walter Bright
2. The "two standard libraries" debacle it pretty much in the past now. D2
going forward has one standard library, Phobos.

Fair enough. Though the site at http://www.dsource.org/projects/tango gives
no indication of that and still evangelizes migration from Phobos to Tango.
Are there people that would disagree with your assessment?

3. For searching, I recommend "D programming" with the quotes. It works

Post by Walter Bright
pretty good in google. I also harangue people who write about D to include
the phrase "D programming language" at least once on their pages. This helps
a lot. On twitter we use #d_lang to tie things together.

K.

4. The official website for D is now
http://www.d-programming-**language.org<http://www.d-programming-language.org>

Post by Walter Bright
.

An odd thing about it is that one might mistake it for a companion site to
Andrei's book, having the same name and the front page devoted to it. Is
this intentional? Perhaps the plan is to host the book, in a
read-it-free-online-or-buy-the-book scheme, like the amazing Real World
Haskell<http://book.realworldhaskell.org/read/why-functional-programming-why-haskell.html>?
(That would be an incredibly strong resource.) Is Andrei's book an
official part of the D project?

Post by Walter Bright
5. I know I suck at web site design

No offense meant!

6. The dlinks page is ancient, and it's been a long time since I even looked

Post by Walter Bright
at it. I agree it needs a revamp.
7. The d-programming-language.org site is on github - this means that you
can create pull requests for it! Please do for anything specific you can
contribute to.

I'd love to. Is the content of digitalmars.com/d now frozen; is the
intention to replace it with a redirect once content is migrated?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110628/699828f8/attachment.html>

[Jimmy Cao]

Though the site at http://www.dsource.org/projects/tango gives no
indication of that and still evangelizes migration from Phobos to Tango.
Are there people that would disagree with your assessment?

The tango homepage will never say something like, "D1/Tango is dead,
everyone migrate to Phobos!" If you look at the history of D, back in 2006
or 2007 when the system for requesting improvements and bugfixes was rather
messy and Phobos was increasingly incompetent as a standard library, part of
the community decided to work on replacing Phobos and make a better library
for the community and driven by the community. So that was how the Tango
community started, and that community stayed with D1 when D2 was released.

Both communities exist today, I guess, but the D2/Phobos community has grown
the most, and D1/Tango community has shrunken (it's been years, the fact
that there are still some D1/Tango users means that Tango really is a fine
library). Phobos has improved ,also, and the transition to github has
helped it a lot. Your best bet is Phobos - its development is very active,
and it is poised to clearly become the best standard library.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110628/296e6072/attachment-0001.html>

[Nick Sabalausky]

"Jimmy Cao" <jcao219 at gmail.com> wrote in message

On Tue, Jun 28, 2011 at 5:49 PM, James Fisher

Though the site at http://www.dsource.org/projects/tango gives no
indication of that and still evangelizes migration from Phobos to Tango.
Are there people that would disagree with your assessment?

The tango homepage will never say something like, "D1/Tango is dead,
everyone migrate to Phobos!" If you look at the history of D, back in
2006
or 2007 when the system for requesting improvements and bugfixes was
rather
messy and Phobos was increasingly incompetent as a standard library, part
of
the community decided to work on replacing Phobos and make a better
library
for the community and driven by the community. So that was how the Tango
community started, and that community stayed with D1 when D2 was released.
Both communities exist today, I guess, but the D2/Phobos community has
grown
the most, and D1/Tango community has shrunken (it's been years, the fact
that there are still some D1/Tango users means that Tango really is a fine
library). Phobos has improved ,also, and the transition to github has
helped it a lot. Your best bet is Phobos - its development is very
active,
and it is poised to clearly become the best standard library.

And even if Tango does get ported to D2 (As I've heard some people are
working on), it'll most likely be a suppliment to Phobos, rather than the
"one or the other" issue it was on D1. (That's what druntime is for.)

[James Fisher]

Post by Nick Sabalausky
"Jimmy Cao" <jcao219 at gmail.com> wrote in message

On Tue, Jun 28, 2011 at 5:49 PM, James Fisher

Though the site at http://www.dsource.org/projects/tango gives no
indication of that and still evangelizes migration from Phobos to Tango.
Are there people that would disagree with your assessment?

The tango homepage will never say something like, "D1/Tango is dead,
everyone migrate to Phobos!" If you look at the history of D, back in
2006
or 2007 when the system for requesting improvements and bugfixes was
rather
messy and Phobos was increasingly incompetent as a standard library, part
of
the community decided to work on replacing Phobos and make a better
library
for the community and driven by the community. So that was how the Tango
community started, and that community stayed with D1 when D2 was

released.

Both communities exist today, I guess, but the D2/Phobos community has
grown
the most, and D1/Tango community has shrunken (it's been years, the fact
that there are still some D1/Tango users means that Tango really is a

fine

library). Phobos has improved ,also, and the transition to github has
helped it a lot. Your best bet is Phobos - its development is very
active,
and it is poised to clearly become the best standard library.

And even if Tango does get ported to D2 (As I've heard some people are
working on), it'll most likely be a suppliment to Phobos, rather than the
"one or the other" issue it was on D1. (That's what druntime is for.)

OK.

1. One of the most pleasingly surprising tech stories I've heard for years
was the merging of Rails and
Merb<http://weblog.rubyonrails.org/2008/12/23/merb-gets-merged-into-rails-3>,
two large separate Ruby web frameworks with the same problem domain. It was
surprising because in the OSS world there's a nasty habit of all projects
being a fork of something else, almost never a merge of two previous
projects. I figure all it took was some strong discussion. BTW, the choice
of stdlib is not obvious to the new user of the language, and the "just let
it die" attitude makes things confusing. This SO question from
09<http://stackoverflow.com/questions/693672/d-standard-library> (was
the choice considered a non-issue then?) for instance recommends Tango.

2. I suppose, once a package manager is in place, this issue will fade as
Tango can be meted out into smaller packages.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/79ed5d9a/attachment.html>

[Lars T. Kyllingstad]

BTW, the choice of stdlib is not obvious to the new user of the
language, and the "just let it die" attitude makes things confusing.
This SO question from
09<http://stackoverflow.com/questions/693672/d-standard-library> (was
the choice considered a non-issue then?) for instance recommends Tango.

It is unfortunate that this is still confusing new D users, because the
choice is really simple:

If you want to use D1, use Tango.
If you want to use D2, use Phobos.

(That said, why anyone would still want to use D1 is beyond me.)

-Lars

[Trass3r]

Post by James Fisher
On Tue, Jun 28, 2011 at 10:09 PM, Walter Bright

Post by Walter Bright
2. The "two standard libraries" debacle it pretty much in the past now.
D2
going forward has one standard library, Phobos.

Fair enough. Though the site at http://www.dsource.org/projects/tango
gives
no indication of that and still evangelizes migration from Phobos to
Tango.
Are there people that would disagree with your assessment?

Well the problem has indeed been solved in D2 by splitting the runtime
from the standard library. In fact the Tango runtime was adapted to be
used as a new common druntime.
But most of the Tango guys just can't seem to get along with D2 and thus
pursue their own goals now.
So there's only one std lib right now. Someone is trying to port Tango to
D2 though.

[Jacob Carlborg]

Post by Walter Bright
5. I know I suck at web site design, which is why David Gileadi helped
us out by designing the d-programming-language.org look & feel.

I think it makes it hard when most of the pages are written in DDOC. It
doesn't help to attract web designers.

[Walter Bright]

I think it makes it hard when most of the pages are written in DDOC. It doesn't
help to attract web designers.

I have no idea what professional web designers use, but I did many web pages
using html in a regular text editor.

It was awful.

Using Ddoc literally doubled my productivity at creating web pages. Furthermore,
I can easily change them. This came in really handy when David redid the look &
feel.

For example, I am able to create the C++ manuals for the Kindle and the
digitalmars.com web pages from the exact same source text, simply by using a
different set of .ddoc macros.

(Although you can supposedly convert html directly to Kindle books, in reality
you'll discover you need to put out different html than you would for web display.)

[James Fisher]

On Wed, Jun 29, 2011 at 9:29 AM, Walter Bright

Post by Walter Bright

I think it makes it hard when most of the pages are written in DDOC. It doesn't
help to attract web designers.

I have no idea what professional web designers use, but I did many web
pages using html in a regular text editor.
It was awful.

I agree that HTML isn't great to work with directly. Even in the realm of
small static sites, the general movement is towards treating HTML as a
presentation format. If one wants a more convenient, non-semantic wrapper
over it, we have things like HAML <http://haml-lang.com/>,
Jade<http://haml-lang.com/>,
and a million other things.

Using Ddoc literally doubled my productivity at creating web pages.

Post by Walter Bright
Furthermore, I can easily change them. This came in really handy when David
redid the look & feel.
For example, I am able to create the C++ manuals for the Kindle and the
digitalmars.com web pages from the exact same source text, simply by using
a different set of .ddoc macros.
(Although you can supposedly convert html directly to Kindle books, in
reality you'll discover you need to put out different html than you would
for web display.)

I respect that it increased your personal productivity. What's worth
questioning is whether it increases the productivity of the growing
community as a whole.

I don't aim to proselytize one mini-language over another, as they're much
of a muchness. But I'd hope to convince people that:

- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats are one
area where Might Is Right.
- The documentation and the D website are separate problems and shouldn't
be conflated. Many other languages take the approach of separating them and
putting documentation in a subsite (e.g.
http://doc.d-programming-language.org/). X-site coherence can be
maintained with pretty much just CSS. As we all know, dividing the problem
is the first step to conquering it.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/5ab745af/attachment.html>

[Adam Richardson]

On Wed, Jun 29, 2011 at 4:29 AM, Walter Bright

Post by Walter Bright

I think it makes it hard when most of the pages are written in DDOC. It doesn't
help to attract web designers.

I have no idea what professional web designers use, but I did many web
pages using html in a regular text editor.
It was awful.
Using Ddoc literally doubled my productivity at creating web pages.
Furthermore, I can easily change them. This came in really handy when David
redid the look & feel.

HTML is a fantastic for crafting web pages (and many web developers have
IDE's that facilitate the process, although even a tool like text wrangler
is pretty handy.) The semantics of HTML (HTML5, microformats, WAI-ARIA,
RDFa, etc) are very rich and growing.

Using ddoc to automatically generate documentation for the API content
within the site seems wise. However, using ddoc for the entire website does
present some challenges.

I'll admit that I looked through to see what I could help out with on the
website, but ddoc stopped me in my tracks. I'll take time to learn how to
use D to build my next web framework, because D seems like a great tool for
the job. However, I'd rather not take the time to learn how to turn build
websites with ddoc, as it's just not built for web site development.

That said, David has shown that you can make great progress with just ddoc
(really, David, you've done fantastic work.)

Adam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/39d02f7b/attachment.html>

[Jacob Carlborg]

Post by Walter Bright

I think it makes it hard when most of the pages are written in DDOC. It doesn't
help to attract web designers.

I have no idea what professional web designers use, but I did many web
pages using html in a regular text editor.
It was awful.

That *is* awful. I use Ruby on Rails with the following languages (and
what they compile to):

HAML -> HTML
SASS -> CSS
CoffeeScript -> JavaScript

And Ruby of course.

Post by Walter Bright
Using Ddoc literally doubled my productivity at creating web pages.
Furthermore, I can easily change them. This came in really handy when
David redid the look & feel.
For example, I am able to create the C++ manuals for the Kindle and the
digitalmars.com web pages from the exact same source text, simply by
using a different set of .ddoc macros.
(Although you can supposedly convert html directly to Kindle books, in
reality you'll discover you need to put out different html than you
would for web display.)

I would say DDoc is good for writing documentation but not for web pages.

[Walter Bright]

That *is* awful. I use Ruby on Rails with the following languages (and what they
HAML -> HTML
SASS -> CSS
CoffeeScript -> JavaScript
And Ruby of course.

Are you recommending that people who want to contribute to D documentation need
to learn Ruby on Rails?

I would say DDoc is good for writing documentation but not for web pages.

Why not? I use it for hundreds of web pages.

[Jacob Carlborg]

Post by Walter Bright

That *is* awful. I use Ruby on Rails with the following languages (and what they
HAML -> HTML
SASS -> CSS
CoffeeScript -> JavaScript
And Ruby of course.

Are you recommending that people who want to contribute to D
documentation need to learn Ruby on Rails?

Your saying you don't know that language(s) web developers use, I'm
saying that I use Ruby on Rails. If the page would be written in Ruby on
Rails then there would most likely be forms you can enter some kind of
structured text in, like Textile or Markdown. You don't have to know
Ruby on Rails just to add a new paragraph in an already existing page.

Post by Walter Bright

I would say DDoc is good for writing documentation but not for web pages.

Why not? I use it for hundreds of web pages.

I don't know what kind of web pages you create but I need something more
than ddoc or html, something more than a simple markup language,
something with if-statements. When you need to store something in a
database you most likely will need a server side script.

[Nick Sabalausky]

"Jacob Carlborg" <doob at me.com> wrote in message

Post by Jacob Carlborg

Post by Walter Bright

I think it makes it hard when most of the pages are written in DDOC. It doesn't
help to attract web designers.

I have no idea what professional web designers use, but I did many web
pages using html in a regular text editor.
It was awful.

That *is* awful. I use Ruby on Rails with the following languages (and
HAML -> HTML
SASS -> CSS
CoffeeScript -> JavaScript
And Ruby of course.

I wouldn't mind switching to some "compile down to HTML/CSS/etc" thing, but
all the mature ones I've seen seem to place a strong emphasis on
whitespace-syntax which is something I can't stand. YAML's about the only
place I can really tolerate it (at least in large part because it's purely
optional, and because it's purely a data language (but then, so are HTML and
CSS)). And then there's some other rediculous thing CoffeeScript does...umm,
IIRC, I think it's implicit declarations.

[Jacob Carlborg]

"Jacob Carlborg"<doob at me.com> wrote in message

Post by Jacob Carlborg

Post by Walter Bright

I think it makes it hard when most of the pages are written in DDOC. It doesn't
help to attract web designers.

I have no idea what professional web designers use, but I did many web
pages using html in a regular text editor.
It was awful.

That *is* awful. I use Ruby on Rails with the following languages (and
HAML -> HTML
SASS -> CSS
CoffeeScript -> JavaScript
And Ruby of course.

I wouldn't mind switching to some "compile down to HTML/CSS/etc" thing, but
all the mature ones I've seen seem to place a strong emphasis on
whitespace-syntax which is something I can't stand. YAML's about the only
place I can really tolerate it (at least in large part because it's purely
optional, and because it's purely a data language (but then, so are HTML and
CSS)). And then there's some other rediculous thing CoffeeScript does...umm,
IIRC, I think it's implicit declarations.

All of the above languages (except Ruby) use indentation for scopes.
"implicit declarations" do you mean that you don't have to declare a
variable before you use it? In that case, Ruby has that as well.
Comparing, for example, HAML and HTML, I think that HAML looks cleaner
than HTML.

Anyway, I like them. First I didn't either like whitespace aware
languages but in these cases I like it. But I would never want it in D.

[Walter Bright]

Post by Adam Richardson
I'll admit that I looked through to see what I could help out with on the
website, but ddoc stopped me in my tracks.

How did it stop you?

Post by Adam Richardson
it's just not built for web site development.

Anything you can do in HTML, you can do in Ddoc.

Post by Adam Richardson
That said, David has shown that you can make great progress with just ddoc
(really, David, you've done fantastic work.)

I am not aware of any issue with Ddoc that impaired David's work.

[Robert Clipsham]

Post by Walter Bright

Post by Adam Richardson
I'll admit that I looked through to see what I could help out with on the
website, but ddoc stopped me in my tracks.

How did it stop you?

DDoc vs Markdown:
* Pretty much everyone who uses github, stackoverflow, and many other
sites knows some amount of markdown
* I've been using D for years and I pride myself on not knowing the
hideous DDoc beyond "Params: Example:" etc.
* DDoc macros make even the simplest things ugly

Code:

DDoc:
$(LINK http://my.url/)
$(LINK2 http://my.url/, My URL)

Markdown:
http://my.url/
[My URL](http://my.url)

DDoc:
$(UL
$(LI $(LINK2 http://a/, A))
$(LI Nesting
$(UL
$(LI I daren't go another layer deeper $(LPAREN)$(LINK2
http://b/, honestly)$(RPAREN)
)
)
)
)
Markdown:
* [A](http://a/)
* Nesting
- I could go deeper with this without it being hideous
+ (No really http://foo.bar/)
+ I could just keep going
* [and it's still not ugly](http://b/)


Another bonus of markdown: It (or a subset of it) could probably be
added to ddoc without much effort given its simplicity, without breaking
anything. Seems like a no-brainer to me.

PS: I probably missed some parenthesis in the DDoc version. That's not
intentional, that just comes from DDoc macros being hideous and just
generally terrible.

[Walter Bright]

Post by Walter Bright
How did it stop you?

* Pretty much everyone who uses github, stackoverflow, and many other sites
knows some amount of markdown
* I've been using D for years and I pride myself on not knowing the hideous DDoc
beyond "Params: Example:" etc.

It was deliberately designed so you didn't actually have to know it in order to
generate fairly reasonable documentation for functions.

* DDoc macros make even the simplest things ugly
$(LINK http://my.url/)
$(LINK2 http://my.url/, My URL)
http://my.url/

I agree, that's better. That would be a nice improvement to Ddoc.

[My URL](http://my.url)

I'm familiar with that from reddit, but I confess to always having to look it up
first as I never can remember which part goes where :-). But what about the
other kinds of links, such as GLINK, which Ddoc makes easy? For example, I use a
macro for links that I redefine in order to make them intrapage links for
generating an ebook and interpage links for the web site. With a non-macro
system, I'm faced with editting all the links.

$(UL
$(LI $(LINK2 http://a/, A))
$(LI Nesting
$(UL
$(LI I daren't go another layer deeper $(LPAREN)$(LINK2 http://b/,
honestly)$(RPAREN)
)
)
)
)

You don't need the $(LPAREN) and $(RPAREN) unless they are not paired. You don't
need them in your example.

* [A](http://a/)
* Nesting
- I could go deeper with this without it being hideous
+ (No really http://foo.bar/)
+ I could just keep going
* [and it's still not ugly](http://b/)

It looks nice, but I think it only works if the items fit on one line.

Another bonus of markdown: It (or a subset of it) could probably be added to
ddoc without much effort given its simplicity, without breaking anything. Seems
like a no-brainer to me.

Not a bad idea.

PS: I probably missed some parenthesis in the DDoc version. That's not
intentional, that just comes from DDoc macros being hideous and just generally
terrible.

You can define your own macros in Ddoc. I do that frequently for repetitive
custom work on an individual page.

[Robert Clipsham]

Post by Walter Bright

Post by Walter Bright
How did it stop you?

* Pretty much everyone who uses github, stackoverflow, and many other sites
knows some amount of markdown
* I've been using D for years and I pride myself on not knowing the hideous DDoc
beyond "Params: Example:" etc.

It was deliberately designed so you didn't actually have to know it in
order to generate fairly reasonable documentation for functions.

I'm just glad it ditched the horrible @params: etc nonsense that every
other documentation system seems to have its heart set on.

Post by Walter Bright

* DDoc macros make even the simplest things ugly
$(LINK http://my.url/)
$(LINK2 http://my.url/, My URL)
http://my.url/

I agree, that's better. That would be a nice improvement to Ddoc.

[My URL](http://my.url)

I'm familiar with that from reddit, but I confess to always having to
look it up first as I never can remember which part goes where :-). But
what about the other kinds of links, such as GLINK, which Ddoc makes
easy? For example, I use a macro for links that I redefine in order to
make them intrapage links for generating an ebook and interpage links
for the web site. With a non-macro system, I'm faced with editting all
the links.

GLINK?

Post by Walter Bright

$(UL
$(LI $(LINK2 http://a/, A))
$(LI Nesting
$(UL
$(LI I daren't go another layer deeper $(LPAREN)$(LINK2 http://b/,
honestly)$(RPAREN)
)
)
)
)

You don't need the $(LPAREN) and $(RPAREN) unless they are not paired.
You don't need them in your example.

I didn't know this. Nor do I intend to!

Post by Walter Bright

* [A](http://a/)
* Nesting
- I could go deeper with this without it being hideous
+ (No really http://foo.bar/)
+ I could just keep going
* [and it's still not ugly](http://b/)

It looks nice, but I think it only works if the items fit on one line.

Whenever I've done it it's been fine with items spreading lines,
providing the whitespace is roughly right. Though I know you don't like
whitespace aware languages.

Post by Walter Bright

Another bonus of markdown: It (or a subset of it) could probably be added to
ddoc without much effort given its simplicity, without breaking anything. Seems
like a no-brainer to me.

Not a bad idea.

Should I open an enhancement request in bugzilla?

Post by Walter Bright

PS: I probably missed some parenthesis in the DDoc version. That's not
intentional, that just comes from DDoc macros being hideous and just generally
terrible.

You can define your own macros in Ddoc. I do that frequently for
repetitive custom work on an individual page.

That wouldn't particularly help the above example though. And
regardless, macros are ugly :D

[Walter Bright]

Post by Robert Clipsham
documentation system seems to have its heart set on.

That came from Javadoc. Yes, I hated it, too. I wanted the Ddoc function
documentation to not look like a markup language.

Post by Robert Clipsham
GLINK?

GLINK=$(LINK2 #$0, $(I $0))

Post by Robert Clipsham

Post by Walter Bright

Post by Robert Clipsham
* [A](http://a/)
* Nesting
- I could go deeper with this without it being hideous
+ (No really http://foo.bar/)
+ I could just keep going
* [and it's still not ugly](http://b/)

It looks nice, but I think it only works if the items fit on one line.

Whenever I've done it it's been fine with items spreading lines, providing the
whitespace is roughly right. Though I know you don't like whitespace aware
languages.

What happens if you want to add a class= attribute to the unordered list?

Post by Robert Clipsham
Should I open an enhancement request in bugzilla?

Sure.

[Adam Ruppe]

One thing I like about ddoc is how hands-off it is. You can put
almost any text inside it and it gets passed out unmolested. I think
the only character that gets disappeared or altered in ddoc is $.

So almost any language could be added as a post-processor to ddoc
without needing to modify anything.

[Walter Bright]

Post by Adam Ruppe
One thing I like about ddoc is how hands-off it is. You can put
almost any text inside it and it gets passed out unmolested. I think
the only character that gets disappeared or altered in ddoc is $.

The more special characters in the markup language, the more trouble you're
going to have. That's why Ddoc is pretty limited to $.

[Nick Sabalausky]

"Robert Clipsham" <robert at octarineparrot.com> wrote in message

Post by Walter Bright

Post by Adam Richardson
I'll admit that I looked through to see what I could help out with on the
website, but ddoc stopped me in my tracks.

How did it stop you?

I've used things like markdown and wiki...umm...that other markup with
"wiki" in the name...and whatever trac uses quite a bit. While there are a
few things about them I found convenient, overall I felt they were horribly
limited, constantly getting in the way and preventing me from doing what I
want to do, and do too much "magical" modification of what I type. I avoid
them and go for straight HTML/CSS whenever I have the opportunity. Not
saying DDoc's perfect (haven't really used it, to be honest), but I do know
it'll handle any HTML I could possibly want, so I'd *hate* to see a switch
to one of those damn "for the idiot masses" blog markups.

[Adam Richardson]

On Wed, Jun 29, 2011 at 2:14 PM, Walter Bright

Post by Walter Bright

Post by Adam Richardson
I'll admit that I looked through to see what I could help out with on the
website, but ddoc stopped me in my tracks.

How did it stop you?

I'm a web developer by trade, and ddoc, while nice for generating
documentation, is not as nice (relatively speaking) for managing a website.
I'd rather bring in elements of ddoc into an html site rather than try to
bring in the appropriate html into ddocs (that's not to say that D wouldn't
handle templating for the site, just that the site wouldn't be built on top
of ddoc.)

For example:

1. Use simple templating system written in D for site.
2. Pages within templating system are built using HTML, CSS, Javascript.
3. DDoc material that's pulled from D source is dynamically brought in to
the pages in the site using the templating system.

DDoc would be used, but not as the foundation for the site.

Post by Walter Bright
it's just not built for web site development.
Anything you can do in HTML, you can do in Ddoc.

This is true. That said, what does the "Anything you can do in X, you can do
in Y" prove regarding the efficacy of using ddoc as the primary tool for
managing the website?

For example, anything I can do in D I can also do in C (or assembly), but I
prefer not to use C merely because I can. I prefer to use D because you've
carefully crafted a systems programming language that provides many of the
functional programming features I value, whilst maintaining succinct, clear
syntax that affords great parsimony.

For the same reason, I would prefer not to manage a website using DDoc, but
rather use tools that are crafted specifically for the job and then augment
those tools with DDoc.

Adam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/68c6727c/attachment.html>

[Adam Ruppe]

Post by Adam Richardson
For the same reason, I would prefer not to manage a website using
DDoc, but rather use tools that are crafted specifically for the job
and then augment those tools with DDoc.

That's how the D website works, in practice.

The DDOC= macro in std.ddoc contains just plain HTML, into which
the generated documentation is entered.

It's not required to be html. Heck, the DDOC= can be blank except
for referencing the body.

ddoc's output is basically just a simple preprocessor for any text,
and it barely modifies it at all if you don't want it to.

[Walter Bright]

This is true. That said, what does the "Anything you can do in X, you can do in
Y" prove regarding the efficacy of using ddoc as the primary tool for managing
the website?

Of course not, but I've seen some markup systems that if you wanted something
that wasn't anticipated by the markup developer, you're out of luck.

[Nick Sabalausky]

"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
I don't aim to proselytize one mini-language over another, as they're much
- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats are
one
area where Might Is Right.

Popularity should *never* be a significant concern. That's how we end up
with complete shit like PHP becoming widespread.

[Adam Richardson]

Post by Nick Sabalausky
"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
I don't aim to proselytize one mini-language over another, as they're

much

Post by James Fisher
- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats

are

Post by James Fisher
one
area where Might Is Right.

Popularity should *never* be a significant concern. That's how we end up
with complete shit like PHP becoming widespread.

Easy :) While I wouldn't use PHP for systems programming, PHP is a solid
tool for building websites.

Adam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/ec387e57/attachment.html>

[Nick Sabalausky]

"Adam Richardson" <simpleshot at gmail.com> wrote in message

Post by Adam Richardson

Post by Nick Sabalausky
"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
I don't aim to proselytize one mini-language over another, as they're

much

Post by James Fisher
- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens
up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats

are

Post by James Fisher
one
area where Might Is Right.

Popularity should *never* be a significant concern. That's how we end up
with complete shit like PHP becoming widespread.

Easy :) While I wouldn't use PHP for systems programming, PHP is a solid
tool for building websites.

It's complete garbage for building websites. It's complete garbage for
*everything*. And I've dealt with PHP and PHP web apps a *lot*. I can't
think of a single other web-oriented tool or language that I wouldn't rather
build a website with than PHP. Even Classic-ASP with VBScript, absolutely
horrid as it is, is at least a somewhat *stable* target.

[Nick Sabalausky]

"Nick Sabalausky" <a at a.a> wrote in message

Post by Nick Sabalausky
"Adam Richardson" <simpleshot at gmail.com> wrote in message

Post by Adam Richardson

Post by Nick Sabalausky
"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
I don't aim to proselytize one mini-language over another, as they're

much

Post by James Fisher
- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens
up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats

are

Post by James Fisher
one
area where Might Is Right.

Popularity should *never* be a significant concern. That's how we end up
with complete shit like PHP becoming widespread.

Easy :) While I wouldn't use PHP for systems programming, PHP is a solid
tool for building websites.

It's complete garbage for building websites.

And there isn't a single damn thing about PHP that's remotely "stable".

Post by Nick Sabalausky
It's complete garbage for *everything*. And I've dealt with PHP and PHP
web apps a *lot*. I can't think of a single other web-oriented tool or
language that I wouldn't rather build a website with than PHP. Even
Classic-ASP with VBScript, absolutely horrid as it is, is at least a
somewhat *stable* target.

[Andrej Mitrovic]

I would agree that macros are a bit hard to read in ddoc. There's some
nice ideas in this thread.

Luckily I don't get to see garbage like this in D code:
/// <summary>
/// Required designer variable.
/// </summary>
private System.ComponentModel.Container components = null;

Really, you need XML tags to give me 3 words of information that I
could live without? It basically guarantees nobody will touch the
language without an XML processing IDE/editor. Maybe VIM/Emacs do have
XML processing built in so they can hide this thing, but a single '//'
would do just fine here, no? :)

[Jacob Carlborg]

Post by Andrej Mitrovic
I would agree that macros are a bit hard to read in ddoc. There's some
nice ideas in this thread.
///<summary>
/// Required designer variable.
///</summary>
private System.ComponentModel.Container components = null;
Really, you need XML tags to give me 3 words of information that I
could live without? It basically guarantees nobody will touch the
language without an XML processing IDE/editor. Maybe VIM/Emacs do have
XML processing built in so they can hide this thing, but a single '//'
would do just fine here, no? :)

Having XML in comments/documentation like that is just ridicules.

[Jacob Carlborg]

"Adam Richardson"<simpleshot at gmail.com> wrote in message

Post by Adam Richardson

"James Fisher"<jameshfisher at gmail.com> wrote in message

Post by James Fisher
I don't aim to proselytize one mini-language over another, as they're

much

Post by James Fisher
- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens
up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats

are

Post by James Fisher
one
area where Might Is Right.

Popularity should *never* be a significant concern. That's how we end up
with complete shit like PHP becoming widespread.

Easy :) While I wouldn't use PHP for systems programming, PHP is a solid
tool for building websites.

It's complete garbage for building websites. It's complete garbage for
*everything*. And I've dealt with PHP and PHP web apps a *lot*. I can't
think of a single other web-oriented tool or language that I wouldn't rather
build a website with than PHP. Even Classic-ASP with VBScript, absolutely
horrid as it is, is at least a somewhat *stable* target.

I wouldn't completely agree with that. I hate PHP as well but I would
choose PHP rather than Classic-ASP with VBScript.

[Nick Sabalausky]

"Jacob Carlborg" <doob at me.com> wrote in message

Post by Jacob Carlborg

"Adam Richardson"<simpleshot at gmail.com> wrote in message

Post by Adam Richardson

"James Fisher"<jameshfisher at gmail.com> wrote in message

Post by James Fisher
I don't aim to proselytize one mini-language over another, as they're

much

Post by James Fisher
- Besides required functionality, the key reason to choose one
markup/documentation/html-generating format is popularity. It opens
up
development to new users, frees up maintainers of old documentation
generators, and gives you new tools to use for free. Markup formats

are

Post by James Fisher
one
area where Might Is Right.

Popularity should *never* be a significant concern. That's how we end up
with complete shit like PHP becoming widespread.

Easy :) While I wouldn't use PHP for systems programming, PHP is a solid
tool for building websites.

It's complete garbage for building websites. It's complete garbage for
*everything*. And I've dealt with PHP and PHP web apps a *lot*. I can't
think of a single other web-oriented tool or language that I wouldn't rather
build a website with than PHP. Even Classic-ASP with VBScript, absolutely
horrid as it is, is at least a somewhat *stable* target.

I wouldn't completely agree with that. I hate PHP as well but I would
choose PHP rather than Classic-ASP with VBScript.

Well, to be fair, if I had to choose between PHP and Classic ASP/VBScript,
my choice would probably be to bash my head into a wall. Preferably brick.
It's not like I'd happily pick ASP.

[James Fisher]

Post by Jacob Carlborg

Post by Walter Bright
5. I know I suck at web site design, which is why David Gileadi helped
us out by designing the d-programming-language.org look & feel.

I think it makes it hard when most of the pages are written in DDOC. It
doesn't help to attract web designers.

I'd definitely agree with that. I have no experience with DDOC, but TBH I
don't intend to ever have any. As a general criticism of DDOC, it seems
like another reinvented wheel. Semi-plaintext formats surround us like the
plague, and for every use case for documentation, there's a better option.
If you want

- simplicity, use Markdown <http://daringfireball.net/projects/markdown/>.
Supported everywhere, like GH.
- bulky extensible semantic documentation, use
DocBook<http://www.docbook.org/>.
Used by O'Reilly, I'm told. Presumably that's how Real World
Haskell<http://book.realworldhaskell.org/> is
maintained as a slick website and an O'Reilly book.
- readability, but power and extensibility if required, use
docutils<http://docutils.sourceforge.net/>
/Sphinx <http://sphinx.pocoo.org/>. Used for the Python standard library
documentation <http://docs.python.org/py3k/>, which, as anyone who has
used it knows, is The Best Documentation In The World.

That said, I suspect DDOC is now entrenched at least in the stdlib
documentation, so maybe we'll have to live with it. However, the case
for using
it for the website<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>is
nonexistent (anyone disagree?).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/63da5eb7/attachment-0001.html>

[Chris Molozian]

I very much agree. When it comes to lightweight markup languages for use
in web (and more) templating there's: Markdown
<http://daringfireball.net/projects/markdown/>, Markdown Extra
<http://michelf.com/projects/php-markdown/extra/>, Haml
<http://haml-lang.com/>, Textile <http://textile.thresholdstate.com/>...
to name just a few. Is it worth maintaining another tool?

When it comes to documentation within source files couldn't D adopt one
of the many different
<http://en.wikipedia.org/wiki/Comparison_of_documentation_generators>documentation
generators? Again wouldn't that mean less custom tools to maintain.

Unless of course ddoc does something more than these other tools?

Cheers,

Chris

On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob at me.com
5. I know I suck at web site design, which is why David Gileadi helped
us out by designing the d-programming-language.org
<http://d-programming-language.org> look & feel.
I think it makes it hard when most of the pages are written in
DDOC. It doesn't help to attract web designers.
I'd definitely agree with that. I have no experience with DDOC, but
TBH I don't intend to ever have any. As a general criticism of DDOC,
it seems like another reinvented wheel. Semi-plaintext formats
surround us like the plague, and for every use case for documentation,
there's a better option. If you want
* simplicity, use Markdown
<http://daringfireball.net/projects/markdown/>. Supported
everywhere, like GH.
* bulky extensible semantic documentation, use DocBook
<http://www.docbook.org/>. Used by O'Reilly, I'm told.
Presumably that's how Real World Haskell
<http://book.realworldhaskell.org/> is maintained as a slick
website and an O'Reilly book.
* readability, but power and extensibility if required, use docutils
<http://docutils.sourceforge.net/>/Sphinx
<http://sphinx.pocoo.org/>. Used for the Python standard library
documentation <http://docs.python.org/py3k/>, which, as anyone who
has used it knows, is The Best Documentation In The World.
That said, I suspect DDOC is now entrenched at least in the stdlib
documentation, so maybe we'll have to live with it. However, the case
for using it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/fb017b67/attachment.html>

[Don]

Post by Chris Molozian
I very much agree. When it comes to lightweight markup languages for
use in web (and more) templating there's: Markdown
<http://daringfireball.net/projects/markdown/>, Markdown Extra
<http://michelf.com/projects/php-markdown/extra/>, Haml
<http://haml-lang.com/>, Textile <http://textile.thresholdstate.com/>...
to name just a few. Is it worth maintaining another tool?
When it comes to documentation within source files couldn't D adopt one
of the many different
<http://en.wikipedia.org/wiki/Comparison_of_documentation_generators>documentation
generators?

Look at how many of those tools support D.

Post by Chris Molozian
Again wouldn't that mean less custom tools to maintain.

I doubt it. The source for DDoc is only 2000 lines of code (and it's
simple code). D has enough unique features that you need to fight with
your document generation system, if it doesn't natively support D.

Post by Chris Molozian
Unless of course ddoc does something more than these other tools?
Cheers,
Chris

On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob at me.com
5. I know I suck at web site design, which is why David Gileadi helped
us out by designing the d-programming-language.org
<http://d-programming-language.org> look & feel.
I think it makes it hard when most of the pages are written in
DDOC. It doesn't help to attract web designers.
I'd definitely agree with that. I have no experience with DDOC, but
TBH I don't intend to ever have any. As a general criticism of DDOC,
it seems like another reinvented wheel. Semi-plaintext formats
surround us like the plague, and for every use case for documentation,
there's a better option. If you want
* simplicity, use Markdown
<http://daringfireball.net/projects/markdown/>. Supported
everywhere, like GH.
* bulky extensible semantic documentation, use DocBook
<http://www.docbook.org/>. Used by O'Reilly, I'm told.
Presumably that's how Real World Haskell
<http://book.realworldhaskell.org/> is maintained as a slick
website and an O'Reilly book.
* readability, but power and extensibility if required, use
docutils <http://docutils.sourceforge.net/>/Sphinx
<http://sphinx.pocoo.org/>. Used for the Python standard
library documentation <http://docs.python.org/py3k/>, which, as
anyone who has used it knows, is The Best Documentation In The
World.
That said, I suspect DDOC is now entrenched at least in the stdlib
documentation, so maybe we'll have to live with it. However, the case
for using it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

[James Fisher]

Post by Don

Post by Chris Molozian
I very much agree. When it comes to lightweight markup languages for use
in web (and more) templating there's: Markdown <
http://daringfireball.net/**projects/markdown/<http://daringfireball.net/projects/markdown/>>,
Markdown Extra <http://michelf.com/projects/**php-markdown/extra/<http://michelf.com/projects/php-markdown/extra/>>,
Haml <http://haml-lang.com/>, Textile <http://textile.**
thresholdstate.com/ <http://textile.thresholdstate.com/>>... to name just
a few. Is it worth maintaining another tool?
When it comes to documentation within source files couldn't D adopt one of
the many different <http://en.wikipedia.org/wiki/**
Comparison_of_documentation_**generators<http://en.wikipedia.org/wiki/Comparison_of_documentation_generators>>documentation
generators?

Look at how many of those tools support D.

Post by Chris Molozian
Again wouldn't that mean less custom tools to maintain.

I doubt it. The source for DDoc is only 2000 lines of code (and it's simple
code). D has enough unique features that you need to fight with your
document generation system, if it doesn't natively support D.

Perhaps we should drop the "what's better than DDOC" issue for the moment.
The real issue is relegating it to where it belongs, which is (surprise)
documenting D code. Which means separating out the stdlib documentation on
d-programming-language.org from ... everything else, in the tradition of

- http://python.org/ vs http://docs.python.org/
- http://www.ruby-lang.org/ <http://www.ruby-lang.org/en/> vs
http://www.ruby-doc.org/ <http://www.ruby-doc.org/stdlib/>
- http://www.perl.org/ vs http://perldoc.perl.org/
- http://nodejs.org/ vs http://nodejs.org/docs/v0.4.8/api/
- and others.

This thread is flitting between topics, for reasons that are entirely my
own. Perhaps new threads would be appropriate for:

- Separating d-programming-language.org from
docs.d-programming-language.org
- D brand identity
- Package management.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/a777a26e/attachment.html>

[Nick Sabalausky]

"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
Perhaps we should drop the "what's better than DDOC" issue for the moment.
The real issue is relegating it to where it belongs, which is (surprise)
documenting D code.

Have you even really looked at DDoc? It's a full-fledged text-macro system.
It's not as if it's just D's answer to Javadoc.

Post by James Fisher
Which means separating out the stdlib documentation on
d-programming-language.org from ... everything else, in the tradition of
- http://python.org/ vs http://docs.python.org/
- http://www.ruby-lang.org/ <http://www.ruby-lang.org/en/> vs
http://www.ruby-doc.org/ <http://www.ruby-doc.org/stdlib/>
- http://www.perl.org/ vs http://perldoc.perl.org/
- http://nodejs.org/ vs http://nodejs.org/docs/v0.4.8/api/
- and others.
This thread is flitting between topics, for reasons that are entirely my
- Separating d-programming-language.org from
docs.d-programming-language.org

Yea, we *could* play the "be a trend whore" dance and do it just like the
others merely because others do it that way. But there obviously needs to be
a more compelling reason than just that. And that's what I'm not seeing:
What's the benefit? DDoc obviously gets the job done fine, and without
creating reliance on another external tool. Any other system would need to
be learned too, and DDoc is trivial to learn. So what's the compelling
benefit that makes it all worthwhile?

[Andrej Mitrovic]

Post by Nick Sabalausky
Any other system would need to
be learned too, and DDoc is trivial to learn. So what's the compelling
benefit that makes it all worthwhile?

It's funny how outsiders think it's trivial to learn their own system
that they're used to, but they're not willing to learn DDOC that we're
used to.

[Nick Sabalausky]

"Andrej Mitrovic" <andrej.mitrovich at gmail.com> wrote in message

Post by Andrej Mitrovic

Post by Nick Sabalausky
Any other system would need to
be learned too, and DDoc is trivial to learn. So what's the compelling
benefit that makes it all worthwhile?

It's funny how outsiders think it's trivial to learn their own system
that they're used to, but they're not willing to learn DDOC that we're
used to.

Yea, exactly. I certainly appreciate the guy's intent to be helpful. That's
certainly welcome. But how helpful is it really for us to have random new
people coming in expecting us to change everything to their way. This is
like a few weeks ago when we had someone basically expecting us to turn D
into Java.

[LULZ]

Post by Nick Sabalausky
Yea, exactly. I certainly appreciate the guy's intent to be

helpful.

That's why I cast aspersion on him and question his motivations,
rather than simply discussing the merits/drawbacks of his comments.

If you didn't loose him with the silliness that "I'm firmly in the
camp that HTML *is* presentation. Or at least should be considered
such." You surely did with the shoulder rubbing, insular,
"outsider" bashing comments.

[Andrej Mitrovic]

Overreacting troll is overreacting. ;]

[Nick Sabalausky]

"Andrej Mitrovic" <andrej.mitrovich at gmail.com> wrote in message

Post by Andrej Mitrovic
Overreacting troll is overreacting. ;]

Troll feeder is troll feeding :)

[Walter Bright]

However, the case for using
it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

I do. Ddoc is:

1. Rather trivial to learn & use. A website/book/community devoted to how to use
it is completely unnecessary. It's fairly obvious how to use it (for someone
with a basic familiarity with HTML) by simply looking at a couple examples.

2. It automatically tracks the D language, so D code examples are always
properly highlighted.

3. It is always available and installed for anyone who installs D.

4. The D compiler and Ddoc are always in sync. No begging for updates from 3rd
parties, no lags even if they get right on incorporating necessary updates.

5. It is not necessary to direct anyone to install some third party system that
may not even exist on all the platforms D does. In general, we try to minimize
dependency on things that are not default installed across operating systems.

6. And lastly, it works, it delivers, and has for many years. It's proven its worth.


If a professional web designer uses famous system X to develop with, and if we
used famous system Y, it's just as much a barrier for him to relearn how to do
things with Y as it is to learn Ddoc.

Please don't be too dismissive of the productivity gains from using Ddoc. At the
time we started using it, the website and the Phobos documentation improved by
huge leaps and bounds, simply because it was so easy to generate decent
documentation with Ddoc.

[James Fisher]

On Wed, Jun 29, 2011 at 12:25 PM, Walter Bright

Post by Walter Bright
1. Rather trivial to learn & use. A website/book/community devoted to how
to use it is completely unnecessary. It's fairly obvious how to use it (for
someone with a basic familiarity with HTML) by simply looking at a couple
examples.
2. It automatically tracks the D language, so D code examples are always
properly highlighted.
3. It is always available and installed for anyone who installs D.
4. The D compiler and Ddoc are always in sync. No begging for updates from
3rd parties, no lags even if they get right on incorporating necessary
updates.
5. It is not necessary to direct anyone to install some third party system
that may not even exist on all the platforms D does. In general, we try to
minimize dependency on things that are not default installed across
operating systems.
6. And lastly, it works, it delivers, and has for many years. It's proven its worth.

OK. These are all good reasons to maintain code documentation in Ddoc --
i.e., the Phobos documentation. Let's drop the argument over replacing the
documentation format. What I'm not convinced of is that Ddoc is has any
advantage over a generic markup format when it comes to the homepage,
associated pages (FAQ, acknowledgements, etc.), howtos, or even the language
reference. When I look over any of those documents --
lex.dd<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/lex.dd>to
take a random example -- I don't see any semantics that can't be
expressed even in something as simple as Markdown. Forcing people to write
their howtos in Ddoc is asking too much for no good reason.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/cd8eb7fc/attachment-0001.html>

[Chris Molozian]

Ok, Ddoc is great at writing D documentation, that's what it was
designed for. Why use a tool designed for code documentation as a web
templating language? Aren't we (as programmers) always saying use the
right tool for the right job...

I understand Ddoc's advantages
<http://www.digitalmars.com/d/2.0/ddoc.html> now. No-one is saying Ddoc
is hard to learn (at least I'm not saying that) but with so many tools,
languages and frameworks to learn these days should it be necessary to
know it when you're a D enthusiast that wants to contribute a HTML
tutorial on d-programming-language.org.

My 2-cents,

Chris

Post by Walter Bright

However, the case for using
it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

1. Rather trivial to learn & use. A website/book/community devoted to
how to use it is completely unnecessary. It's fairly obvious how to
use it (for someone with a basic familiarity with HTML) by simply
looking at a couple examples.
2. It automatically tracks the D language, so D code examples are
always properly highlighted.
3. It is always available and installed for anyone who installs D.
4. The D compiler and Ddoc are always in sync. No begging for updates
from 3rd parties, no lags even if they get right on incorporating
necessary updates.
5. It is not necessary to direct anyone to install some third party
system that may not even exist on all the platforms D does. In
general, we try to minimize dependency on things that are not default
installed across operating systems.
6. And lastly, it works, it delivers, and has for many years. It's proven its worth.
If a professional web designer uses famous system X to develop with,
and if we used famous system Y, it's just as much a barrier for him to
relearn how to do things with Y as it is to learn Ddoc.
Please don't be too dismissive of the productivity gains from using
Ddoc. At the time we started using it, the website and the Phobos
documentation improved by huge leaps and bounds, simply because it was
so easy to generate decent documentation with Ddoc.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/f3dd1441/attachment.html>

[Ary Manzana]

Post by Walter Bright

However, the case for using
it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

1. Rather trivial to learn & use. A website/book/community devoted to
how to use it is completely unnecessary. It's fairly obvious how to use
it (for someone with a basic familiarity with HTML) by simply looking at
a couple examples.

But you have to learn it nonetheless.

Post by Walter Bright
2. It automatically tracks the D language, so D code examples are always
properly highlighted.

There are many tools to syntax highlight code using HTML. Making the
compiler (or some part of it) do it is... hmmm... it's not the
compiler's job!

Come on, it's not that hard to highlight with an external javascript
(Nick Sabalausky, please no comments :-P :-))

Post by Walter Bright
3. It is always available and installed for anyone who installs D.

Fair.

Post by Walter Bright
4. The D compiler and Ddoc are always in sync. No begging for updates
from 3rd parties, no lags even if they get right on incorporating
necessary updates.

More job for you and your team, having to keep that in sync. And when D
becomes more popular I'm sure someone else will write a better ddoc, or
better ddocs, so why spend effort and time doing it in-sync with the
compiler?

Post by Walter Bright
5. It is not necessary to direct anyone to install some third party
system that may not even exist on all the platforms D does. In general,
we try to minimize dependency on things that are not default installed
across operating systems.
6. And lastly, it works, it delivers, and has for many years. It's proven its worth.
If a professional web designer uses famous system X to develop with, and
if we used famous system Y, it's just as much a barrier for him to
relearn how to do things with Y as it is to learn Ddoc.
Please don't be too dismissive of the productivity gains from using
Ddoc. At the time we started using it, the website and the Phobos
documentation improved by huge leaps and bounds, simply because it was
so easy to generate decent documentation with Ddoc.

As someone else pointed out, the documentation for Phobos (or any
library) could be in a different subdomain without having to deal with
the main website styles or antyhing. And you can do the main website
with another framework.

[James Fisher]

Post by Ary Manzana
There are many tools to syntax highlight code using HTML. Making the
compiler (or some part of it) do it is... hmmm... it's not the compiler's
job!
Come on, it's not that hard to highlight with an external javascript (Nick
Sabalausky, please no comments :-P :-))

GP.

As someone else pointed out, the documentation for Phobos (or any library)

Post by Ary Manzana
could be in a different subdomain without having to deal with the main
website styles or antyhing. And you can do the main website with another
framework.

A related thought here: are we aware of GitHub site hosting? AFAICT
d-p-l.org doesn't use it, so I guess the repo is being pulled to another
server? As the content is (I think?) entirely static, GH hosting would be
easier, more maintainable, and cheaper. And no out-of-sync issues -- I saw
a thread today with someone complaining the site hadn't been pulled from GH
...

For the main site: while I've not used it, I hear GH's inbuilt support for
Jekyll <https://github.com/mojombo/jekyll>, a static site generator, is
great. It's pretty well
recognized<https://github.com/mojombo/jekyll/wiki/sites>,
completely customizable, and I suspect well within our requirements. Some
examples of sites built on it:

http://joelbradbury.net/
http://domain51.com/
http://jimeh.me/
http://neilang.com/

Of course, we don't have to use Jekyll, and can roll our own static site.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/14b1f0f2/attachment-0001.html>

[Jacob Carlborg]

Post by Ary Manzana

Post by Walter Bright

However, the case for using
it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

1. Rather trivial to learn & use. A website/book/community devoted to
how to use it is completely unnecessary. It's fairly obvious how to use
it (for someone with a basic familiarity with HTML) by simply looking at
a couple examples.

But you have to learn it nonetheless.

Post by Walter Bright
2. It automatically tracks the D language, so D code examples are always
properly highlighted.

There are many tools to syntax highlight code using HTML. Making the
compiler (or some part of it) do it is... hmmm... it's not the
compiler's job!
Come on, it's not that hard to highlight with an external javascript
(Nick Sabalausky, please no comments :-P :-))

No reason for using JavaScript to do it.

Post by Ary Manzana

Post by Walter Bright
3. It is always available and installed for anyone who installs D.

Fair.

Post by Walter Bright
4. The D compiler and Ddoc are always in sync. No begging for updates
from 3rd parties, no lags even if they get right on incorporating
necessary updates.

More job for you and your team, having to keep that in sync. And when D
becomes more popular I'm sure someone else will write a better ddoc, or
better ddocs, so why spend effort and time doing it in-sync with the
compiler?

If DDoc would be a separate tool then it *would* be necessary for the
developers to sync it with the compiler. When it's embedded in the
compiler it will be automatically.

[Nick Sabalausky]

"Ary Manzana" <ary at esperanto.org.ar> wrote in message

Post by Ary Manzana

Post by Walter Bright

However, the case for using
it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

1. Rather trivial to learn & use. A website/book/community devoted to
how to use it is completely unnecessary. It's fairly obvious how to use
it (for someone with a basic familiarity with HTML) by simply looking at
a couple examples.

But you have to learn it nonetheless.

So? You have to learn markdown, etc, too. And I always find myself reaching
for the syntax page whenever using one of those.

Post by Ary Manzana

Post by Walter Bright
2. It automatically tracks the D language, so D code examples are always
properly highlighted.

There are many tools to syntax highlight code using HTML. Making the
compiler (or some part of it) do it is... hmmm... it's not the compiler's
job!

Like Walter pointed out, it's far, far less maintenance and syncing-up work
if it does use the actual compiler.

Post by Ary Manzana
Come on, it's not that hard to highlight with an external javascript (Nick
Sabalausky, please no comments :-P :-))

Heh, Jacob already said it for me :)

Post by Ary Manzana

Post by Walter Bright
4. The D compiler and Ddoc are always in sync. No begging for updates
from 3rd parties, no lags even if they get right on incorporating
necessary updates.

More job for you and your team, having to keep that in sync. And when D
becomes more popular I'm sure someone else will write a better ddoc, or
better ddocs, so why spend effort and time doing it in-sync with the
compiler?

Again, it's far, far less maintenance and syncing-up work if it does use the
actual compiler.

Post by Ary Manzana
As someone else pointed out, the documentation for Phobos (or any library)
could be in a different subdomain without having to deal with the main
website styles or antyhing. And you can do the main website with another
framework.

Why use two separate systems when doing it all in one works fine? I really
hate the trend over the last decade of switching to a totally different
language for every damn little thing. It just creates *more* work, not less.

[Nick Sabalausky]

"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
Of course, we don't have to use Jekyll, and can roll our own static site.

??? That's exactly what we've done...roll our own static site... Why do we
have to have GitHub host it?

I realize you're intentions here are good, but the way I see it, you're
coming barging in here on a "Chase trends! Use more misc...stuff...just
because it's out there!" crusade.

[Jacob Carlborg]

Post by James Fisher
OK. These are all good reasons to maintain code documentation in Ddoc
-- i.e., the Phobos documentation. Let's drop the argument over
replacing the documentation format. What I'm not convinced of is that
Ddoc is has any advantage over a generic markup format when it comes to
the homepage, associated pages (FAQ, acknowledgements, etc.), howtos, or
even the language reference. When I look over any of those documents --
lex.dd
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/lex.dd>
to take a random example -- I don't see any semantics that can't be
expressed even in something as simple as Markdown. Forcing people to
write their howtos in Ddoc is asking too much for no good reason.

I completely agree with this.

[Walter Bright]

7. We don't get left in the lurch if said third party quits.

8. Ddoc understands the semantics of D code. Third party doc generators never will.

[Ary Manzana]

Post by Walter Bright
7. We don't get left in the lurch if said third party quits.
8. Ddoc understands the semantics of D code. Third party doc generators never will.

So the semantics of D code can only be understood by the compiler? Hmmm...

[Walter Bright]

Post by Ary Manzana

Post by Walter Bright
7. We don't get left in the lurch if said third party quits.
8. Ddoc understands the semantics of D code. Third party doc generators never will.

So the semantics of D code can only be understood by the compiler? Hmmm...

How many third party doc generators include essentially a compiler for every
language they support - or even for any of them?

[KennyTM~]

Post by Walter Bright

Post by Ary Manzana

Post by Walter Bright
7. We don't get left in the lurch if said third party quits.
8. Ddoc understands the semantics of D code. Third party doc generators never will.

So the semantics of D code can only be understood by the compiler? Hmmm...

How many third party doc generators include essentially a compiler for
every language they support - or even for any of them?

You don't need a compiler to understand a language for documenting the
code. A lexer is enough. And Pygment does support D.

http://pygments.org/languages/

Note that I and likely James Fisher are not talking about generating
header docs (i.e. Phobos docs), which point 8 will be valid. We're
talking about http://d-programming-language.org/language-reference.html
which restricting the choice to DDoc is unnecessary.

[Jacob Carlborg]

Post by Ary Manzana

Post by Walter Bright
7. We don't get left in the lurch if said third party quits.
8. Ddoc understands the semantics of D code. Third party doc generators never will.

So the semantics of D code can only be understood by the compiler? Hmmm...

The compiler will be the best tool for understanding a language. Unless
you do something like Clang/LLVM does. Where the compiler and other
tools build upon the same library that handles the language.

[Walter Bright]

Ok, Ddoc is great at writing D documentation, that's what it was designed for.
Why use a tool designed for code documentation as a web templating language?
Aren't we (as programmers) always saying use the right tool for the right job...
I understand Ddoc's advantages <http://www.digitalmars.com/d/2.0/ddoc.html> now.
No-one is saying Ddoc is hard to learn (at least I'm not saying that) but with
so many tools, languages and frameworks to learn these days should it be
necessary to know it when you're a D enthusiast that wants to contribute a HTML
tutorial on d-programming-language.org.

You're going to have to learn some sort of system in order to work on
documentation. Ddoc takes about 10 minutes to learn. I mean, $(B bold this
text). How hard can that be?

[Walter Bright]

Post by James Fisher
What I'm not convinced of is that Ddoc is has any
advantage over a generic markup format when it comes to the homepage, associated
pages (FAQ, acknowledgements, etc.), howtos, or even the language reference.
When I look over any of those documents -- lex.dd
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/lex.dd>
to take a random example -- I don't see any semantics that can't be expressed
even in something as simple as Markdown. Forcing people to write their howtos
in Ddoc is asking too much for no good reason.

Ok, so take lex.dd (or another page, pick any) and show how it is so much
easier, nicer, and more productive to express it using some other markup format.

[KennyTM~]

Post by Walter Bright

Post by James Fisher
What I'm not convinced of is that Ddoc is has any
advantage over a generic markup format when it comes to the homepage, associated
pages (FAQ, acknowledgements, etc.), howtos, or even the language reference.
When I look over any of those documents -- lex.dd
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/lex.dd>
to take a random example -- I don't see any semantics that can't be expressed
even in something as simple as Markdown. Forcing people to write their
howtos
in Ddoc is asking too much for no good reason.

Ok, so take lex.dd (or another page, pick any) and show how it is so
much easier, nicer, and more productive to express it using some other
markup format.

Ddoc:
https://raw.github.com/D-Programming-Language/d-programming-language.org/master/module.dd
Output: http://d-programming-language.org/module.html
reStructuredText (+ Sphinx):
https://raw.github.com/kennytm/dmd/gh-pages/module.rst
Output (using Sphinx's default stylesheet): http://kennytm.github.com/dmd/

The easier, nicer, and more productive part:
- Native support of sectioning and anchors instead of sprinkling with
<h3> and <a name>'s. Linking is also more natural.
- One could use an external Turing-complete parser (in Python, though)
for some special block of documentation, e.g. the grammar list, instead
of having to hack the macro system for the result. The latter is like
having to highlight the D code using $(RED x) $(GREEN x) $(BLUE x) manually.
- Writing reST is really like writing document. Writing DDoc is like
writing Lisp.
- reST has better support than DDoc is many aspects (output format,
stylesheets, plugins, documentations, etc.).

[Andrej Mitrovic]

Post by KennyTM~
Output (using Sphinx's default stylesheet): http://kennytm.github.com/dmd/

Hey it's the good old Python docs! :)

I like the fact that a table of contents is generated on the left.
This is missing on pretty much every page on dpl.org.

[Andrej Mitrovic]

Vim can syntax highlight rest syntax, that's really sweet.

[bearophile]

Post by KennyTM~
https://raw.github.com/kennytm/dmd/gh-pages/module.rst
Output (using Sphinx's default stylesheet): http://kennytm.github.com/dmd/

Yes, Sphinx is nice. Some Python tools are nice. I think I have suggested its usage here more than one year ago.

Bye,
bearophile

[Walter Bright]

- Native support of sectioning and anchors instead of sprinkling with <h3> and
<a name>'s.

In Ddoc, you can define your own macros to do that, for example:

H3=<h3>$0</h3>

and then:

$(H3 This is a Header 3)

There is no reason whatsoever you are stuck with the defaults.

Linking is also more natural.

What if the link points to another file? And what if sometimes you want it
intrafile, and another time interfile, without changing the source text?

And what if, for the unordered list, you wish to add a "class=foo" attribute for
one of them, and "class=bar" for another?

- One could use an external Turing-complete parser (in Python, though) for some
special block of documentation, e.g. the grammar list, instead of having to hack
the macro system for the result. The latter is like having to highlight the D
code using $(RED x) $(GREEN x) $(BLUE x) manually.
- Writing reST is really like writing document. Writing DDoc is like writing Lisp.
- reST has better support than DDoc is many aspects (output format, stylesheets,
plugins, documentations, etc.).

Let's say I have some C++ code, C code, and ASM code, and want them to use
different css classes. In Ddoc, I'd do:

$(CCODE
... C code ...
)

$(CPPCODE
... C++ code ...
)

$(ASMCODE
... asm code ...
)

and by defining the macros, I can set them to use div's, pre's, whatever
attributes I want, and do this as many times as I need to for ALL of the constructs.

Generally, how good or how bad your Ddoc source looks like depends on how you've
defined the macros.

[KennyTM~]

Post by Walter Bright

- Native support of sectioning and anchors instead of sprinkling with <h3> and
<a name>'s.

H3=<h3>$0</h3>
$(H3 This is a Header 3)
There is no reason whatsoever you are stuck with the defaults.

Right, it's possible, but it is ugly. Isn't the point to show the syntax
"easier, nicer, and more productive"?

Post by Walter Bright

Linking is also more natural.

What if the link points to another file? And what if sometimes you want
it intrafile, and another time interfile, without changing the source text?

Yes it is supported by Sphinx with the :ref:`target` syntax.

http://sphinx.pocoo.org/markup/inline.html#ref-role

In DDoc you have to write $(LINK2 foo.html#bar, bar). I don't see that
as a solution. For example, if you move MixinDeclaration to
declaration.dd, then existing link to MixinDeclaration will break
because you have to write $(LINK2 module.html#MixinDeclaration) or
define a macro in macro.ddoc, because DDoc can't automatically track the
targets. This won't happen in reST/Sphinx.

All existing approach listed in
http://d-programming-language.org/ddoc.html support inter- and
intra-file cross-referencing

Post by Walter Bright
And what if, for the unordered list, you wish to add a "class=foo"
attribute for one of them, and "class=bar" for another?

Why would you need to do that? Anyway, this is also supported by
docutils natively with the '.. class::' directive ('.. rst-class::' in
Sphinx):

.. rst-class:: foo

* 1
* 2
* 3

.. rst-class:: bar

* 4
* 5
* 6

http://sphinx.pocoo.org/rest.html#id2
http://docutils.sourceforge.net/docs/ref/rst/directives.html#class

Post by Walter Bright

- One could use an external Turing-complete parser (in Python, though) for some
special block of documentation, e.g. the grammar list, instead of having to hack
the macro system for the result. The latter is like having to
highlight the D
code using $(RED x) $(GREEN x) $(BLUE x) manually.
- Writing reST is really like writing document. Writing DDoc is like writing Lisp.
- reST has better support than DDoc is many aspects (output format, stylesheets,
plugins, documentations, etc.).

Let's say I have some C++ code, C code, and ASM code, and want them to
$(CCODE
... C code ...
)
$(CPPCODE
... C++ code ...
)
$(ASMCODE
... asm code ...
)
and by defining the macros, I can set them to use div's, pre's, whatever
attributes I want, and do this as many times as I need to for ALL of the constructs.

That's not an advantage of DDoc. As I've shown above you could use the
'.. class::' directive to assign classes, and it's also possible to
write your own directive or inline marker, more than DDoc's simple macro
system can do (e.g. it can create Phobos's links on the top without
relying on Javascript), and you could even use the '.. raw::' directive
to drop down to HTML.

But whether the document writer want to expose to these capabilities
frequently? I'd say no, they'd rather have functions to format the
document nicely by default.

Furthermore, Sphinx has the '.. code-block::' directive to even syntax
highlight those C and C++ code for you.

.. code-block:: c

int main() { return 0; }

.. code-block:: c++

template <typename T>
T min(const T& a, const T& b) { return a < b ? a : b; }

.. code-block:: gas

pushl %ebp
movl %esp,%ebp
pushl %edi
pushl %esi
pushl %ebx
subl $0x000001ec,%esp
calll 0x000c5361
popl %ebx

http://sphinx.pocoo.org/markup/code.html

Post by Walter Bright
Generally, how good or how bad your Ddoc source looks like depends on
how you've defined the macros.

This could be applied to everything, like C++ vs D ;). I'd rather the
source look good out of the box than having to define dozens of macros
to make it look good.

[Jacob Carlborg]

On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob at me.com
5. I know I suck at web site design, which is why David Gileadi helped
us out by designing the d-programming-language.org
<http://d-programming-language.org> look & feel.
I think it makes it hard when most of the pages are written in DDOC.
It doesn't help to attract web designers.
I'd definitely agree with that. I have no experience with DDOC, but TBH
I don't intend to ever have any. As a general criticism of DDOC, it
seems like another reinvented wheel. Semi-plaintext formats surround us
like the plague, and for every use case for documentation, there's a
better option. If you want
* simplicity, use Markdown
<http://daringfireball.net/projects/markdown/>. Supported
everywhere, like GH.
* bulky extensible semantic documentation, use DocBook
<http://www.docbook.org/>. Used by O'Reilly, I'm told.
Presumably that's how Real World Haskell
<http://book.realworldhaskell.org/> is maintained as a slick
website and an O'Reilly book.
* readability, but power and extensibility if required, use docutils
<http://docutils.sourceforge.net/>/Sphinx
<http://sphinx.pocoo.org/>. Used for the Python standard library
documentation <http://docs.python.org/py3k/>, which, as anyone who
has used it knows, is The Best Documentation In The World.
That said, I suspect DDOC is now entrenched at least in the stdlib
documentation, so maybe we'll have to live with it. However, the case
for using it for the website
<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd>
is nonexistent (anyone disagree?).

HTML or some kind of other language can be used for the web site and
DDoc for the actual documentation.

[Walter Bright]

Post by Jacob Carlborg
HTML or some kind of other language can be used for the web site

Yes, and that's what we do!

Post by Jacob Carlborg
and DDoc for the actual documentation.

I don't see your point here.

[Jacob Carlborg]

Post by Walter Bright

Post by Jacob Carlborg
HTML or some kind of other language can be used for the web site

Yes, and that's what we do!

Post by Jacob Carlborg
and DDoc for the actual documentation.

I don't see your point here.

What I've seen you use ddoc for both the website and the documentation.
With "documentation" I mean the doc comments written in the code. With
"website" I mean everything else, that isn't documentation.

[Adam D. Ruppe]

I have no experience with DDOC, but TBH I don't intend to ever have any.

The beauty of ddoc is you don't need experience with it.

/**
this is ddoc

yes just this
*/


My biggest criticism of it is trivial to fix, but I haven't found
the time yet.

That is, the std.ddoc that is used to build the main site outputs
presentational html instead of semantic html.


Just going through that and changing to more semantic tags - so
the automatically generated data from the ddoc back end is not lost
by the time it gets to html - would make a big difference.


Then you can more easily apply css or other xml transformations
to it.



Also as another note, the web pages really *aren't* written in
ddoc. Take a look at std.ddoc some day... it has plain HTML
for the main page structure.

If the content tags were more semantic, between css and that
plain html structure, boom, there's the stuff to attack for the web.
No need to think about ddoc at all.

[Lars T. Kyllingstad]

Also as another note, the web pages really *aren't* written in ddoc.

They most definitely are. std.ddoc is an exception.

https://github.com/D-Programming-Language/d-programming-language.org/blob/
master/index.dd

-Lars

[Walter Bright]

Post by Adam D. Ruppe
Also as another note, the web pages really *aren't* written in
ddoc. Take a look at std.ddoc some day... it has plain HTML
for the main page structure.

Ddoc is a macro system. std.ddoc defines the macros to translate from Ddoc to
HTML. I don't really understand your comment.

[Adam Ruppe]

Post by Walter Bright
Ddoc is a macro system. std.ddoc defines the macros to translate from
Ddoc to HTML. I don't really understand your comment.

Take a look at this definition:

===========

DDOC = <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>

<!--
Copyright (c) 1999-2010 by Digital Mars
All Rights Reserved Written by Walter Bright
http://www.digitalmars.com
-->

<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" >
<title>$(TITLE) - D Programming Language - Digital Mars</title>
<link rel="stylesheet" type="text/css" href="../style.css">

<script>
function listanchors()
{
var a = document.getElementById("quickindex");
if (!a) return;
var newText = "";
var hash = new Array;
var n = 0;
var values = new Array;
// List all anchors.
for (var i = 0; i < document.anchors.length; i++)
{
var a = document.anchors[i];
var text = a.name;
if (hash[text] > 0) continue;


============


While that's technically a ddoc macro, that has very little impact
on someone wanting to edit the page's overall structure, appearance,
or dynamic behavior.

If he just writes more plain html (etc.) inside that one macro block,
it will be applied to the site.

Don't have to learn special escaping rules or whatever; if you know
how to write html, you can edit these pages. What you see there
is what you get.

[Walter Bright]

Post by Adam Ruppe
While that's technically a ddoc macro, that has very little impact
on someone wanting to edit the page's overall structure, appearance,
or dynamic behavior.
If he just writes more plain html (etc.) inside that one macro block,
it will be applied to the site.
Don't have to learn special escaping rules or whatever; if you know
how to write html, you can edit these pages. What you see there
is what you get.

I'm really not getting what the problem is.

[Adam Ruppe]

Post by Walter Bright
I'm really not getting what the problem is.

That's the point - there *is* no problem, at least not once you
look past any initial resistance. Your existing skills just work.

[Walter Bright]

Post by Adam Ruppe

Post by Walter Bright
I'm really not getting what the problem is.

That's the point - there *is* no problem, at least not once you
look past any initial resistance. Your existing skills just work.

Oh, ok :-)

I should note that David redid the whole look & feel of the web site without
changing the source code - he simply changed the Ddoc macro definitions and the
style sheet.

[Nick Sabalausky]

"Adam D. Ruppe" <destructionator at gmail.com> wrote in message

Post by Adam D. Ruppe

I have no experience with DDOC, but TBH I don't intend to ever have any.

The beauty of ddoc is you don't need experience with it.
/**
this is ddoc
yes just this
*/
My biggest criticism of it is trivial to fix, but I haven't found
the time yet.
That is, the std.ddoc that is used to build the main site outputs
presentational html instead of semantic html.

I'm firmly in the camp that HTML *is* presentation. Or at least should be
considered such. And even moreso since CSS is such total garbage for any
presentational needs besides basic styling (hell, "cascading *STYLE*
sheets").

Of course, I haven't really looked at std.ddoc, so for all I know maybe it
could use improvement.

[Adam Ruppe]

Post by Nick Sabalausky
I'm firmly in the camp that HTML *is* presentation.

The problem here is two things can look the same, but should be
treated differently by post-processing programs.

For example, lists of members. The presentational style code in
std.ddoc now generates this kind of thing:

<dl>
<dt>enum Foo</dt>
<dd><dl>
<dt>member1</dt>
</dl></dd>

<dt>struct Bar</dt>
blah blah blah
</dl>

Now, suppose you want to do a post-processor of some sort to grab all
enums. It's more painful than it has to be - instead of using the
html structure, you've gotta scan the inner text too for the keywords.


You might want them to look the same, but it's still sometimes helpful
to be able to differentiate them by some kind of metadata.


I'm not really against having both presentational and semantic
data in the html, since the post-processor can always strip out
stuff it doesn't care about.

But, if that semantic stuff isn't present, it causes pain for
other scenarios down the line. (Contrast to missing presentational
stuff, which can be fairly easily regenerated with rich enough
semantics.)


When I get around to updating std.ddoc, I'll have it looking almost
the same except I'd add class="struct" and class="enum" to the
list macros too.

[Nick Sabalausky]

"Adam Ruppe" <destructionator at gmail.com> wrote in message

Post by Adam Ruppe

Post by Nick Sabalausky
I'm firmly in the camp that HTML *is* presentation.

The problem here is two things can look the same, but should be
treated differently by post-processing programs.
For example, lists of members. The presentational style code in
<dl>
<dt>enum Foo</dt>
<dd><dl>
<dt>member1</dt>
</dl></dd>
<dt>struct Bar</dt>
blah blah blah
</dl>
Now, suppose you want to do a post-processor of some sort to grab all
enums. It's more painful than it has to be - instead of using the
html structure, you've gotta scan the inner text too for the keywords.
You might want them to look the same, but it's still sometimes helpful
to be able to differentiate them by some kind of metadata.
I'm not really against having both presentational and semantic
data in the html, since the post-processor can always strip out
stuff it doesn't care about.
But, if that semantic stuff isn't present, it causes pain for
other scenarios down the line. (Contrast to missing presentational
stuff, which can be fairly easily regenerated with rich enough
semantics.)
When I get around to updating std.ddoc, I'll have it looking almost
the same except I'd add class="struct" and class="enum" to the
list macros too.

Yea, I see. That all makes sense.

[Nick Sabalausky]

"James Fisher" <jameshfisher at gmail.com> wrote in message

Post by James Fisher
*# Package management*
This one's *really* important. The front page of
digitalmars.org/d/describes it as having "... the programmer
productivity of modern languages
like Ruby and Python". The language, maybe, but this statement is
absolutely not true while there is no associated package manager.

Yea, that's why we're working on it. There's been a few rather big
discussions on it very recently and a number of people have been working on
actual code.

Post by James Fisher
I've followed the "two standard libraries" debacle with some confusion
(I'm
still not clear what's being done about it).

For D2, the std lib is Phobos. Period. For D1, the de-facto standard is
Tango (which was created because, at the time, Phobos wasn't very good and
didn't have much manpower). This hasn't been an issue in ages.

Post by James Fisher
The closest thing to a central repository seems to be
http://www.dsource.org/. But this is all wrong. People don't want to use
a
language-specific site to host their project under SVN. They want to use
GitHub/Bitbucket/Google code/etc. Dsource.org should just maintain a list
of packages for an installer -- say, like http://search.npmjs.org/.

DSource predates the widespread popularity of GitHub/Bitbucket/Google
code/etc. I think it actually predates Google Code, period. Also, I'd
caution against blanket stantements about "what people want." I, for one,
like DSource. There are some things about it I like *better* than the
others. And I'm happy using DSource for a number of things.

Post by James Fisher
That D
projects are hosted on a D-exclusive site tells me that D has a closed
community.

What this tells me is that you enjoy making assumptions and jumping to
conclusions. ;)

Post by James Fisher
*# Community fragmentation*
http://www.digitalmars.com/d/ -- seems to be official
http://www.d-programming-language.org/ -- also seems to be official!

You caught us right in the middle of the transition from
http://www.digitalmars.com/d/ to http://www.d-programming-language.org/
That's why it seems confusing.

Post by James Fisher
http://www.dprogramming.com/

I don't see what's so wrong with that. It never claims to be anything
official. I'm sure other languages have user-created sites, too. Big deal.

Post by James Fisher
http://www.dsource.org/
etc.

That's for project hosting. Not the same.

Post by James Fisher
*# It's unsearchable!*
This one is really trivial. There's an important reason that other
languages have squiffy names: searchability. Googling for "d <query>" is
useless, and "d language <query>" is still awful. Other languages that
suffer from the same affliction have the convention of appending "lang" as
a
suffix -- "golang", for example -- and this works well. It seems that
"dlang" has not caught on. I see there's a site at http://dlang.org/
(yes,
yet another one!). Whois says it's owned by http://oscarbrynolf.com/.
The
(seemingly recent?) move to GitHub and new website would have been a
chance
to get this right. Prepending "d programming language" to every search I
make is still absolutely horrible.

"d programming" works fine for me. And you're right, it is only a trivial
matter.

Post by James Fisher
*# No marketing or brand awareness*
OK, I can live with this. But make no mistake: it *does* seriously cut
down
on the people migrating to it. Take a look at the "free images" offered
at
http://digitalmars.com/d/dlinks.html -- this is a marketers nightmare!
That
list *literally* makes me shudder. I'm not saying that D requires another
generic Web 2.0 HTML5 look with gradients and rounded corners that one
sees
on the latest fashionable projects. I *am* saying that it needs something
consistent and clean, and currently it, seemingly willfully, has neither.

We've been doing a lot of marketing and promoting. As for the images, that
seems to be an incredibly petty "issue".

Post by James Fisher
The point I want to get across here is: the problem with the D programming
language *is not that there are problems with the D programming language.*
The language and compiler (from what I know) have been world-class for
some
time. I've seen a few conversations where people using D get quite
indignant that people are interested in Go, Rust, etc. D is not getting
new
users because it doesn't look like it *wants* new users: it dresses
sloppily, it doesn't make itself findable easily, and it doesn't have
infrastructure for new users to share and benefit from sharing.

The main problem with D is that there's too many people with their lists
about what's wrong with D, and not enough willing to actually jump in and
help out. I'm sorry if I come across a bit harsh, but we seriously get
another one of these "What's wrong with D" lists every few weeks (and each
one seems more out-of-date than the last) and hardly any of the people
writing them have ever actually made any real contributions besides just
complaints. If you're going to help out, then fantastic, and welcome aboard!
But if not, then please understand that we already have more volunteer
supervisors than we need, so that sort of thing gets very frustrating for
those of us dedicating our own time and effort for free to actually
accomplish all the goals.

[James Fisher]

Post by Nick Sabalausky
The main problem with D is that there's too many people with their lists
about what's wrong with D, and not enough willing to actually jump in and
help out. I'm sorry if I come across a bit harsh, but we seriously get
another one of these "What's wrong with D" lists every few weeks (and each
one seems more out-of-date than the last) and hardly any of the people
writing them have ever actually made any real contributions besides just
complaints. If you're going to help out, then fantastic, and welcome aboard!
But if not, then please understand that we already have more volunteer
supervisors than we need, so that sort of thing gets very frustrating for
those of us dedicating our own time and effort for free to actually
accomplish all the goals.

Well, sure I'm willing to help. The reason I started out like this was to
gauge whether these problems were actually seen to be problems by the
community -- you get a lot of projects that are so inward-facing that
suggestions that it should be otherwise are taken as insults.

While my coding abilities aren't bad, I figure that's not what I'm best
helping with here. Key things I'd suggest I could help with are:

- A simple D brand identity. Nothing complex, just an official
pronouncement that "this is our logo/logotype, this is our color palette,
these are the one or two fonts we use, here's how we describe ourselves,
here are some simple guidelines on how to build a D-branded site/document".
This could be hashed out and maintained in a small GH repo.
- Applying that to d-programming-language.org.
- Coming up with a long list of D community
sites/wikis/tutorials/howtos/documentation/link lists. Identifying projects
that overlap domains and drumming up support for these to be merged into the
most popular of them or into d-programming-language.org. **I do think
this is possible!**
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/2b9a91b1/attachment.html>

[Jimmy Cao]

I think that's a great idea (the common font, colors, logo(?))

We also need a list of tutorials and wikis.
Here's the tutorial/wiki I'm working on:
http://en.wikibooks.org/wiki/D_(The_Programming_Language)

I also think that ddoc isn't as good as many other alternatives, but I don't
think it's easy to change it.

Post by James Fisher

Post by Nick Sabalausky
The main problem with D is that there's too many people with their lists
about what's wrong with D, and not enough willing to actually jump in and
help out. I'm sorry if I come across a bit harsh, but we seriously get
another one of these "What's wrong with D" lists every few weeks (and each
one seems more out-of-date than the last) and hardly any of the people
writing them have ever actually made any real contributions besides just
complaints. If you're going to help out, then fantastic, and welcome aboard!
But if not, then please understand that we already have more volunteer
supervisors than we need, so that sort of thing gets very frustrating for
those of us dedicating our own time and effort for free to actually
accomplish all the goals.

Well, sure I'm willing to help. The reason I started out like this was to
gauge whether these problems were actually seen to be problems by the
community -- you get a lot of projects that are so inward-facing that
suggestions that it should be otherwise are taken as insults.
While my coding abilities aren't bad, I figure that's not what I'm best
- A simple D brand identity. Nothing complex, just an official
pronouncement that "this is our logo/logotype, this is our color palette,
these are the one or two fonts we use, here's how we describe ourselves,
here are some simple guidelines on how to build a D-branded site/document".
This could be hashed out and maintained in a small GH repo.
- Applying that to d-programming-language.org.
- Coming up with a long list of D community
sites/wikis/tutorials/howtos/documentation/link lists. Identifying projects
that overlap domains and drumming up support for these to be merged into the
most popular of them or into d-programming-language.org. **I do think
this is possible!**

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/a03bc8c6/attachment.html>

[David Gileadi]

Post by Nick Sabalausky
The main problem with D is that there's too many people with their lists
about what's wrong with D, and not enough willing to actually jump in and
help out. I'm sorry if I come across a bit harsh, but we seriously get
another one of these "What's wrong with D" lists every few weeks (and each
one seems more out-of-date than the last) and hardly any of the people
writing them have ever actually made any real contributions besides just
complaints. If you're going to help out, then fantastic, and welcome aboard!
But if not, then please understand that we already have more volunteer
supervisors than we need, so that sort of thing gets very
frustrating for
those of us dedicating our own time and effort for free to actually
accomplish all the goals.
Well, sure I'm willing to help. The reason I started out like this was
to gauge whether these problems were actually seen to be problems by the
community -- you get a lot of projects that are so inward-facing that
suggestions that it should be otherwise are taken as insults.
While my coding abilities aren't bad, I figure that's not what I'm best
* A simple D brand identity. Nothing complex, just an official
pronouncement that "this is our logo/logotype, this is our color
palette, these are the one or two fonts we use, here's how we
describe ourselves, here are some simple guidelines on how to
build a D-branded site/document". This could be hashed out and
maintained in a small GH repo.
* Applying that to d-programming-language.org
<http://d-programming-language.org>.
* Coming up with a long list of D community
sites/wikis/tutorials/howtos/documentation/link lists.
Identifying projects that overlap domains and drumming up
support for these to be merged into the most popular of them or
into d-programming-language.org
<http://d-programming-language.org>. **I do think this is possible!**

While I'm just a volunteer, based on my experience I believe that
contributions in these areas would be welcomed and very useful.

[bearophile]

James Fisher:

Welcome here.

Why I'm hesitating to switch to D<

You don't need to "switch" to D. Just using it along with other languages is better.

The language, maybe, but this statement is absolutely not true while there is no associated package manager.<

It's called advertisement :-)

a massive "batteries included" standard library is no substitute for a world-class package manager.<
The productivity gain that comes from being able to execute "dinstall <somepackage>", and then having it magically available, is *immense*.<

Right.

IMO the big-standard-library is a slightly outdated concept in an age where we're always able to pull stuff from the net in an instant.<

There are several more things I'd like in the D standard distribution. External libs don't avoid the need of a rich Phobos. As most other design things, it's a matter of trade-offs.

There's an important reason that other languages have squiffy names: searchability. Googling for "d <query>" is useless, and "d language <query>" is still awful.<

I think it's too much late to fix this for D.

The point I want to get across here is: the problem with the D programming language *is not that there are problems with the D programming language.* The language and compiler (from what I know) have been world-class for some time.<

Here there is a huge fallacy. I want a well designed language first, with a well debugged compiler that produces efficient binaries. This is the necessary base to build on, to create Phobos, all nice libraries, and tools like package managers and IDEs. A good language without libraries and tools is not so useful, but if you don't create a good language&compiler first, or you don't express the desire to create it, then I am not interested in it (in the world there are languages that are badly designed but are widely used). Regardless its status along its history, it's several years that D aims to be a good language with a good compiler.

Bye,
bearophile

[Walter Bright]

Post by bearophile
Regardless its status along its history, it's several years that D aims to be
a good language with a good compiler.

I'd like to agree that D's emphasis has been first and foremost on being an
excellent language.

It gives the rest something to live up to :-)

[Jacob Carlborg]

Post by James Fisher
I'm a casual follower of development on D. In my opinion, it's the
cleanest, most complete multi-paradigm language currently out there --
from what I can see, I would describe the language as *done*. However,
I, like many others, am not switching to it. Why? Because a perfect
language does not a perfect development environment make: everything
*surrounding* the language is a complete mess. Here's my
non-comprehensive laundry list in the hope it's useful to someone.
*# Package management*

I working on this. This is the ideas I have:
https://github.com/jacob-carlborg/orbit/wiki/Orbit-Package-Manager-for-D

I've started the development. I'm going to write a more detail
explanation/specification of the tools.

[James Fisher]

I working on this. This is the ideas I have: https://github.com/jacob-**
carlborg/orbit/wiki/Orbit-**Package-Manager-for-D<https://github.com/jacob-carlborg/orbit/wiki/Orbit-Package-Manager-for-D>
I've started the development. I'm going to write a more detail
explanation/specification of the tools.

Oh, cool. Should discussion for this happen on GH Issues?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110629/2acd5e03/attachment.html>

[Caligo]

www.digitalmars.com/d/ still shows up in search results and it points
to the old crappy site. Can we get this link to point to the new
site?

[Walter Bright]

Post by Caligo
www.digitalmars.com/d/ still shows up in search results and it points
to the old crappy site. Can we get this link to point to the new
site?

Yeah, I'll get it fixed.

[Jacob Carlborg]

On Wed, Jun 29, 2011 at 7:52 AM, Jacob Carlborg <doob at me.com
https://github.com/jacob-__carlborg/orbit/wiki/Orbit-__Package-Manager-for-D
<https://github.com/jacob-carlborg/orbit/wiki/Orbit-Package-Manager-for-D>
I've started the development. I'm going to write a more detail
explanation/specification of the tools.
Oh, cool. Should discussion for this happen on GH Issues?

I don't know. This is where the discussion will be most exposed.

[Dejan Lekic]

James, no offense - this is a post made by a person who probably did not
look more than 10min for what he needs...

#1 Package management - if you were around you would see that it is a
hot topic, and will be solved soon.

#2 I do not know how you see community fragmentation, really. D
community is here on the NG, on IRC ( irc://irc.freenode.org/d ),
DSource, GitHub ...

#3 Unreachable? How? Do not tell me you type "D" in Google and You
seriously expect it to give you http://www.d-programming-language.org as
the first hit!? :)

#4 Now I am convinced you actually did not look at the
http://www.d-programming-language.org ... Yes, DigitalMars website has
kind of "old-school" HTML, but there are other websites out there. If
you discard an excellent programming language like D just because the
author's website looks crappy, than I have no further comments, really...

Conclusion:

-- Get informed.

[Adam Ruppe]

Conclusion: -- Get informed.

To be fair, when someone is saying "you aren't very good at getting
the word out in a consistent way", saying "get informed" is just
shifting the blame right back.

[Chris Molozian]

What a useless comment to a potential contributor... see Walter's
earlier comment for a constructive way to reply to someone interested in D.

Btw, prefixing your comment with "no offense", is like saying "with all
due respect you're an ass."

Chris

Post by Dejan Lekic
James, no offense - this is a post made by a person who probably did
not look more than 10min for what he needs...
#1 Package management - if you were around you would see that it is a
hot topic, and will be solved soon.
#2 I do not know how you see community fragmentation, really. D
community is here on the NG, on IRC ( irc://irc.freenode.org/d ),
DSource, GitHub ...
#3 Unreachable? How? Do not tell me you type "D" in Google and You
seriously expect it to give you http://www.d-programming-language.org
as the first hit!? :)
#4 Now I am convinced you actually did not look at the
http://www.d-programming-language.org ... Yes, DigitalMars website has
kind of "old-school" HTML, but there are other websites out there. If
you discard an excellent programming language like D just because the
author's website looks crappy, than I have no further comments, really...
-- Get informed.

[Walter Bright]

Yes, DigitalMars website has kind of
"old-school" HTML, but there are other websites out there.

Sure, it's an old school look.

1. That is not the fault of Ddoc, it is more that that's my level of web site
expertise.

2. I've stuck to things that make a website:

1. fast to load
2. looks the same in all browsers with no special case browser coding
3. allows the client to format and reflow the text
4. work even if javascript is disabled

And, in general, I think a programming language web site should be fairly
straightforward. I don't think having it look like a Coca Cola web site is
appropriate for the audience. It should be easy to navigate, easy on the eyes,
and "just the facts, ma'am."

[Jose Armando Garcia]

On Wed, Jun 29, 2011 at 3:42 PM, Walter Bright

Post by Walter Bright
And, in general, I think a programming language web site should be fairly
straightforward. I don't think having it look like a Coca Cola web site is
appropriate for the audience. It should be easy to navigate, easy on the
eyes, and "just the facts, ma'am."

Amen to that. I would love to some day generate man pages for druntime
and phobos. Need to find some time...

[Nick Sabalausky]

"Walter Bright" <newshound2 at digitalmars.com> wrote in message

Post by Walter Bright
And, in general, I think a programming language web site should be fairly
straightforward. I don't think having it look like a Coca Cola web site is
appropriate for the audience. It should be easy to navigate, easy on the
eyes, and "just the facts, ma'am."

Heh, I can just imagine a D site packed with stock photos of overly-excited
models on trampolines (like they have on boxes of "low-fat" foods) or suits
smiling into the camera because they just absolutely *love* being telephone
support reps. Horrifying thought...