www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Why I'm hesitating to switch to D

reply James Fisher <jameshfisher gmail.com> writes:
--90e6ba613b24e4dba204a6cacce5
Content-Type: text/plain; charset=UTF-8

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

--90e6ba613b24e4dba204a6cacce5
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<div>I&#39;m a casual follower of development on D. =C2=A0In my opinion, it=
&#39;s the cleanest, most complete multi-paradigm language currently out th=
ere -- from what I can see, I would describe the language as *done*. =C2=A0=
However, I, like many others, am not switching to it. =C2=A0Why? =C2=A0Beca=
use a perfect language does not a perfect development environment make: eve=
rything *surrounding* the language is a complete mess. =C2=A0Here&#39;s my =
non-comprehensive laundry list in the hope it&#39;s useful to someone.</div=

r></div><div>This one&#39;s *really* important. =C2=A0The front page of <a = href=3D"http://digitalmars.org/d/">digitalmars.org/d/</a> describes it as h= aving &quot;... the programmer productivity of modern languages like Ruby a= nd Python&quot;. =C2=A0The language, maybe, but this statement is absolutel= y not true while there is no associated package manager.</div> <div><br></div><div>I&#39;ve followed the &quot;two standard libraries&quot= ; debacle with some confusion (I&#39;m still not clear what&#39;s being don= e about it). =C2=A0But this isn&#39;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 &quot;batteries included= &quot; standard library is no substitute for a world-class package manager.= =C2=A0IMO the big-standard-library is a slightly outdated concept in an ag= e where we&#39;re always able to pull stuff from the net in an instant. =C2= =A0A big stdlib means a big platform installation, no matter the size of th= e task, and yet no stdlib can be so big as to satisfy all needs.</div> <meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8"><d= iv><br></div><div>The productivity gain that comes from being able to execu= te &quot;dinstall &lt;somepackage&gt;&quot;, and then having it magically a= vailable, is *immense*. =C2=A0When I need to get a job done, I&#39;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 inst= all, realise dependencies are missing, install them too, then fix everythin= g that&#39;s broken. =C2=A0Having a package manager is also crucial to gett= ing people to bother sharing their code with others.</div> <div><br></div><div>The closest thing to a central repository seems to be= =C2=A0<a href=3D"http://www.dsource.org/">http://www.dsource.org/</a>. =C2= =A0But this is all wrong. =C2=A0People don&#39;t want to use a language-spe= cific site to host their project under SVN. =C2=A0They want to use GitHub/B= itbucket/Google code/etc. =C2=A0Dsource.org should just maintain a list of = packages for an installer -- say, like=C2=A0<a href=3D"http://search.npmjs.= org/">http://search.npmjs.org/</a>. =C2=A0That D projects are hosted on a D= -exclusive site tells me that D has a closed community.</div> <div><br></div><div>Yet D has a working module and package system, so a wor= king package manager should be a small task!</div><meta http-equiv=3D"conte= nt-type" content=3D"text/html; charset=3Dutf-8"><meta http-equiv=3D"content= -type" content=3D"text/html; charset=3Dutf-8"><meta http-equiv=3D"content-t= ype" content=3D"text/html; charset=3Dutf-8"><meta http-equiv=3D"content-typ= e" content=3D"text/html; charset=3Dutf-8"><div> <br></div><div><br></div><div><b># Community fragmentation</b></div><div><b= r></div><div>Where is the D community? =C2=A0I see:</div><div><br></div><di= v><a href=3D"http://www.digitalmars.com/d/">http://www.digitalmars.com/d/</= a> -- seems to be official</div> <div><a href=3D"http://www.d-programming-language.org/">http://www.d-progra= mming-language.org/</a> -- also seems to be official!</div><div><br></div><= div>I would guess that <a href=3D"http://d-programming-language.org">d-prog= ramming-language.org</a> is meant to deprecate the digitalmars page, but th= ere&#39;s no statement to that effect on either site.</div> <div><br></div><div>There&#39;s a whole host of other sites that seem to ha= ve spawned, I guess because whatever *is* the official center is unsatisfac= tory:</div><div><br></div><div><a href=3D"http://www.dprogramming.com/">htt= p://www.dprogramming.com/</a></div> <div><a href=3D"http://www.dsource.org/">http://www.dsource.org/</a></div><= div>etc.</div><div><br></div><div>Some real effort has to go into rounding = up the herd. =C2=A0(The move to git and GitHub is an excellent one in this = regard.)</div> <div><br></div><div><br></div><div><b># It&#39;s unsearchable!</b></div><di= v><br></div><div>This one is really trivial. =C2=A0There&#39;s an important= reason that other languages have squiffy names: searchability. =C2=A0Googl= ing for &quot;d &lt;query&gt;&quot; is useless, and &quot;d language &lt;qu= ery&gt;&quot; is still awful. =C2=A0Other languages that suffer from the sa= me affliction have the convention of appending &quot;lang&quot; as a suffix= -- &quot;golang&quot;, for example -- and this works well. =C2=A0It seems = that &quot;dlang&quot; has not caught on. =C2=A0I see there&#39;s a site at= <a href=3D"http://dlang.org/">http://dlang.org/</a> (yes, yet another one!= ). =C2=A0Whois says it&#39;s owned by <a href=3D"http://oscarbrynolf.com/">= http://oscarbrynolf.com/</a>. =C2=A0The (seemingly recent?) move to GitHub = and new website would have been a chance to get this right. =C2=A0Prependin= g &quot;d programming language&quot; to every search I make is still absolu= tely horrible.</div> <meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8"><d= iv><br></div><div><br></div><div><b># No marketing or brand awareness</b></= div><div><br></div><div>OK, I can live with this. =C2=A0But make no mistake= : it *does* seriously cut down on the people migrating to it. =C2=A0Take a = look at the &quot;free images&quot; offered at <a href=3D"http://digitalmar= s.com/d/dlinks.html">http://digitalmars.com/d/dlinks.html</a> -- this is a = marketers nightmare! =C2=A0That list *literally* makes me shudder. =C2=A0I&= #39;m not saying that D requires another generic Web 2.0 HTML5 look with gr= adients and rounded corners that one sees on the latest fashionable project= s. =C2=A0I *am* saying that it needs something consistent and clean, and cu= rrently it, seemingly willfully, has neither. =C2=A0(BTW, I&#39;ve done som= e web design work before, e.g. <a href=3D"http://hsk.org.uk/">http://hsk.or= g.uk/</a> -- I&#39;d be willing to help out.)</div> <div><br></div><div>For comparative illustration:</div><div><br></div><div>= <a href=3D"http://python.org/">http://python.org/</a> -- clean, no showines= s.</div><div><a href=3D"http://www.ruby-lang.org/en/">http://www.ruby-lang.= org/en/</a> -- a bit busy, but consistent.</div> <div><a href=3D"http://golang.org/">http://golang.org/</a> -- very clean, w= ell organized.</div><div><meta http-equiv=3D"content-type" content=3D"text/= html; charset=3Dutf-8"><a href=3D"http://haskell.org/haskellwiki/Haskell">h= ttp://haskell.org/</a></div> <div><br></div><div><br></div><div>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.* =C2=A0The language and compiler (from wh= at I know) have been world-class for some time. =C2=A0I&#39;ve seen a few c= onversations where people using D get quite indignant that people are inter= ested in Go, Rust, etc. =C2=A0D is not getting new users because it doesn&#= 39;t look like it *wants* new users: it dresses sloppily, it doesn&#39;t ma= ke itself findable easily, and it doesn&#39;t have infrastructure for new u= sers to share and benefit from sharing.</div> <div><br></div><div><br></div><div>James Fisher</div> --90e6ba613b24e4dba204a6cacce5--
Jun 28 2011
next sibling parent David Gileadi <gileadis NSPMgmail.com> writes:
On 6/28/11 1:37 PM, James Fisher wrote:
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.
Jun 28 2011
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Jun 28 2011
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-06-28 23:09, Walter Bright wrote:
 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. -- /Jacob Carlborg
Jun 28 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/28/2011 11:46 PM, Jacob Carlborg wrote:
 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.)
Jun 29 2011
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-06-29 10:29, Walter Bright wrote:
 On 6/28/2011 11:46 PM, Jacob Carlborg wrote:
 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.
 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. -- /Jacob Carlborg
Jun 29 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 6:58 AM, Jacob Carlborg wrote:
 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.

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.
Jun 29 2011
parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 20:16, Walter Bright wrote:
 On 6/29/2011 6:58 AM, Jacob Carlborg wrote:
 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.

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.
 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. -- /Jacob Carlborg
Jun 29 2011
prev sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Jacob Carlborg" <doob me.com> wrote in message 
news:iufbc8$22ob$1 digitalmars.com...
 On 2011-06-29 10:29, Walter Bright wrote:
 On 6/28/2011 11:46 PM, Jacob Carlborg wrote:
 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.

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.
Jun 29 2011
parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 22:07, Nick Sabalausky wrote:
 "Jacob Carlborg"<doob me.com>  wrote in message
 news:iufbc8$22ob$1 digitalmars.com...
 On 2011-06-29 10:29, Walter Bright wrote:
 On 6/28/2011 11:46 PM, Jacob Carlborg wrote:
 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.

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. -- /Jacob Carlborg
Jun 29 2011
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 4:03 AM, Adam Richardson wrote:
 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?
 it's just not built for web site development.

Anything you can do in HTML, you can do in Ddoc.
 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.
Jun 29 2011
next sibling parent reply Robert Clipsham <robert octarineparrot.com> writes:
On 29/06/2011 19:14, Walter Bright wrote:
 On 6/29/2011 4:03 AM, Adam Richardson wrote:
 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. -- Robert http://octarineparrot.com/
Jun 29 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 11:42 AM, Robert Clipsham wrote:
 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.

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

 Code:

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

 Markdown:
 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.
 DDoc:
 $(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.
 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/)

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.
Jun 29 2011
parent reply Robert Clipsham <robert octarineparrot.com> writes:
On 29/06/2011 19:57, Walter Bright wrote:
 On 6/29/2011 11:42 AM, Robert Clipsham wrote:
 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.

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.
 * DDoc macros make even the simplest things ugly

 Code:

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

 Markdown:
 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?
 DDoc:
 $(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!
 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/)

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.
 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?
 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 -- Robert http://octarineparrot.com/
Jun 29 2011
parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 12:17 PM, Robert Clipsham wrote:
 I'm just glad it ditched the horrible  params: etc nonsense that every other
 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.
 GLINK?

GLINK=$(LINK2 #$0, $(I $0))
 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/)

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?
 Should I open an enhancement request in bugzilla?

Sure.
Jun 29 2011
prev sibling next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
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.
Jun 29 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 12:09 PM, Adam Ruppe wrote:
 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 $.
Jun 29 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/29/11 2:58 PM, Walter Bright wrote:
 On 6/29/2011 12:09 PM, Adam Ruppe wrote:
 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 $.

One good thing about ddoc is its uniformity, $(name comma-sep-list) is replaced by the definition of name. That should be pretty much it. If anything I'd add to that uniformity: (a) remove the ---- syntax which is quite difficult to use with my editors, (b) replace params: and etc. with macro-style syntax. Andrei
Jul 02 2011
parent Adam D. Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu wrote:
 If anything I'd add to that uniformity:

I don't know, it seems ok the way it is. The sections aren't quite macros, though they are implemented that way (sections become DDOC_SECTION and DDOC_SECTION_H). I like the way they look though. It's a natural way to organize stuff.
Jul 02 2011
prev sibling next sibling parent "Nick Sabalausky" <a a.a> writes:
"Robert Clipsham" <robert octarineparrot.com> wrote in message 
news:iufs08$pmu$1 digitalmars.com...
 On 29/06/2011 19:14, Walter Bright wrote:
 On 6/29/2011 4:03 AM, Adam Richardson wrote:
 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:

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.
Jun 29 2011
prev sibling parent Lutger Blijdestijn <lutger.blijdestijn gmail.com> writes:
Robert Clipsham wrote:

 On 29/06/2011 19:14, Walter Bright wrote:
 On 6/29/2011 4:03 AM, Adam Richardson wrote:
 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

Sure, but it's really apples and oranges. Any such template system for markup is both complicated, limited and convenient at once. It has no power at all. DDoc is the other way around, it's a very different approach. The equivalent to ddoc's extensibility would be hacking the sources of a markdown processor to extend it. Now that's painful. You could, for example, write everything in markdown but first put it through ddoc and then process it's output with some markdown tool. That way you write mostly simple markdown and have some extra power from the macro system. That's actually the approach that ddoc for D code has: very limited sugar for the most common cases, but with the optional power to extend it. The other way around should be possible too: a markdown macro which tags a fragment for postprocessing.
Jul 01 2011
prev sibling next sibling parent Adam Ruppe <destructionator gmail.com> writes:
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.
Jun 29 2011
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 12:59 PM, Adam Richardson wrote:
 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.
Jun 29 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 22:31, Andrej Mitrovic wrote:
 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? :)

Having XML in comments/documentation like that is just ridicules. -- /Jacob Carlborg
Jun 29 2011
prev sibling next sibling parent Don <nospam nospam.com> writes:
Chris Molozian wrote:
   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_gene
ators>documentation 
 generators? 

Look at how many of those tools support D.
 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.
 Unless of course ddoc does something more than these other tools?

 
 Cheers,
 
 Chris
 
 
 On 06/29/11 09:38, James Fisher wrote:
 On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob me.com 
 <mailto:doob me.com>> wrote:

     On 2011-06-28 23:09, Walter Bright wrote:

         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/b
ob/master/index.dd> 
 is nonexistent (anyone disagree?).


Jun 29 2011
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 1:38 AM, James Fisher wrote:
 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.
Jun 29 2011
next sibling parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 6/29/11 6:25 PM, Walter Bright wrote:
 On 6/29/2011 1:38 AM, James Fisher wrote:
 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.

But you have to learn it nonetheless.
 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 :-))
 3. It is always available and installed for anyone who installs D.

Fair.
 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?
 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.
Jun 29 2011
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 15:39, Ary Manzana wrote:
 On 6/29/11 6:25 PM, Walter Bright wrote:
 On 6/29/2011 1:38 AM, James Fisher wrote:
 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.

But you have to learn it nonetheless.
 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.
 3. It is always available and installed for anyone who installs D.

Fair.
 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. -- /Jacob Carlborg
Jun 29 2011
prev sibling next sibling parent "Nick Sabalausky" <a a.a> writes:
"Ary Manzana" <ary esperanto.org.ar> wrote in message 
news:iufa8g$20o9$1 digitalmars.com...
 On 6/29/11 6:25 PM, Walter Bright wrote:
 On 6/29/2011 1:38 AM, James Fisher wrote:
 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.

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.
 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.
 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 :)
 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.
 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.
Jun 29 2011
prev sibling next sibling parent "Nick Sabalausky" <a a.a> writes:
"James Fisher" <jameshfisher gmail.com> wrote in message 
news:mailman.1285.1309356559.14074.digitalmars-d puremagic.com...
 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.
Jun 29 2011
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/29/11 9:09 AM, James Fisher wrote:
 A related thought here: are we aware of GitHub site hosting?  AFAICT
 d-p-l.org <http://d-p-l.org> doesn't use it, so I guess the repo is
 being pulled to another server?

I think this has been cleared already - the d-programming-language.org website is on github. Andrei
Jul 02 2011
parent reply KennyTM~ <kennytm gmail.com> writes:
On Jul 3, 11 03:33, Andrei Alexandrescu wrote:
 On 6/29/11 9:09 AM, James Fisher wrote:
 A related thought here: are we aware of GitHub site hosting? AFAICT
 d-p-l.org <http://d-p-l.org> doesn't use it, so I guess the repo is
 being pulled to another server?

I think this has been cleared already - the d-programming-language.org website is on github. Andrei

By 'github hosting' I think he means 'github:pages' (http://pages.github.com/). Having d-p-l.org hosted outside of github is fine, as long as it is synced (pulled) frequently enough with the github repo.
Jul 02 2011
parent Michel Fortin <michel.fortin michelf.com> writes:
On 2011-07-02 15:55:13 -0400, KennyTM~ <kennytm gmail.com> said:

 On Jul 3, 11 03:33, Andrei Alexandrescu wrote:
 On 6/29/11 9:09 AM, James Fisher wrote:
 A related thought here: are we aware of GitHub site hosting? AFAICT
 d-p-l.org <http://d-p-l.org> doesn't use it, so I guess the repo is
 being pulled to another server?

I think this has been cleared already - the d-programming-language.org website is on github. Andrei

By 'github hosting' I think he means 'github:pages' (http://pages.github.com/). Having d-p-l.org hosted outside of github is fine, as long as it is synced (pulled) frequently enough with the github repo.

Agree. That said, it might be beneficial to use github (or some other server) as a mirror for the DMD binary packages, as http://ftp.digitalmars.com/ is notoriously slow to download from. -- Michel Fortin michel.fortin michelf.com http://michelf.com/
Jul 02 2011
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 15:12, James Fisher wrote:
 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. -- /Jacob Carlborg
Jun 29 2011
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 4:25 AM, Walter Bright wrote:
 Ddoc is:

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.
Jun 29 2011
parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 6/30/11 1:00 AM, Walter Bright wrote:
 On 6/29/2011 4:25 AM, Walter Bright wrote:
 Ddoc is:

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...
Jun 29 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 8:35 PM, Ary Manzana wrote:
 On 6/30/11 1:00 AM, Walter Bright wrote:
 On 6/29/2011 4:25 AM, Walter Bright wrote:
 Ddoc is:

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?
Jun 29 2011
parent KennyTM~ <kennytm gmail.com> writes:
On Jun 30, 11 13:20, Walter Bright wrote:
 On 6/29/2011 8:35 PM, Ary Manzana wrote:
 On 6/30/11 1:00 AM, Walter Bright wrote:
 On 6/29/2011 4:25 AM, Walter Bright wrote:
 Ddoc is:

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.
Jun 30 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-06-30 05:35, Ary Manzana wrote:
 On 6/30/11 1:00 AM, Walter Bright wrote:
 On 6/29/2011 4:25 AM, Walter Bright wrote:
 Ddoc is:

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. -- /Jacob Carlborg
Jun 30 2011
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 6:37 AM, Chris Molozian wrote:
 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?
Jun 29 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 6:12 AM, James Fisher wrote:
 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.
Jun 29 2011
parent reply KennyTM~ <kennytm gmail.com> writes:
On Jun 30, 11 02:20, Walter Bright wrote:
 On 6/29/2011 6:12 AM, James Fisher wrote:
 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.).
Jun 29 2011
next sibling parent bearophile <bearophileHUGS lycos.com> writes:
KennyTM~:

 reStructuredText (+ Sphinx): 
 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
Jun 29 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 3:56 PM, KennyTM~ wrote:
 The easier, nicer, and more productive part:
 - 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.
Jun 29 2011
next sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Jun 30, 11 11:57, Walter Bright wrote:
 On 6/29/2011 3:56 PM, KennyTM~ wrote:
 The easier, nicer, and more productive part:
 - 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.

Right, it's possible, but it is ugly. Isn't the point to show the syntax "easier, nicer, and more productive"?
 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
 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
 - 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.

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
 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.
Jun 30 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 1:26 AM, KennyTM~ wrote:
 Right, it's possible, but it is ugly. Isn't the point to show the syntax
 "easier, nicer, and more productive"?

Ddoc has pretty much only one syntax. Sphinx seems to have a lot of them.
 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?

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

What's natural about that?
 In DDoc you have to write $(LINK2 foo.html#bar, bar).

No, you don't have to. I'll often write it as: $(CHAPTER foo, 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.

Yes, the idea that a link may be somewhere in a collection files, is probably better.
 And what if, for the unordered list, you wish to add a "class=foo"
 attribute for one of them, and "class=bar" for another?


Style sheets. For example, sometimes you want a list to go out horizontally rather than vertically; this is controlled by the style sheet. You specify a class for the list, and then the layout for that class.
 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

This I don't particularly like. I've got to learn a new syntax for it, I've got to read and learn a manual on what 'class' means for Sphinx and do some spelunking to figure out if it is the same thing as an html class or something different. The syntax arguably isn't better, either. It's just different. Even worse, if I want to change the classes, I've got to do a global search/replace. With Ddoc, I change one macro. With Ddoc, you can read the HTML manual and apply it directly to Ddoc. Ddoc doesn't even know what HTML is, so it has no need to replicate its functionality in a same-only-different manner. HTML has lots of these attributes. Are they *all* in Sphinx? What if a new one is added to HTML? What if I want to use :: in my text? One problem with a lot of text markup is you've got to provide escapes for all that - which is why Ddoc pretty much sticks to $. In Ddoc, for another example, I did the documentation for the Digital Mars C++ runtime library. For web pages, I formatted things using definition lists. Unfortunately, those came out badly in the Kindle, but using h4 instead worked much better. Since I had written the docs in terms of a higher level Ddoc macro, I simply changed its definition to use h4 instead of dl, and voila! thousands of library functions got fixed without incredibly tediously recoding each one. For me, a viable doc system needs to have some sort of symbolic redefinition capability. Textual macro processors have existed for a long time, and they work well for that, which is why Ddoc went that direction. (You might notice that Ddoc macros are a lot like makefile macros!) (I did consider using the C macro preprocessor, but it is too specialized for C.)
 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.

class::' directive to assign classes,

Do I gotta do that every time I write a CPPCODE section?
 and it's also possible to write your own
 directive or inline marker,

That would be better.
 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.

The default works well 95% of the time. The rest of the time it doesn't, and if you have to leave the documentation system, it really sucks.
 Furthermore, Sphinx has the '.. code-block::' directive to even syntax
highlight
 those C and C++ code for you.

What if you have something it doesn't highlight for you? Like D? :-)
 I'd rather the source
 look good out of the box than having to define dozens of macros to make it look
 good.

The point is, you can customize the macros to match the semantic content of your documentation. It is not necessarily a low level thing. For example, I might want to document a library function like this: $(RTLENTRY name, $(HEADER name.h) $(PROTOTYPE void name(); ) $(DESCRIPTION name() is the greatest function evar! ) $(EXAMPLE name(); // great things happen ) ) Or some such. Then, by manipulating the definitions of those macros, I can generate all kinds of different markup. I could set it up as h4's, h3's, tables, definition lists, etc. I could use a code font for HEADER, and regular font for DESCRIPTION. If I used a markup language with no symbolic ability, I would have to re-edit everything to change the layout of the output. This isn't just pie in the sky. I really do write Ddoc stuff like this, and really do change the layouts searching for something that is more pleasing.
Jun 30 2011
parent reply KennyTM~ <kennytm gmail.com> writes:
On Jun 30, 11 18:25, Walter Bright wrote:
 On 6/30/2011 1:26 AM, KennyTM~ wrote:
 Right, it's possible, but it is ugly. Isn't the point to show the syntax
 "easier, nicer, and more productive"?

Ddoc has pretty much only one syntax. Sphinx seems to have a lot of them.

OK, if that's a concern.
 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?

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

What's natural about that?
 In DDoc you have to write $(LINK2 foo.html#bar, bar).

No, you don't have to. I'll often write it as: $(CHAPTER foo, bar)

The 'foo' is still here. By natural I mean once you have a 'bar', you often don't need to care about the 'foo'. Also, in d-programming-language.org $(LINK2 x.html#y, y) is used, but $(CHAPTER x, y) does not exist.
 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.

Yes, the idea that a link may be somewhere in a collection files, is probably better.
 And what if, for the unordered list, you wish to add a "class=foo"
 attribute for one of them, and "class=bar" for another?


Style sheets. For example, sometimes you want a list to go out horizontally rather than vertically; this is controlled by the style sheet. You specify a class for the list, and then the layout for that class.

OK.
 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

This I don't particularly like. I've got to learn a new syntax for it, I've got to read and learn a manual on what 'class' means for Sphinx and do some spelunking to figure out if it is the same thing as an html class or something different. The syntax arguably isn't better, either. It's just different. Even worse, if I want to change the classes, I've got to do a global search/replace. With Ddoc, I change one macro.

You don't have to use '.. class::'! Directives can be manually-defined also. I'm just illustrating this is possible with the requirement 'you wish to add a "class=foo" attribute for one of them, and "class=bar" for another?' (Also I didn't say _you_ have to learn reST. For instance, the site could be maintained by some other people in Digital Mars or the D "committee".)
 With Ddoc, you can read the HTML manual and apply it directly to Ddoc.
 Ddoc doesn't even know what HTML is, so it has no need to replicate its
 functionality in a same-only-different manner.

Neither does Sphinx. '.. class::' is not tied to HTML either.
 HTML has lots of these attributes. Are they *all* in Sphinx? What if a
 new one is added to HTML? What if I want to use :: in my text? One
 problem with a lot of text markup is you've got to provide escapes for
 all that - which is why Ddoc pretty much sticks to $.

If you need all of these attributes, why not use raw HTML (yes there is '.. raw::')? Besides, the output may not be HTML. Sphinx supports LaTeX, ePub, man page, texinfo, etc. That should also be the same for Ddoc. You can '::' escape it as ':\:', and '::' is special only at the end of a line. In Ddoc there is $(LPAREN) and $(RPAREN) and &amp; also.
 In Ddoc, for another example, I did the documentation for the Digital
 Mars C++ runtime library. For web pages, I formatted things using
 definition lists. Unfortunately, those came out badly in the Kindle, but
 using h4 instead worked much better. Since I had written the docs in
 terms of a higher level Ddoc macro, I simply changed its definition to
 use h4 instead of dl, and voila! thousands of library functions got
 fixed without incredibly tediously recoding each one.

 For me, a viable doc system needs to have some sort of symbolic
 redefinition capability. Textual macro processors have existed for a
 long time, and they work well for that, which is why Ddoc went that
 direction. (You might notice that Ddoc macros are a lot like makefile
 macros!)

OK.
 (I did consider using the C macro preprocessor, but it is too
 specialized for C.)


 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.

'.. class::' directive to assign classes,

Do I gotta do that every time I write a CPPCODE section?

How is '.. class:: cppcode' different from '$(CPPCODE x)' in terms of redundancy?
 and it's also possible to write your own
 directive or inline marker,

That would be better.
 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.

The default works well 95% of the time. The rest of the time it doesn't, and if you have to leave the documentation system, it really sucks.
 Furthermore, Sphinx has the '.. code-block::' directive to even syntax
 highlight
 those C and C++ code for you.

What if you have something it doesn't highlight for you? Like D? :-)

You contribute to Pygment! :) BTW it *does* highlight D. See http://pygments.org/languages/ for the support. OTOH, DDoc doesn't highlight anything besides D (not that it's an advantage in this context).
 I'd rather the source
 look good out of the box than having to define dozens of macros to
 make it look
 good.

The point is, you can customize the macros to match the semantic content of your documentation. It is not necessarily a low level thing. For example, I might want to document a library function like this: $(RTLENTRY name, $(HEADER name.h) $(PROTOTYPE void name(); ) $(DESCRIPTION name() is the greatest function evar! ) $(EXAMPLE name(); // great things happen ) ) Or some such. Then, by manipulating the definitions of those macros, I can generate all kinds of different markup. I could set it up as h4's, h3's, tables, definition lists, etc. I could use a code font for HEADER, and regular font for DESCRIPTION.

Yes. But as I've argued before, you can't highlight code in $(EXAMPLE a) without relying on Javascript or other run-time solution.
 If I used a markup language with no symbolic ability, I would have to
 re-edit everything to change the layout of the output.

 This isn't just pie in the sky. I really do write Ddoc stuff like this,
 and really do change the layouts searching for something that is more
 pleasing.

Yes.
Jun 30 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 6:28 AM, KennyTM~ wrote:
 No, you don't have to. I'll often write it as:

 $(CHAPTER foo, bar)

The 'foo' is still here. By natural I mean once you have a 'bar', you often don't need to care about the 'foo'.

Right, I agreed that Sphinx does better with that detail.
 Also, in d-programming-language.org $(LINK2
 x.html#y, y) is used, but $(CHAPTER x, y) does not exist.

Right, but defining your own macros is completely trivial, and when using Ddoc for more than a few lines, I'd expect one to define helpful macros specific to what you're writing. If you're going to avoid writing such macros, then writing Ddoc source is probably going to be clumsy. It's just not meant to be used that way - like trying to write C code without writing any functions other than main().
 With Ddoc, you can read the HTML manual and apply it directly to Ddoc.
 Ddoc doesn't even know what HTML is, so it has no need to replicate its
 functionality in a same-only-different manner.

Neither does Sphinx. '.. class::' is not tied to HTML either.

I think you misunderstood me. I meant I don't have to learn a separate-but-equal markup language. If I know html, then using Ddoc is a no-brainer to use. If you need more than a few minutes to get the hang of it, something is wrong. Maybe if you're unfamiliar with text macros, but I can't see a person competent to write programming manuals not knowing them. Expecting someone who's expertise is flower arranging to learn/use Ddoc is likely a hopeless task.
 If you need all of these attributes, why not use raw HTML (yes there is '..
 raw::')?

Because writing HTML more than once is a giant annoying pain. With Ddoc, I hide those naughty bits in a macro, then use the macro.
 How is '.. class:: cppcode' different from '$(CPPCODE x)' in terms of
redundancy?

Since CPPCODE is a macro, it can expand to anything. I can use it to set the html tag, font, color, size, class, whatever. And, I can *change* it globally by changing the macro, not by editing each instance. It's the same rationale for why we have user-defined aliases, classes, and functions in programming languages. I think I've completely failed to make that point.
 What if you have something it doesn't highlight for you? Like D? :-)


:-(
 BTW it *does* highlight D. See http://pygments.org/languages/ for the support.

And when D gets a new keyword? Everyone has to wait for the next upgrade cycle of Sphinx. With Ddoc, it's automatic.
 OTOH, DDoc doesn't highlight anything besides D (not that it's an advantage in
 this context).

That's right.
Jun 30 2011
parent KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 03:10, Walter Bright wrote:
 On 6/30/2011 6:28 AM, KennyTM~ wrote:
 No, you don't have to. I'll often write it as:

 $(CHAPTER foo, bar)

The 'foo' is still here. By natural I mean once you have a 'bar', you often don't need to care about the 'foo'.

Right, I agreed that Sphinx does better with that detail.
 Also, in d-programming-language.org $(LINK2
 x.html#y, y) is used, but $(CHAPTER x, y) does not exist.

Right, but defining your own macros is completely trivial, and when using Ddoc for more than a few lines, I'd expect one to define helpful macros specific to what you're writing. If you're going to avoid writing such macros, then writing Ddoc source is probably going to be clumsy. It's just not meant to be used that way - like trying to write C code without writing any functions other than main().

Right. Perhaps d-p-l.org should replace those $(LINK2 x#y, z) by $(CHAPTER x, y, z) also. (or $(SECTION x, y, z) depending on what y is).
 With Ddoc, you can read the HTML manual and apply it directly to Ddoc.
 Ddoc doesn't even know what HTML is, so it has no need to replicate its
 functionality in a same-only-different manner.

Neither does Sphinx. '.. class::' is not tied to HTML either.

I think you misunderstood me. I meant I don't have to learn a separate-but-equal markup language. If I know html, then using Ddoc is a no-brainer to use. If you need more than a few minutes to get the hang of it, something is wrong. Maybe if you're unfamiliar with text macros, but I can't see a person competent to write programming manuals not knowing them. Expecting someone who's expertise is flower arranging to learn/use Ddoc is likely a hopeless task.
 If you need all of these attributes, why not use raw HTML (yes there
 is '..
 raw::')?

Because writing HTML more than once is a giant annoying pain. With Ddoc, I hide those naughty bits in a macro, then use the macro.
 How is '.. class:: cppcode' different from '$(CPPCODE x)' in terms of
 redundancy?

Since CPPCODE is a macro, it can expand to anything. I can use it to set the html tag, font, color, size, class, whatever. And, I can *change* it globally by changing the macro, not by editing each instance. It's the same rationale for why we have user-defined aliases, classes, and functions in programming languages. I think I've completely failed to make that point.

OK. I agree DDoc make a very easy to define and change a macro, but this isn't a unique capability of DDoc. (Also you write your own '.. cppcode::', as I've said before. It's just not as straight-forward as DDoc :) )
 What if you have something it doesn't highlight for you? Like D? :-)


:-(
 BTW it *does* highlight D. See http://pygments.org/languages/ for the
 support.

And when D gets a new keyword? Everyone has to wait for the next upgrade cycle of Sphinx. With Ddoc, it's automatic.

If D can get a new keyword we won't see 'inout(T)' and 'auto ref' and 'final switch' and all overloads of 'static' ;-) And missing a few keywords (say, __gshared) isn't fatal.
 OTOH, DDoc doesn't highlight anything besides D (not that it's an
 advantage in
 this context).

That's right.

(actually I wanted to write "not that it's _a disadvantage_ in this context". My mind lost in the double negativeness :) )
Jun 30 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 1:26 AM, KennyTM~ wrote:
 Yes it is supported by Sphinx with the :ref:`target` syntax.

Take a look at this: http://sphinx.pocoo.org/rest.html#tables +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | ... | ... | | +------------------------+------------+----------+----------+ I originally did think about doing this for tables in Ddoc. But although it looks reasonable, it is unbearably tedious to actually have to type in a complex table like this, and even worse to try and change such a table. Have you ever tried it? I have. Awful. Try writing 50 different tables that way. Next, look at: http://sphinx.pocoo.org/rest.html#sections •# with overline, for parts •* with overline, for chapters •=, for sections •-, for subsections •^, for subsubsections •", for paragraphs I challenge anyone to remember this table. Heck, I can't even remember the C operator precedence table 100%. And: http://sphinx.pocoo.org/rest.html#external-links .. _a link: http://example.com/ is that really better than: $(LINK2 http://example.com/, a link) ? Sphinx is a large and complex markup system that is arguably as much to learn as HTML is - and I still need to learn HTML. Everything in Sphinx seems to have a special syntax, while Ddoc has a single syntax. Sphinx has some nice things, like the automatic connecting of links. But I don't find it, on the whole, better. Granted, I haven't actually used it and might think differently if I did. If Sphinx was the industry standard that everyone uses, that might make it compelling in spite of its problems. But it isn't, I'd never heard of it before your links. (Of course, that might just mean I'm living under a rock!) I've seen all kinds of markup languages, starting with runoff in the 70s. I'm modestly familiar with runoff (did a term paper with it! that was the end of my typewriter), unix man, mediawiki, other wiki markups, reddit markup, javadoc, doxygen, Latex, html (of course), the crazy formats used in various web forums, etc.
Jun 30 2011
next sibling parent bearophile <bearophileHUGS lycos.com> writes:
Walter:

 If Sphinx was the industry standard that everyone 
 uses, that might make it compelling in spite of its problems. But it isn't,
I'd 
 never heard of it before your links. (Of course, that might just mean I'm
living 
 under a rock!)

Sphinx is kind of new, but it's used for Python docs and elsewhere. Sphinx is based on ReST, that is not new and is "widely" used: http://en.wikipedia.org/wiki/ReStructuredText Bye, bearophile
Jun 30 2011
prev sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Jun 30, 11 18:50, Walter Bright wrote:
 On 6/30/2011 1:26 AM, KennyTM~ wrote:
 Yes it is supported by Sphinx with the :ref:`target` syntax.

Take a look at this: http://sphinx.pocoo.org/rest.html#tables +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | ... | ... | | +------------------------+------------+----------+----------+ I originally did think about doing this for tables in Ddoc. But although it looks reasonable, it is unbearably tedious to actually have to type in a complex table like this, and even worse to try and change such a table. Have you ever tried it? I have. Awful. Try writing 50 different tables that way.

Right. I agree this is one disadvantage in authoring the document. Although, in terms of readability, this is much better than $(TABLE $(TR $(TH Header) $(TH Header2) ) $(TR $(TD Body1) ... ) ... )
 Next, look at:

 http://sphinx.pocoo.org/rest.html#sections

 •# with overline, for parts
 •* with overline, for chapters
 •=, for sections
 •-, for subsections
 •^, for subsubsections
 •", for paragraphs

 I challenge anyone to remember this table. Heck, I can't even remember
 the C operator precedence table 100%.

That's incorrect. Please read the paragraph above it. Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, this *convention* is used which you may follow:
 And:

 http://sphinx.pocoo.org/rest.html#external-links

 .. _a link: http://example.com/

 is that really better than:

 $(LINK2 http://example.com/, a link)

 ?

Some people may think it is, I don't, but you could write it as `a link <http://example.com/>`_
 Sphinx is a large and complex markup system that is arguably as much to
 learn as HTML is - and I still need to learn HTML. Everything in Sphinx
 seems to have a special syntax, while Ddoc has a single syntax.

 Sphinx has some nice things, like the automatic connecting of links. But
 I don't find it, on the whole, better. Granted, I haven't actually used
 it and might think differently if I did. If Sphinx was the industry
 standard that everyone uses, that might make it compelling in spite of
 its problems. But it isn't, I'd never heard of it before your links. (Of
 course, that might just mean I'm living under a rock!)

 I've seen all kinds of markup languages, starting with runoff in the
 70s. I'm modestly familiar with runoff (did a term paper with it! that
 was the end of my typewriter), unix man, mediawiki, other wiki markups,
 reddit markup, javadoc, doxygen, Latex, html (of course), the crazy
 formats used in various web forums, etc.

Jun 30 2011
next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
KennyTM~ wrote:
 Right. I agree this is one disadvantage in authoring the document.
 Although, in terms of readability, this is much better than

 $(TABLE
 $(TR
  $(TH Header)
  $(TH Header2)

Note that textual macros can do a *lot* better than this. If we take advantage of recursive template expansion.... ====== $ cat test73.d /** $(TABLE $(HEADERS Something, Something Else, Something To End) $(ROW This is it, So is this, And the third) $(ROW This is it, So is this, And the third) $(ROW This is it, So is this, And the third)) Macros: TABLE=<table>$0</table> TH=<th>$1</th>$(TH $+) HEADERS=<tr>$(TH $1, $+)</tr> TD=<td>$1</td>$(TD $+) ROW=<tr>$(TD $1, $+)</tr> */ $ dmd -D test73.d $ cat test73.html <table> <tr><th>Something</th><th>Something Else</th><th>Something To End</th></tr> <tr><td> This is it</td><td>So is this</td><td>And the third</td></tr> <tr><td> This is it</td><td>So is this</td><td>And the third</td></tr> <tr><td> This is it</td><td>So is this</td><td>And the third</td></tr></table> ======= That's fairly readable in source and generates the html needed, that looks pretty decent. The default ddoc macros need more work than ddoc itself IMO.
Jun 30 2011
next sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Jun 30, 11 22:31, Adam Ruppe wrote:
 KennyTM~ wrote:
 Right. I agree this is one disadvantage in authoring the document.
 Although, in terms of readability, this is much better than

 $(TABLE
 $(TR
   $(TH Header)
   $(TH Header2)

Note that textual macros can do a *lot* better than this. If we take advantage of recursive template expansion.... ====== $ cat test73.d /** $(TABLE $(HEADERS Something, Something Else, Something To End) $(ROW This is it, So is this, And the third) $(ROW This is it, So is this, And the third) $(ROW This is it, So is this, And the third)) Macros: TABLE=<table>$0</table> TH=<th>$1</th>$(TH $+) HEADERS=<tr>$(TH $1, $+)</tr> TD=<td>$1</td>$(TD $+) ROW=<tr>$(TD $1, $+)</tr> */ $ dmd -D test73.d $ cat test73.html <table> <tr><th>Something</th><th>Something Else</th><th>Something To End</th></tr> <tr><td> This is it</td><td>So is this</td><td>And the third</td></tr> <tr><td> This is it</td><td>So is this</td><td>And the third</td></tr> <tr><td> This is it</td><td>So is this</td><td>And the third</td></tr></table> ======= That's fairly readable in source and generates the html needed, that looks pretty decent. The default ddoc macros need more work than ddoc itself IMO.

Interesting trick! Thanks. Indeed the default DDoc macros are not very good, e.g. having no inline code format ($(D x) in Phobos), and relying on the presentational aspect of HTML (e.g. DDOC_BUGS = $(RED BUGS:)$(BR)$0$(BR)$(BR)), etc.
Jun 30 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 7:50 AM, KennyTM~ wrote:
 Interesting trick! Thanks. Indeed the default DDoc macros are not very good,
 e.g. having no inline code format ($(D x) in Phobos), and relying on the
 presentational aspect of HTML (e.g. DDOC_BUGS = $(RED BUGS:)$(BR)$0$(BR)$(BR)),
 etc.

I wanted the default macros to not rely on having a style sheet.
Jun 30 2011
parent KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 02:48, Walter Bright wrote:
 On 6/30/2011 7:50 AM, KennyTM~ wrote:
 Interesting trick! Thanks. Indeed the default DDoc macros are not very
 good,
 e.g. having no inline code format ($(D x) in Phobos), and relying on the
 presentational aspect of HTML (e.g. DDOC_BUGS = $(RED
 BUGS:)$(BR)$0$(BR)$(BR)),
 etc.

I wanted the default macros to not rely on having a style sheet.

The default $(DDOC) could have an embedded <style>-sheet.
Jun 30 2011
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 7:31 AM, Adam Ruppe wrote:
 If we take advantage of recursive template expansion....

I worked pretty hard on getting recursion right on the templates. There are a number of subtleties on it; I had the advantage of doing macro systems before and know how to do it. You can use it a lot like car/cdr in Lisp, which you show with your table macro, which is better than mine.
Jun 30 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 7:31 AM, Adam Ruppe wrote:
          Macros:
                  TABLE=<table>$0</table>

                  TH=<th>$1</th>$(TH $+)
                  HEADERS=<tr>$(TH $1, $+)</tr>

                  TD=<td>$1</td>$(TD $+)
                  ROW=<tr>$(TD $1, $+)</tr>

Your idea also works for lists: $(UL $(LI item 1) $(LI item 2) ) now becomes: $(LIST item 1, item 2 ) where: LI=<li>$1</li>$(LI $+) LIST=$(UL $(LI $1, $+))
Jul 02 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 7/2/11 11:39 PM, Walter Bright wrote:
 On 6/30/2011 7:31 AM, Adam Ruppe wrote:
 Macros:
 TABLE=<table>$0</table>

 TH=<th>$1</th>$(TH $+)
 HEADERS=<tr>$(TH $1, $+)</tr>

 TD=<td>$1</td>$(TD $+)
 ROW=<tr>$(TD $1, $+)</tr>

Your idea also works for lists: $(UL $(LI item 1) $(LI item 2) ) now becomes: $(LIST item 1, item 2 ) where: LI=<li>$1</li>$(LI $+) LIST=$(UL $(LI $1, $+))

Excellent idea. To complement it, we need a "text with commas" kind of thing so we don't need to insert $(COMMA) in longer list items: TXT = $0 $(LIST $(TXT stuff, with, commas), stuff without commas, $(TXT got, the, idea) ) Works? Andrei
Jul 02 2011
next sibling parent KennyTM~ <kennytm gmail.com> writes:
On Jul 3, 11 13:34, Andrei Alexandrescu wrote:
 On 7/2/11 11:39 PM, Walter Bright wrote:
 On 6/30/2011 7:31 AM, Adam Ruppe wrote:
 Macros:
 TABLE=<table>$0</table>

 TH=<th>$1</th>$(TH $+)
 HEADERS=<tr>$(TH $1, $+)</tr>

 TD=<td>$1</td>$(TD $+)
 ROW=<tr>$(TD $1, $+)</tr>

Your idea also works for lists: $(UL $(LI item 1) $(LI item 2) ) now becomes: $(LIST item 1, item 2 ) where: LI=<li>$1</li>$(LI $+) LIST=$(UL $(LI $1, $+))

Excellent idea. To complement it, we need a "text with commas" kind of thing so we don't need to insert $(COMMA) in longer list items: TXT = $0 $(LIST $(TXT stuff, with, commas), stuff without commas, $(TXT got, the, idea) ) Works? Andrei

There should be a DIP or Bugzilla to summarize all these improvements :)
Jul 02 2011
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 7/2/2011 10:34 PM, Andrei Alexandrescu wrote:
 Excellent idea. To complement it, we need a "text with commas" kind of thing so
 we don't need to insert $(COMMA) in longer list items:

 TXT = $0

 $(LIST
 $(TXT stuff, with, commas),
 stuff without commas,
 $(TXT got, the, idea)
 )

 Works?

Yes, that works. I've been using ARGS for that! But the name isn't important.
Jul 03 2011
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
Andrei wrote:
 Works?

Yes, I like this a lot. The same technique can be used on any kind of list: $(TAGS sorting, searching) $(SEE_ALSO std.algorithm.sort, std.algorithm.indexOf, std.algorithm.canFind) Which expand to links inside a div for the macro or something so an xml processor can pull them out of the result too. (I like the color section labels for text, but for see also, I now think one of these list macros is a better fit.)
Jul 03 2011
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 7:05 AM, KennyTM~ wrote:
 Right. I agree this is one disadvantage in authoring the document. Although, in
 terms of readability, this is much better than

 $(TABLE
 $(TR
 $(TH Header)
 $(TH Header2)
 )
 $(TR
 $(TD Body1)
 ...
 )
 ...
 )

I've actually been using different macros for that now, and it looks like: $(TABLE $(TH2 Header, Header2) $(TR2 Body1, Body2) ) which works and looks reasonable. In fact, I'll often just write it as: $(TABLE Header, Header2 Body1, Body2 ) and use a trivial microemacs macro to fill in the rest. Handy when you've got 50 lines or so to do.
 Next, look at:

 http://sphinx.pocoo.org/rest.html#sections

 •# with overline, for parts
 •* with overline, for chapters
 •=, for sections
 •-, for subsections
 •^, for subsubsections
 •", for paragraphs

 I challenge anyone to remember this table. Heck, I can't even remember
 the C operator precedence table 100%.

That's incorrect. Please read the paragraph above it.

Ok, my bad.
 http://sphinx.pocoo.org/rest.html#external-links

 .. _a link: http://example.com/

 is that really better than:

 $(LINK2 http://example.com/, a link)

 ?

Some people may think it is, I don't, but you could write it as `a link <http://example.com/>`_

I find the back ticks and _ parts of the syntax wacky and underwhelming. Back ticks are used for D raw string literals, and I now think that was a mistake.
Jun 30 2011
parent reply "Nick Sabalausky" <a a.a> writes:
"Walter Bright" <newshound2 digitalmars.com> wrote in message 
news:iuig3e$2m1k$1 digitalmars.com...
 Back ticks are used for D raw string literals, and I now think that was a 
 mistake.

What would you have used instead?
Jun 30 2011
next sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 03:27, Nick Sabalausky wrote:
 "Walter Bright"<newshound2 digitalmars.com>  wrote in message
 news:iuig3e$2m1k$1 digitalmars.com...
   >
 Back ticks are used for D raw string literals, and I now think that was a
 mistake.

What would you have used instead?

There is r"..." which is equivalent to `...`. I've only used `...`.
Jun 30 2011
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"KennyTM~" <kennytm gmail.com> wrote in message 
news:iuik51$2t5s$2 digitalmars.com...
 On Jul 1, 11 03:27, Nick Sabalausky wrote:
 "Walter Bright"<newshound2 digitalmars.com>  wrote in message
 news:iuig3e$2m1k$1 digitalmars.com...
   >
 Back ticks are used for D raw string literals, and I now think that was 
 a
 mistake.

What would you have used instead?

There is r"..." which is equivalent to `...`. I've only used `...`.

That's not equivalent. The r"..." can't have a double-quote inside it, so it's only a half-way solution, and is probably why no one really uses it (At least that's why I never use it).
Jun 30 2011
parent "Nick Sabalausky" <a a.a> writes:
"Andrej Mitrovic" <andrej.mitrovich gmail.com> wrote in message 
news:mailman.1347.1309480430.14074.digitalmars-d puremagic.com...
 For ultimate escaping use:

 auto str = q"EOS
    Weeee I'm a string ""``'q{\
 EOS";

 Of course then you have to make sure 'EOS' is a unique name too. You
 could use some funky unicode character sequence for that, just to be
 sure. :p

I always forget about that one. I think "string with q" and I think "q{}-style token strings".
Jun 30 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-06-30 21:47, KennyTM~ wrote:
 On Jul 1, 11 03:27, Nick Sabalausky wrote:
 "Walter Bright"<newshound2 digitalmars.com> wrote in message
 news:iuig3e$2m1k$1 digitalmars.com...
 Back ticks are used for D raw string literals, and I now think that
 was a
 mistake.

What would you have used instead?

There is r"..." which is equivalent to `...`. I've only used `...`.

I use `...` when I need to enclose a " . -- /Jacob Carlborg
Jun 30 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 12:27 PM, Nick Sabalausky wrote:
 "Walter Bright"<newshound2 digitalmars.com>  wrote in message
 news:iuig3e$2m1k$1 digitalmars.com...
   >
 Back ticks are used for D raw string literals, and I now think that was a
 mistake.

What would you have used instead?

D has other methods for raw literals, so the ` are not only ugly, they're redundant.
Jun 30 2011
next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
Walter Bright wrote:
 D has other methods for raw literals, so the ` are not only ugly,
 they're redundant.

The best part about `` literals is you can put " inside them. You can do that with q{} too, but then the {} needs to match up which is a bit of a hassle at times.
Jun 30 2011
parent reply Timon Gehr <timon.gehr gmx.ch> writes:
Adam Ruppe wrote:
 Walter Bright wrote:
 D has other methods for raw literals, so the ` are not only ugly,
 they're redundant.

The best part about `` literals is you can put " inside them. You can do that with q{} too, but then the {} needs to match up which is a bit of a hassle at times.

There are also q"My Text{ { (} " `'?" and import("foo.txt");
Jun 30 2011
parent KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 04:34, Timon Gehr wrote:
 Adam Ruppe wrote:
 Walter Bright wrote:
 D has other methods for raw literals, so the ` are not only ugly,
 they're redundant.

The best part about `` literals is you can put " inside them. You can do that with q{} too, but then the {} needs to match up which is a bit of a hassle at times.

There are also q"°My Text{ { (} " `'?°" and import("foo.txt");

Let's replace `...` with q"`...`" ;-)
Jun 30 2011
prev sibling next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to get raw 
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile
Jun 30 2011
next sibling parent reply simendsjo <simendsjo gmail.com> writes:
On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...
Jun 30 2011
parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel
Jun 30 2011
next sibling parent reply simendsjo <simendsjo gmail.com> writes:
On 30.06.2011 23:45, Daniel Gibson wrote:
 Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

I need it for my language, but very rarely, so I wouldn't miss it much. I haven't heard of this before, but I'll try to search around for solutions for windows. Thanks for the tip.
Jun 30 2011
parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 23:58, schrieb simendsjo:
 On 30.06.2011 23:45, Daniel Gibson wrote:
 Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

I need it for my language, but very rarely, so I wouldn't miss it much. I haven't heard of this before, but I'll try to search around for solutions for windows. Thanks for the tip.

Maybe there is a solution to enable and disable them with a keyboard shortcut. I guess this is not only a problem for backticks but also for ~ and ^ (which may be more useful for everyday programming), so a way to disable/enable dead keys on the fly is probably really useful. Cheers, - Daniel
Jun 30 2011
parent reply simendsjo <simendsjo gmail.com> writes:
On 01.07.2011 00:03, Daniel Gibson wrote:
 Am 30.06.2011 23:58, schrieb simendsjo:
 On 30.06.2011 23:45, Daniel Gibson wrote:
 Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

I need it for my language, but very rarely, so I wouldn't miss it much. I haven't heard of this before, but I'll try to search around for solutions for windows. Thanks for the tip.

Maybe there is a solution to enable and disable them with a keyboard shortcut. I guess this is not only a problem for backticks but also for ~ and ^ (which may be more useful for everyday programming), so a way to disable/enable dead keys on the fly is probably really useful. Cheers, - Daniel

~ is Ctrl+Alt+~+Space ^ is Shift+^+Space { is Ctrl+Alt+{ [ is Ctrl+Alt+[ ( is Shift+( ~ is the most tedious as D uses it a lot.. 4 key presses. I've seriously thought about changing to an programmer or English layout while programming..
Jun 30 2011
parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 01.07.2011 00:12, schrieb simendsjo:
 On 01.07.2011 00:03, Daniel Gibson wrote:
 Am 30.06.2011 23:58, schrieb simendsjo:
 On 30.06.2011 23:45, Daniel Gibson wrote:
 Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

I need it for my language, but very rarely, so I wouldn't miss it much. I haven't heard of this before, but I'll try to search around for solutions for windows. Thanks for the tip.

Maybe there is a solution to enable and disable them with a keyboard shortcut. I guess this is not only a problem for backticks but also for ~ and ^ (which may be more useful for everyday programming), so a way to disable/enable dead keys on the fly is probably really useful. Cheers, - Daniel

~ is Ctrl+Alt+~+Space ^ is Shift+^+Space { is Ctrl+Alt+{ [ is Ctrl+Alt+[ ( is Shift+( ~ is the most tedious as D uses it a lot.. 4 key presses.

My keyboard (german layout) has an "Alt Gr" key. So for me it's AltGr+~ for ~ (and, if dead keys are enabled, +space additionally) etc.
 I've seriously thought about changing to an programmer or English layout
 while programming..

Me too, but I didn't really get used to it. But then again, the AltGr combinations are still somehow bearable, while ctrl-alt combinations sound quite annoying.
Jun 30 2011
parent simendsjo <simendsjo gmail.com> writes:
On 01.07.2011 00:18, Daniel Gibson wrote:
 Am 01.07.2011 00:12, schrieb simendsjo:
 On 01.07.2011 00:03, Daniel Gibson wrote:
 Am 30.06.2011 23:58, schrieb simendsjo:
 On 30.06.2011 23:45, Daniel Gibson wrote:
 Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

I need it for my language, but very rarely, so I wouldn't miss it much. I haven't heard of this before, but I'll try to search around for solutions for windows. Thanks for the tip.

Maybe there is a solution to enable and disable them with a keyboard shortcut. I guess this is not only a problem for backticks but also for ~ and ^ (which may be more useful for everyday programming), so a way to disable/enable dead keys on the fly is probably really useful. Cheers, - Daniel

~ is Ctrl+Alt+~+Space ^ is Shift+^+Space { is Ctrl+Alt+{ [ is Ctrl+Alt+[ ( is Shift+( ~ is the most tedious as D uses it a lot.. 4 key presses.

My keyboard (german layout) has an "Alt Gr" key. So for me it's AltGr+~ for ~ (and, if dead keys are enabled, +space additionally) etc.
 I've seriously thought about changing to an programmer or English layout
 while programming..

Me too, but I didn't really get used to it. But then again, the AltGr combinations are still somehow bearable, while ctrl-alt combinations sound quite annoying.

I have a norwegian layout, but I think it's quite similar. For ~ I can use AltGr, but for { I need to bend my hand halfway around. I've been doing this for years, and it's straining my hands. So I've started using C-A in many cases to avoid this - in addition to switching to dvorak.
Jun 30 2011
prev sibling parent Mike Wey <mike-wey example.com> writes:
On 06/30/2011 11:45 PM, Daniel Gibson wrote:
 Am 30.06.2011 23:41, schrieb simendsjo:
 On 30.06.2011 23:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

And if you still need some accents you can enable the compose key: http://www.hermit.org/Linux/ComposeKeys.html -- Mike Wey
Jul 02 2011
prev sibling next sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)
Jun 30 2011
next sibling parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O
Jun 30 2011
next sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 05:52, Daniel Gibson wrote:
 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

That's why C has trigraphs! (yuck)
Jun 30 2011
parent Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 23:57, schrieb KennyTM~:
 On Jul 1, 11 05:52, Daniel Gibson wrote:
 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

That's why C has trigraphs! (yuck)

Right, totally forgot those. Is this still a problem with recent keyboards (of any layout)? I thought it was only a problem in the 70ies or so.
Jun 30 2011
prev sibling parent reply simendsjo <simendsjo gmail.com> writes:
On 01.07.2011 00:49, Simen Kjaeraas wrote:
 On Thu, 30 Jun 2011 23:52:38 +0200, Daniel Gibson
 <metalcaedes gmail.com> wrote:

 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

And standard Norwegian layout has them on AltGr+8/9. The pain. But using US int'l has the added advantage of confusing the hell out of my cow-orkers when they try to use my confuser (which has thus earned that title :p).

Switch to programmer dvorak and they'll never touch your computer again.
Jun 30 2011
next sibling parent reply simendsjo <simendsjo gmail.com> writes:
On 01.07.2011 02:19, Jonathan M Davis wrote:
 On 2011-06-30 15:59, simendsjo wrote:
 On 01.07.2011 00:49, Simen Kjaeraas wrote:
 On Thu, 30 Jun 2011 23:52:38 +0200, Daniel Gibson

 <metalcaedes gmail.com>  wrote:
 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:
 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

And standard Norwegian layout has them on AltGr+8/9. The pain. But using US int'l has the added advantage of confusing the hell out of my cow-orkers when they try to use my confuser (which has thus earned that title :p).

Switch to programmer dvorak and they'll never touch your computer again.

I switched to dvorak _and_ got one of these: http://www.kinesis- ergo.com/advantage.htm No one is going to be using my computer with my keyboard. Though honestly, as much as I like dvorak, I wouldn't advise that anyone switch to it. Too many programs assume qwerty, so all of their shortcuts are designed for it. Stuff like the shortcuts for cut, copy, and paste are on completely different places on the keyboard and don't work as well (only cut can be done with just your left hand). I had to completely remap vim to be able to use it. Other programs need their keys or shortcuts remapped to work very well. It just causes problems for stuff that assumes qwerty. So, it's likely more pain than its worth. My keyboard is awesome regardless of whether you use qwerty or dvork though. I can actually type numbers on it without looking, which I could never do on a normal keyboard, because the keys aren't vertically aligned on a normal keyboard. It's expensive, but I'm quite happy that I bought it. - Jonathan M Davis

Looks ergonomically "correct", but pretty massive. I've considered TypeMatrix (http://typematrix.com/) in the past, but I think it's a bit expensive. As for dvorak, I'm not quite sure. The keybindings haven't been a large problem for me. Most programs have mappings based on the name of the function (o for open), and this isn't a problem. The only vim "problems" is movement which now requires two hands - but I decided not to remap, and it hasn't been a problem. Games on the other hand :) I still switched quite recently, and type very slowly. And my hands actually hurt more - probably because I'm not used to it. I'm hoping that dvorak will help on strain in the long run though..
Jun 30 2011
parent reply Jacob Carlborg <doob me.com> writes:
On 2011-07-01 02:29, simendsjo wrote:
 Looks ergonomically "correct", but pretty massive. I've considered
 TypeMatrix (http://typematrix.com/) in the past, but I think it's a bit
 expensive.

I've never understood how keyboards with keys sitting almost vertical can be ergonomically correct. It's like pressing keys sitting on a wall. -- /Jacob Carlborg
Jul 01 2011
parent simendsjo <simendsjo gmail.com> writes:
On 01.07.2011 11:33, Jacob Carlborg wrote:
 On 2011-07-01 02:29, simendsjo wrote:
 Looks ergonomically "correct", but pretty massive. I've considered
 TypeMatrix (http://typematrix.com/) in the past, but I think it's a bit
 expensive.

I've never understood how keyboards with keys sitting almost vertical can be ergonomically correct. It's like pressing keys sitting on a wall.

I know. It looks very wrong in this regard. But I like the placement of other keys like enter and backspace.
Jul 01 2011
prev sibling next sibling parent "Nick Sabalausky" <a a.a> writes:
"simendsjo" <simendsjo gmail.com> wrote in message 
news:iuivd2$2sat$3 digitalmars.com...
 On 01.07.2011 00:49, Simen Kjaeraas wrote:
 And standard Norwegian layout has them on AltGr+8/9. The pain.
 But using US int'l has the added advantage of confusing the hell out
 of my cow-orkers when they try to use my confuser (which has thus earned
 that title :p).

Switch to programmer dvorak and they'll never touch your computer again.

Years ago I started getting some minor wrist pain, so I switched to a trackball instead of a mouse (this one: http://www.amazon.com/Logitech-Trackman-Wheel-Optical-Silver/dp/B00005NIMJ I don't know why it's so expensive on Amazon, they're only about $35 in stores.) Took a couple days to get used to it, and a couple weeks for it to feel 100% natural and be 100% proficient, but it's been well worth it: I love it and haven't had any wrist pain since. (And spinning the wheel's just damn fun :) ) At an old job I had, I bought another of those trackballs to use at work. Anytime anyone tried to lean over and do anything on my computer they compained about "How can you use this thing?" :) The real interesting thing though, is that they *always* reached straight for the trackball *despite* the fact that I also had a mouse plugged in, sitting right out in plain view.
Jun 30 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-07-01 02:19, Jonathan M Davis wrote:
 I switched to dvorak _and_ got one of these: http://www.kinesis-
 ergo.com/advantage.htm

 No one is going to be using my computer with my keyboard. Though honestly, as
 much as I like dvorak, I wouldn't advise that anyone switch to it. Too many
 programs assume qwerty, so all of their shortcuts are designed for it. Stuff
 like the shortcuts for cut, copy, and paste are on completely different places
 on the keyboard and don't work as well (only cut can be done with just your
 left hand). I had to completely remap vim to be able to use it. Other programs
 need their keys or shortcuts remapped to work very well. It just causes
 problems for stuff that assumes qwerty. So, it's likely more pain than its
 worth. My keyboard is awesome regardless of whether you use qwerty or dvork
 though. I can actually type numbers on it without looking, which I could never
 do on a normal keyboard, because the keys aren't vertically aligned on a
 normal keyboard. It's expensive, but I'm quite happy that I bought it.

 - Jonathan M Davis

Using this keyboard: http://www.typematrix.com with the dvorak layout you can use other keys then ctrl+x/c/v for cut, copy and paste. If you look in the store, and choose "Skin Only" and then dvorka you can see it has keys for cut, copy and paste in similar places where ctrl+x/c/v would be on a normal keyboard. -- /Jacob Carlborg
Jul 01 2011
prev sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
KennyTM~:

 (I know some keyboard doesn't have '[' and ']'. So having no '`' 
 shouldn't be the reason it is removed from the language.)

Even keyboards that don't have [] as first keys, have them printed on the keys as alternative symbols, because they are Far more commonly needed than backticks. Bye, bearophile
Jun 30 2011
parent reply David Nadlinger <see klickverbot.at> writes:
On 7/1/11 12:16 AM, bearophile wrote:
 Even keyboards that don't have [] as first keys, have them printed on the keys
as alternative symbols, because they are Far more commonly needed than
backticks.

Unless you are using a QWERTZ mac keyboard. :) David
Jun 30 2011
parent Daniel Gibson <metalcaedes gmail.com> writes:
Am 01.07.2011 00:28, schrieb David Nadlinger:
 On 7/1/11 12:16 AM, bearophile wrote:
 Even keyboards that don't have [] as first keys, have them printed on
 the keys as alternative symbols, because they are Far more commonly
 needed than backticks.

Unless you are using a QWERTZ mac keyboard. :) David

OMG. I didn't wanna believe it, but http://upload.wikimedia.org/wikipedia/commons/1/10/2007_09_30_de_Apple-Tastatur.jpg proved me wrong. The same for laptops ( http://www.elektro-export.de/epages/es114318.sf/de_AT/?ObjectPath=/Shops/es114318_Elektro-Export/Products/KB-APPLE04[1] ) No [], no {}.. WTF. This is the most ridiculous fact I've heard about Apple products so far.. just unbelievable. Cheers, - Daniel
Jun 30 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 2:39 PM, bearophile wrote:
 I don't have backticks on my keyboard,

I got a keyboard from the thrift shop for a buck. It has `.
Jun 30 2011
parent Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 23:51, schrieb Walter Bright:
 On 6/30/2011 2:39 PM, bearophile wrote:
 I don't have backticks on my keyboard,

I got a keyboard from the thrift shop for a buck. It has `.

Probably his keyboard doesn't have US layout ;)
Jun 30 2011
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 2:04 PM, Jonathan M Davis wrote:
 Actually, I find the backticks to be by far the most pleasant way to get raw
 strings in D. I don't particularly like the other syntaxes for it
 (particularly q{}). It may be that other considerations make it so that it
 would have been better not to use backticks for raw strings, but I really like
 it, and I use them all the time.

Don't worry, they're not going away!
Jun 30 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
BTW, probably the biggest shortcoming of Ddoc is that its template system does 
not have conditional or looping constructs. It is not a complete programming 
language. Such could be added, but there has been no particular need for it.

Andrei surprised me by using javascript to fill that role, and perhaps that is 
good enough.
Jun 30 2011
parent reply Adam Ruppe <destructionator gmail.com> writes:
 Andrei surprised me by using javascript to fill that role, and
 perhaps that is good enough.

Or you can use D too - I made a little post-processor that parses and modifies the html to add fancier things, when needed for me. This is why I've made a few comments on making the std.ddoc macros more semanticlly rich - to make the post processor's job easier. Though, I find the straight up ddoc, even without bothering with macros at all, to be pretty much good enough for the main goal of documenting functions. Being easy and simple is more important to me than being fancy.
Jun 30 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 12:22 PM, Adam Ruppe wrote:
 Being easy and simple is more important to me than being fancy.

Exactly. Having every "would be nice if" feature can just sink a project with it's dead weight. Back in the 80's, the company I worked for bought a profiling tool for C. Nobody ever used it. I figured part of the problem was the manual was an inch thick. That simply discouraged anyone from bothering to invest the effort to learn it. That's why the profiler for dmd is: dmd foo.d -profile Sadly, still nobody uses the profiler. Reminds me of a Bjarne Stroustrup comment when he joked that decades ago, he imagined that it would be great if using a computer were as simple as using a phone. He said that dream came true :-)
Jun 30 2011
next sibling parent reply eles <eles eles.com> writes:
 Reminds me of a Bjarne Stroustrup comment when he joked that decades

 imagined that it would be great if using a computer were as simple as

 phone. He said that dream came true :-)

"I have always wished for my computer to be as easy to use as my telephone; my wish has come true because I can no longer figure out how to use my telephone."
Jun 30 2011
parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 1:27 PM, eles wrote:
 Reminds me of a Bjarne Stroustrup comment when he joked that decades

 imagined that it would be great if using a computer were as simple as

 phone. He said that dream came true :-)

"I have always wished for my computer to be as easy to use as my telephone; my wish has come true because I can no longer figure out how to use my telephone."

The correct quote is better, thanks!
Jun 30 2011
prev sibling next sibling parent bearophile <bearophileHUGS lycos.com> writes:
Walter:

 Sadly, still nobody uses the profiler.

I'm using it all the time! I'd even like a statistical profile to be added as second profiler to the standard distribution (there is one, around, for D). Bye, bearophile
Jun 30 2011
prev sibling next sibling parent reply Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 22:20, schrieb Walter Bright:
 On 6/30/2011 12:22 PM, Adam Ruppe wrote:
 Being easy and simple is more important to me than being fancy.

Exactly. Having every "would be nice if" feature can just sink a project with it's dead weight. Back in the 80's, the company I worked for bought a profiling tool for C. Nobody ever used it. I figured part of the problem was the manual was an inch thick. That simply discouraged anyone from bothering to invest the effort to learn it. That's why the profiler for dmd is: dmd foo.d -profile Sadly, still nobody uses the profiler.

Are you sure? I've used it several times. But maybe there should be an article on it or something. (On why it should be used and how this is done) Cheers, - Daniel
Jun 30 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 1:36 PM, Daniel Gibson wrote:
 Are you sure? I've used it several times.

I base that on if people were using it, there'd be lots of bug reports and enhancement requests! Does anyone use it's companion, -cov?
Jun 30 2011
next sibling parent Daniel Gibson <metalcaedes gmail.com> writes:
Am 30.06.2011 22:47, schrieb Walter Bright:
 On 6/30/2011 1:36 PM, Daniel Gibson wrote:
 Are you sure? I've used it several times.

I base that on if people were using it, there'd be lots of bug reports and enhancement requests!

Which reminds me - IIRC there were issues with multi threaded programs. But because http://www.digitalmars.com/ctg/trace.html says "Profiling of multithreaded apps is not supported." there are probably no bug reports about this - it's expected behavior. However for the profiler to be really useful (especially nowadays with multicore CPUs and std.parallelism), profiling multithreaded apps should be supported.
 
 Does anyone use it's companion, -cov?

I think I've tried it once, but didn't have too much use for it (because for optimization I care more about the output of -profile) Cheers, - Daniel
Jun 30 2011
prev sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Walter:

 I base that on if people were using it, there'd be lots of bug reports and 
 enhancement requests!

I have not needed enhancement requests for the profiler. But I'd like a statistical one added.
 Does anyone use it's companion, -cov?

I use it often, but it's buggy, you can't use it for "larger" programs. I have never nailed down in what cases it doesn't work, sorry. I have two enhancements request since some time in Bugzilla for the coverage analyser: http://d.puremagic.com/issues/show_bug.cgi?id=4153 http://d.puremagic.com/issues/show_bug.cgi?id=4718 Bye, bearophile
Jun 30 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/30/2011 2:35 PM, bearophile wrote:
 I use it often, but it's buggy, you can't use it for "larger" programs.

Bug reports?
Jun 30 2011
next sibling parent reply David Nadlinger <see klickverbot.at> writes:
On 6/30/11 11:52 PM, Walter Bright wrote:
 On 6/30/2011 2:35 PM, bearophile wrote:
 I use it often, but it's buggy, you can't use it for "larger" programs.

Bug reports?

This obviously depends on the keyboard layout one is using… David
Jun 30 2011
parent reply KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 05:54, David Nadlinger wrote:
 On 6/30/11 11:52 PM, Walter Bright wrote:
 On 6/30/2011 2:35 PM, bearophile wrote:
 I use it often, but it's buggy, you can't use it for "larger" programs.

Bug reports?

This obviously depends on the keyboard layout one is using… David

That would be a really interesting bug if the coverage analysis depends on the keyboard layout...
Jun 30 2011
next sibling parent David Nadlinger <see klickverbot.at> writes:
On 6/30/11 11:59 PM, KennyTM~ wrote:
 On Jul 1, 11 05:54, David Nadlinger wrote:
 On 6/30/11 11:52 PM, Walter Bright wrote:
 On 6/30/2011 2:35 PM, bearophile wrote:
 I use it often, but it's buggy, you can't use it for "larger" programs.

Bug reports?

This obviously depends on the keyboard layout one is using… David

That would be a really interesting bug if the coverage analysis depends on the keyboard layout...

Oh, wow, apparently I hit »reply« on the wrong post – that should go in the backticks »sub-thread«, of course. ;) David
Jun 30 2011
prev sibling parent "Nick Sabalausky" <a a.a> writes:
"KennyTM~" <kennytm gmail.com> wrote in message 
news:iuirsg$b72$1 digitalmars.com...
 On Jul 1, 11 05:54, David Nadlinger wrote:
 On 6/30/11 11:52 PM, Walter Bright wrote:
 On 6/30/2011 2:35 PM, bearophile wrote:
 I use it often, but it's buggy, you can't use it for "larger" programs.

Bug reports?

This obviously depends on the keyboard layout one is using. David

That would be a really interesting bug if the coverage analysis depends on the keyboard layout...

I agree with David, it's just totally, totally obvious how it's dependent on keyboard layout. Can't you see it? :)
Jun 30 2011
prev sibling parent bearophile <bearophileHUGS lycos.com> writes:
Walter:

 Bug reports?

A bit later I have written:
 I have never nailed down in what cases it doesn't work, sorry.

It means I was not able to find test cases where the bugs come out. To me they come out only in larger programs. Bye, bearophile
Jun 30 2011
prev sibling parent KennyTM~ <kennytm gmail.com> writes:
On Jul 1, 11 05:35, bearophile wrote:
 Walter:

 I base that on if people were using it, there'd be lots of bug reports and
 enhancement requests!

I have not needed enhancement requests for the profiler. But I'd like a statistical one added.
 Does anyone use it's companion, -cov?

I use it often, but it's buggy, you can't use it for "larger" programs. I have never nailed down in what cases it doesn't work, sorry. I have two enhancements request since some time in Bugzilla for the coverage analyser: http://d.puremagic.com/issues/show_bug.cgi?id=4153 http://d.puremagic.com/issues/show_bug.cgi?id=4718 Bye, bearophile

4718? But std.cover no longer exists in D2.
Jun 30 2011
prev sibling parent "Nick Sabalausky" <a a.a> writes:
"Walter Bright" <newshound2 digitalmars.com> wrote in message 
news:iuim2t$31ba$1 digitalmars.com...
 On 6/30/2011 12:22 PM, Adam Ruppe wrote:
 Being easy and simple is more important to me than being fancy.

Exactly. Having every "would be nice if" feature can just sink a project with it's dead weight. Back in the 80's, the company I worked for bought a profiling tool for C. Nobody ever used it. I figured part of the problem was the manual was an inch thick. That simply discouraged anyone from bothering to invest the effort to learn it. That's why the profiler for dmd is: dmd foo.d -profile Sadly, still nobody uses the profiler.

I use it. The output is initially hard to understand, though, until you 1. See an explanation of it, and 2. Actually notice that there's a timing chart way down at the bottom after all the fan-in/fan-out. Some demangling would be really nice in it though.
Jun 30 2011
prev sibling parent Adam Ruppe <destructionator gmail.com> writes:
Walter Bright wrote:
 In Ddoc, you can define your own macros to do that, for example:
     H3=<h3>$0</h3>

So, I was just writing up a complaint about ddoc's escaping of characters when I looked at doc.c and found it already had a solution... except looking at the code, it doesn't seem to be fully implemented. ======= $ cat test72.d extern(C) void printf(in char*, ...); /** Macros: ESCAPES=/a/lol */ /// this is (cool) $19 & <span> arguably wrong void main() { printf("Hello, &amp; world!\n".ptr); } $ dmd test72.d -D Segmentation fault ========= Poo. Now I wish I hadn't deleted the proposal I typed up... generally though: have the ESCAPES thing be implemented fully, and add ($DDOC_RAW) to bypass it, so you can still embed html in there while getting escaped output by default. (in std.ddoc you'd define HTML=($DDOC_RAW $0) so you can handle different embedded raw source differently in different output formats.)
Jun 30 2011
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-06-29 10:38, James Fisher wrote:
 On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob me.com
 <mailto:doob me.com>> wrote:

     On 2011-06-28 23:09, Walter Bright wrote:

         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. -- /Jacob Carlborg
Jun 29 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 7:00 AM, Jacob Carlborg wrote:
 HTML or some kind of other language can be used for the web site

Yes, and that's what we do!
 and DDoc for the actual documentation.

I don't see your point here.
Jun 29 2011
parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 20:03, Walter Bright wrote:
 On 6/29/2011 7:00 AM, Jacob Carlborg wrote:
 HTML or some kind of other language can be used for the web site

Yes, and that's what we do!
 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. -- /Jacob Carlborg
Jun 29 2011
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
James Fisher wrote:
 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.
Jun 29 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 7:18 AM, Adam D. Ruppe wrote:
 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.
Jun 29 2011
parent reply Adam Ruppe <destructionator gmail.com> writes:
Walter Bright wrote:
 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.
Jun 29 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 11:23 AM, Adam Ruppe wrote:
 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.
Jun 29 2011
parent reply Adam Ruppe <destructionator gmail.com> writes:
Walter Bright wrote:
 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.
Jun 29 2011
parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 11:49 AM, Adam Ruppe wrote:
 Walter Bright wrote:
 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.
Jun 29 2011
prev sibling next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Adam D. Ruppe" <destructionator gmail.com> wrote in message 
news:iufc81$2424$1 digitalmars.com...
 James Fisher wrote:
 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.
Jun 29 2011
parent reply Adam Ruppe <destructionator gmail.com> writes:
Nick Sabalausky wrote:
 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.
Jun 29 2011
next sibling parent "Nick Sabalausky" <a a.a> writes:
"Adam Ruppe" <destructionator gmail.com> wrote in message 
news:iug41e$1a4s$1 digitalmars.com...
 Nick Sabalausky wrote:
 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.

Yea, I see. That all makes sense.
Jun 29 2011
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/29/11 4:04 PM, Adam Ruppe wrote:
 Nick Sabalausky wrote:
 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.

Yes please. Excellent point. Andrei
Jul 02 2011
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/29/11 9:18 AM, Adam D. Ruppe wrote:
 James Fisher wrote:
 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.

Yah, agreed. I've done some work on that in the past; ideally each construct would generate a div/span with its own class and then everything would be controlled by CSSs.
 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.

I agree. It's a bit difficult for me to understand all the fuss. Arguments regarding learning of ddoc literally take longer to type than to obviate by learning. BTW, if anyone wants to contribute to the site, usage of html is not a barrier. Andrei
Jul 02 2011
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Andrei:
 Yah, agreed. I've done some work on that in the past; ideally each
 construct would generate a div/span with its own class and then
 everything would be controlled by CSSs.

Yes, indeed. I'd like to go a little further than it goes now too, specifically, I'd like for any D identifiers - function names, etc. - that's outputted by the generator to be a macro too. For example, in code snippets or in function signatures. MyStruct myfunction(); Shouldn't just output, it should be like: $(DDOC_GLOBAL_NAME module.name, MyStruct) $(DDOC_PSYMBOL myFunction)(); (or maybe wrapping the return value in yet another macro. The more information we have, the better.) Why? So the global name can be translated right into a link. Ideally, you should be able to click on *any* D name in the docs and go right to it. The compiler can tell the scope too - global if the name is from another module. _NAME if it's from this module. _LOCAL if it's a local variable in a function example. This way, the macro can link straight to anything, with all the accuracy of the compiler's scoping and overload resolution rules. A textual post-processor can't be that accurate, so the links won't necessarily be accurate. But, even if the compiler did nothing but identify identifiers and pass the name to a macro, that'd be an improvement since it can always link to a search engine, (Like my own http://dpldocs.info/NAME ) for the final resolution. This lack of easy cross-referencing in examples and signatures, especially across modules, is the only problem I have with ddoc itself right now.
Jul 02 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 7/2/2011 3:00 PM, Adam D. Ruppe wrote:
 Shouldn't just output, it should be like:

 $(DDOC_GLOBAL_NAME module.name, MyStruct) $(DDOC_PSYMBOL myFunction)();

Sounds like a good idea for a pull request!
Jul 02 2011
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Walter Bright wrote:
 Sounds like a good idea for a pull request!

Aye. I just wish my todo list was shorter!
Jul 02 2011
parent Walter Bright <newshound2 digitalmars.com> writes:
On 7/2/2011 3:35 PM, Adam D. Ruppe wrote:
 Walter Bright wrote:
 Sounds like a good idea for a pull request!

Aye. I just wish my todo list was shorter!

Mine has several thousand items on it!
Jul 02 2011
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-07-03 00:00, Adam D. Ruppe wrote:
 Andrei:
 Yah, agreed. I've done some work on that in the past; ideally each
 construct would generate a div/span with its own class and then
 everything would be controlled by CSSs.

Yes, indeed. I'd like to go a little further than it goes now too, specifically, I'd like for any D identifiers - function names, etc. - that's outputted by the generator to be a macro too. For example, in code snippets or in function signatures. MyStruct myfunction(); Shouldn't just output, it should be like: $(DDOC_GLOBAL_NAME module.name, MyStruct) $(DDOC_PSYMBOL myFunction)(); (or maybe wrapping the return value in yet another macro. The more information we have, the better.) Why? So the global name can be translated right into a link. Ideally, you should be able to click on *any* D name in the docs and go right to it. The compiler can tell the scope too - global if the name is from another module. _NAME if it's from this module. _LOCAL if it's a local variable in a function example. This way, the macro can link straight to anything, with all the accuracy of the compiler's scoping and overload resolution rules. A textual post-processor can't be that accurate, so the links won't necessarily be accurate. But, even if the compiler did nothing but identify identifiers and pass the name to a macro, that'd be an improvement since it can always link to a search engine, (Like my own http://dpldocs.info/NAME ) for the final resolution. This lack of easy cross-referencing in examples and signatures, especially across modules, is the only problem I have with ddoc itself right now.

Very good idea. -- /Jacob Carlborg
Jul 03 2011
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
Johannes Pfau wrote:
 I tried to do something similar some time ago, but I never finished it.

Looks pretty nice.... also looks like a lot more work than I thought it would be!
Jul 03 2011
prev sibling parent Chris Molozian <chris cmoz.me> writes:
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

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


On 06/29/11 12:25, Walter Bright wrote:
 On 6/29/2011 1:38 AM, James Fisher wrote:
 However, the case for using
 it for the website
 <https://github.com/D-Programming-Language/d-programming-language.org/b
ob/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.

Jun 29 2011
prev sibling next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"James Fisher" <jameshfisher gmail.com> wrote in message 
news:mailman.1259.1309290936.14074.digitalmars-d puremagic.com...
 *# 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.
 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.
 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.
 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. ;)
 *# 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!

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.
 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.
 http://www.dsource.org/
 etc.

That's for project hosting. Not the same.
 *# 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.
 *# 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".
 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.
Jun 28 2011
parent David Gileadi <gileadis NSPMgmail.com> writes:
On 6/29/11 2:02 AM, James Fisher wrote:
 On Tue, Jun 28, 2011 at 10:39 PM, Nick Sabalausky <a a.a> wrote:

     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
       <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.
Jun 29 2011
prev sibling next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
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
Jun 28 2011
parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/28/2011 3:35 PM, bearophile wrote:
 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 :-)
Jun 28 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--20cf3054a013c7d27b04a6cd79cc
Content-Type: text/plain; charset=UTF-8

On Tue, Jun 28, 2011 at 10:09 PM, Walter Bright
<newshound2 digitalmars.com>wrote:

 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
 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?
 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
 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>
 .

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?
 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
 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? --20cf3054a013c7d27b04a6cd79cc Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Tue, Jun 28, 2011 at 10:09 PM, Walter Bright = <span dir=3D"ltr">&lt;<a href=3D"mailto:newshound2 digitalmars.com">newshou= nd2 digitalmars.com</a>&gt;</span> wrote:<br><blockquote class=3D"gmail_quo= te" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;= "> Thanks for taking the time to do a detailed writeup on your opinions. I thi= nk it&#39;s great feedback.<br></blockquote><div><br></div><div>Well, thank= s!</div><div><br></div><blockquote class=3D"gmail_quote" style=3D"margin:0 = 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> 1. We all (well, almost all) agree on the need for a package manager. There= are some recent threads on getting this going.<br></blockquote><div><br></= div><div>Ah. =C2=A0Is <a href=3D"http://www.digitalmars.com/d/archives/digi= talmars/D/More_on_the_necessity_and_difficulty_of_a_package_management_syst= em_127873.html">this</a> the main thread you mean?</div> <div>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8= ex;border-left:1px #ccc solid;padding-left:1ex;"> 2. The &quot;two standard libraries&quot; debacle it pretty much in the pas= t now. D2 going forward has one standard library, Phobos.<br></blockquote><= div><br></div><div>Fair enough. =C2=A0Though the site at=C2=A0<a href=3D"ht= tp://www.dsource.org/projects/tango">http://www.dsource.org/projects/tango<= /a>=C2=A0gives no indication of that and still evangelizes migration from P= hobos to Tango. =C2=A0Are there people that would disagree with your assess= ment?</div> <div><br></div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex= ;border-left:1px #ccc solid;padding-left:1ex;"> 3. For searching, I recommend &quot;D programming&quot; with the quotes. It= works pretty good in google. I also harangue people who write about D to i= nclude the phrase &quot;D programming language&quot; at least once on their= pages. This helps a lot. On twitter we use #d_lang to tie things together.= <br> </blockquote><div><br></div><div>K.</div><div><br></div><blockquote class= =3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd= ing-left:1ex;"> 4. The official website for D is now <a href=3D"http://www.d-programming-la= nguage.org" target=3D"_blank">http://www.d-programming-<u></u>language.org<= /a>.</blockquote><div><br></div><div>An odd thing about it is that one migh= t mistake it for a companion site to Andrei&#39;s book, having the same nam= e and the front page devoted to it. =C2=A0Is this intentional? =C2=A0Perhap= s the plan is to host the book, in a read-it-free-online-or-buy-the-book sc= heme, like the amazing <a href=3D"http://book.realworldhaskell.org/read/why= -functional-programming-why-haskell.html">Real World Haskell</a>? =C2=A0(Th= at would be an incredibly strong resource.) =C2=A0Is Andrei&#39;s book an o= fficial part of the D project?</div> <div>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8= ex;border-left:1px #ccc solid;padding-left:1ex;"> 5. I know I suck at web site design</blockquote><div><br></div><div>No offe= nse meant!</div><div><br></div><blockquote class=3D"gmail_quote" style=3D"m= argin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">6. The dlink= s page is ancient, and it&#39;s been a long time since I even looked at it.= I agree it needs a revamp.<br> <br> 7. The <a href=3D"http://d-programming-language.org" target=3D"_blank">d-pr= ogramming-language.org</a> site is on github - this means that you can crea= te pull requests for it! Please do for anything specific you can contribute= to.<br> </blockquote></div><br><div>I&#39;d love to. =C2=A0Is the content of <a hre= f=3D"http://digitalmars.com/d">digitalmars.com/d</a> now frozen; is the int= ention to replace it with a redirect once content is migrated?</div> --20cf3054a013c7d27b04a6cd79cc--
Jun 28 2011
prev sibling next sibling parent Trass3r <un known.com> writes:
Am 29.06.2011, 00:49 Uhr, schrieb James Fisher <jameshfisher gmail.com>:
 On Tue, Jun 28, 2011 at 10:09 PM, 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.
Jun 28 2011
prev sibling next sibling parent reply Jimmy Cao <jcao219 gmail.com> writes:
--0016363b8cece251d404a6ce6c78
Content-Type: text/plain; charset=ISO-8859-1

On Tue, Jun 28, 2011 at 5:49 PM, James Fisher <jameshfisher gmail.com>wrote:

 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. --0016363b8cece251d404a6ce6c78 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Tue, Jun 28, 2011 at 5:49 PM, James Fisher <span dir=3D"ltr">&lt;<a href= =3D"mailto:jameshfisher gmail.com">jameshfisher gmail.com</a>&gt;</span> wr= ote:<div class=3D"gmail_quote"><blockquote class=3D"gmail_quote" style=3D"m= argin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> <div class=3D"gmail_quote"><div class=3D"im"><div><br></div></div><div>Thou= gh the site at=A0<a href=3D"http://www.dsource.org/projects/tango" target= =3D"_blank">http://www.dsource.org/projects/tango</a>=A0gives no indication= of that and still evangelizes migration from Phobos to Tango. =A0Are there= people that would disagree with your assessment?</div> </div></blockquote><div><br></div><div>The tango homepage will never say so= mething like, &quot;D1/Tango is dead, everyone migrate to Phobos!&quot; =A0= If you look at the history of D, back in 2006 or 2007 when the system for r= equesting improvements and bugfixes was rather messy and Phobos was increas= ingly incompetent as a standard library, part of the community decided to w= ork on replacing Phobos and make a better library for the community and dri= ven by the community. =A0So that was how the Tango community started, and t= hat community stayed with D1 when D2 was released.</div> <div><br></div><div>Both communities exist today, I guess, but the D2/Phobo= s community has grown the most, and D1/Tango community has shrunken (it&#39= ;s been years, the fact that there are still some D1/Tango users means that= Tango really is a fine library). =A0Phobos has improved ,also, and the tra= nsition to github has helped it a lot. =A0Your best bet is Phobos - its dev= elopment is very active, and it is poised to clearly become the best standa= rd library.</div> </div> --0016363b8cece251d404a6ce6c78--
Jun 28 2011
parent "Nick Sabalausky" <a a.a> writes:
"Jimmy Cao" <jcao219 gmail.com> wrote in message 
news:mailman.1263.1309305438.14074.digitalmars-d puremagic.com...
 On Tue, Jun 28, 2011 at 5:49 PM, James Fisher 
 <jameshfisher gmail.com>wrote:

 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.)
Jun 28 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--90e6ba613b240998ad04a6d417e8
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 1:02 AM, Nick Sabalausky <a a.a> wrote:

 "Jimmy Cao" <jcao219 gmail.com> wrote in message
 news:mailman.1263.1309305438.14074.digitalmars-d puremagic.com...
 On Tue, Jun 28, 2011 at 5:49 PM, James Fisher
 <jameshfisher gmail.com>wrote:

 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

 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

 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. --90e6ba613b240998ad04a6d417e8 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 1:02 AM, Nick Sabalausky= <span dir=3D"ltr">&lt;a a.a&gt;</span> wrote:<br><blockquote class=3D"gmai= l_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left= :1ex;"> &quot;Jimmy Cao&quot; &lt;<a href=3D"mailto:jcao219 gmail.com">jcao219 gmai= l.com</a>&gt; wrote in message<br> news:mailman.1263.1309305438.14074.digitalmars-d puremagic.com...<br> <div class=3D"im">&gt; On Tue, Jun 28, 2011 at 5:49 PM, James Fisher<br> &gt; &lt;<a href=3D"mailto:jameshfisher gmail.com">jameshfisher gmail.com</= a>&gt;wrote:<br> &gt;<br> &gt;&gt;<br> </div><div class=3D"im">&gt;&gt; Though the site at <a href=3D"http://www.d= source.org/projects/tango" target=3D"_blank">http://www.dsource.org/project= s/tango</a> gives no<br> &gt;&gt; indication of that and still evangelizes migration from Phobos to = Tango.<br> &gt;&gt; =C2=A0Are there people that would disagree with your assessment?<b= r> &gt;&gt;<br> &gt;<br> </div><div class=3D"im">&gt; The tango homepage will never say something li= ke, &quot;D1/Tango is dead,<br> &gt; everyone migrate to Phobos!&quot; =C2=A0If you look at the history of = D, back in<br> &gt; 2006<br> &gt; or 2007 when the system for requesting improvements and bugfixes was<b= r> &gt; rather<br> &gt; messy and Phobos was increasingly incompetent as a standard library, p= art<br> &gt; of<br> &gt; the community decided to work on replacing Phobos and make a better<br=

&gt; for the community and driven by the community. =C2=A0So that was how t= he Tango<br> &gt; community started, and that community stayed with D1 when D2 was relea= sed.<br> &gt;<br> &gt; Both communities exist today, I guess, but the D2/Phobos community has= <br> &gt; grown<br> &gt; the most, and D1/Tango community has shrunken (it&#39;s been years, th= e fact<br> &gt; that there are still some D1/Tango users means that Tango really is a = fine<br> &gt; library). =C2=A0Phobos has improved ,also, and the transition to githu= b has<br> &gt; helped it a lot. =C2=A0Your best bet is Phobos - its development is ve= ry<br> &gt; active,<br> &gt; and it is poised to clearly become the best standard library.<br> &gt;<br> <br> </div>And even if Tango does get ported to D2 (As I&#39;ve heard some peopl= e are<br> working on), it&#39;ll most likely be a suppliment to Phobos, rather than t= he<br> &quot;one or the other&quot; issue it was on D1. (That&#39;s what druntime = is for.)<br></blockquote><div><br></div><div>OK.</div><div><br></div><div>1= . =C2=A0One of the most pleasingly surprising tech stories I&#39;ve heard f= or years was <a href=3D"http://weblog.rubyonrails.org/2008/12/23/merb-gets-= merged-into-rails-3">the merging of Rails and Merb</a>, two large separate = Ruby web frameworks with the same problem domain. =C2=A0It was surprising b= ecause in the OSS world there&#39;s a nasty habit of all projects being a f= ork of something else, almost never a merge of two previous projects. =C2= =A0I figure all it took was some strong discussion. =C2=A0BTW, the choice o= f stdlib is not obvious to the new user of the language, and the &quot;just= let it die&quot; attitude makes things confusing. =C2=A0<a href=3D"http://= stackoverflow.com/questions/693672/d-standard-library">This SO question fro= m 09</a>=C2=A0(was the choice considered a non-issue then?)=C2=A0for instan= ce recommends Tango.</div> <div><br></div><div>2. I suppose, once a package manager is in place, this = issue will fade as Tango can be meted out into smaller packages.</div></div=

--90e6ba613b240998ad04a6d417e8--
Jun 28 2011
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-06-28 21:37, James Fisher wrote:
 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. -- /Jacob Carlborg
Jun 28 2011
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 1:09 AM, Caligo wrote:
 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.
Jun 29 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-06-29 10:05, James Fisher wrote:
 On Wed, Jun 29, 2011 at 7:52 AM, Jacob Carlborg <doob me.com
 <mailto:doob me.com>> wrote:

     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?

I don't know. This is where the discussion will be most exposed. -- /Jacob Carlborg
Jun 29 2011
prev sibling next sibling parent "Lars T. Kyllingstad" <public kyllingen.NOSPAMnet> writes:
On Wed, 29 Jun 2011 07:42:36 +0100, James Fisher wrote:

 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
Jun 29 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--90e6ba1ef6687af01b04a6d535f1
Content-Type: text/plain; charset=UTF-8

On Tue, Jun 28, 2011 at 10:39 PM, Nick Sabalausky <a a.a> wrote:
 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!** --90e6ba1ef6687af01b04a6d535f1 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Tue, Jun 28, 2011 at 10:39 PM, Nick Sabalausk= y <span dir=3D"ltr">&lt;a a.a&gt;</span> wrote:<blockquote class=3D"gmail_q= uote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1e= x">The main problem with D is that there&#39;s too many people with their l= ists<br> about what&#39;s wrong with D, and not enough willing to actually jump in a= nd<br> help out. I&#39;m sorry if I come across a bit harsh, but we seriously get<= br> another one of these &quot;What&#39;s wrong with D&quot; lists every few we= eks (and each<br> one seems more out-of-date than the last) and hardly any of the people<br> writing them have ever actually made any real contributions besides just<br=

oard!<br> But if not, then please understand that we already have more volunteer<br> supervisors than we need, so that sort of thing gets very frustrating for<b= r> those of us dedicating our own time and effort for free to actually<br> accomplish all the goals.<br></blockquote><div><br></div><div>Well, sure I&= #39;m willing to help. =C2=A0The reason I started out like this was to gaug= e 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 th= at it should be otherwise are taken as insults.</div> <div><br></div><div>While my coding abilities aren&#39;t bad, I figure that= &#39;s not what I&#39;m best helping with here. =C2=A0Key things I&#39;d su= ggest I could help with are:</div><div><ul><li>A simple D brand identity. = =C2=A0Nothing complex, just an official pronouncement that &quot;this is ou= r logo/logotype, this is our color palette, these are the one or two fonts = we use, here&#39;s how we describe ourselves, here are some simple guidelin= es on how to build a D-branded site/document&quot;. =C2=A0This could be has= hed out and maintained in a small GH repo.</li> <li>Applying that to <a href=3D"http://d-programming-language.org">d-progra= mming-language.org</a>.</li><li>Coming up with a long list of D community s= ites/wikis/tutorials/howtos/documentation/link lists. =C2=A0Identifying pro= jects that overlap domains and drumming up support for these to be merged i= nto the most popular of them or into <a href=3D"http://d-programming-langua= ge.org">d-programming-language.org</a>. =C2=A0**I do think this is possible= !**</li> </ul></div></div> --90e6ba1ef6687af01b04a6d535f1--
Jun 29 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--90e6ba3fcc5532ad9104a6d54198
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 7:52 AM, Jacob Carlborg <doob me.com> wrote:
 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? --90e6ba3fcc5532ad9104a6d54198 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 7:52 AM, Jacob Carlb= org <span dir=3D"ltr">&lt;<a href=3D"mailto:doob me.com">doob me.com</a>&gt= ;</span> wrote:<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex= ;border-left:1px #ccc solid;padding-left:1ex;"> I working on this. This is the ideas I have: <a href=3D"https://github.com/= jacob-carlborg/orbit/wiki/Orbit-Package-Manager-for-D" target=3D"_blank">ht= tps://github.com/jacob-<u></u>carlborg/orbit/wiki/Orbit-<u></u>Package-Mana= ger-for-D</a><br> <br> I&#39;ve started the development. I&#39;m going to write a more detail expl= anation/specification of the tools.<br></blockquote><div><br></div><div>Oh,= cool. =C2=A0Should discussion for this happen on GH Issues?</div></div> --90e6ba3fcc5532ad9104a6d54198--
Jun 29 2011
prev sibling next sibling parent Caligo <iteronvexor gmail.com> writes:
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?
Jun 29 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--20cf303bff6c26510404a6d5b4f7
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob me.com> wrote:

 On 2011-06-28 23:09, Walter Bright wrote:

 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?). --20cf303bff6c26510404a6d5b4f7 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg = <span dir=3D"ltr">&lt;<a href=3D"mailto:doob me.com">doob me.com</a>&gt;</s= pan> wrote:<br><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex= ;border-left:1px #ccc solid;padding-left:1ex;"> <div class=3D"im">On 2011-06-28 23:09, Walter Bright wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> 5. I know I suck at web site design, which is why David Gileadi helped<br> us out by designing the <a href=3D"http://d-programming-language.org" targe= t=3D"_blank">d-programming-language.org</a> look &amp; feel.<br> </blockquote> <br></div> I think it makes it hard when most of the pages are written in DDOC. It doe= sn&#39;t help to attract web designers.<br></blockquote><div><br></div><div=
I&#39;d definitely agree with that. =C2=A0I have no experience with DDOC, =

f DDOC, it seems like another reinvented wheel. =C2=A0Semi-plaintext format= s surround us like the plague, and for every use case for documentation, th= ere&#39;s a better option. =C2=A0If you want</div> <div><ul><li>simplicity, use <a href=3D"http://daringfireball.net/projects/= markdown/">Markdown</a>. =C2=A0Supported everywhere, like GH.</li><li>bulky= extensible semantic documentation, use <a href=3D"http://www.docbook.org/"=
DocBook</a>. =C2=A0Used by O&#39;Reilly, I&#39;m told. =C2=A0Presumably th=

ll</a>=C2=A0is maintained as a slick website and an O&#39;Reilly book.</li> <li>readability, but power and extensibility if required, use <a href=3D"ht= tp://docutils.sourceforge.net/">docutils</a>/<a href=3D"http://sphinx.pocoo= .org/">Sphinx</a>. =C2=A0Used for the <a href=3D"http://docs.python.org/py3= k/">Python standard library documentation</a>, which, as anyone who has use= d it knows, is The Best Documentation In The World.</li> </ul></div><div>That said, I suspect DDOC is now entrenched at least in the= stdlib documentation, so maybe we&#39;ll have to live with it. =C2=A0Howev= er, the case for <a href=3D"https://github.com/D-Programming-Language/d-pro= gramming-language.org/blob/master/index.dd">using it for the website</a> is= nonexistent (anyone disagree?).</div> </div> --20cf303bff6c26510404a6d5b4f7--
Jun 29 2011
prev sibling next sibling parent Jimmy Cao <jcao219 gmail.com> writes:
--90e6ba53a7dc6a377904a6d5c06d
Content-Type: text/plain; charset=ISO-8859-1

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.


On Wed, Jun 29, 2011 at 3:02 AM, James Fisher <jameshfisher gmail.com>wrote:

 On Tue, Jun 28, 2011 at 10:39 PM, Nick Sabalausky <a a.a> wrote:
 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!**

--90e6ba53a7dc6a377904a6d5c06d Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable <div>I think that&#39;s a great idea (the common font, colors, logo(?))</di= v><div><br></div><div>We also need a list of tutorials and wikis.</div><div=
Here&#39;s the tutorial/wiki I&#39;m working on:</div><div><a href=3D"http=

tp://en.wikibooks.org/wiki/D_(The_Programming_Language)</a></div> <div><br></div><div>I also think that ddoc isn&#39;t as good as many other = alternatives, but I don&#39;t think it&#39;s easy to change it.</div><br><b= r><div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 3:02 AM, James Fisher = <span dir=3D"ltr">&lt;<a href=3D"mailto:jameshfisher gmail.com" target=3D"_= blank">jameshfisher gmail.com</a>&gt;</span> wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"><div class=3D"gmail_quote"><div>On Tue, Jun = 28, 2011 at 10:39 PM, Nick Sabalausky <span dir=3D"ltr">&lt;a a.a&gt;</span=
 wrote:<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border=

The main problem with D is that there&#39;s too many people with their list= s<br> about what&#39;s wrong with D, and not enough willing to actually jump in a= nd<br> help out. I&#39;m sorry if I come across a bit harsh, but we seriously get<= br> another one of these &quot;What&#39;s wrong with D&quot; lists every few we= eks (and each<br> one seems more out-of-date than the last) and hardly any of the people<br> writing them have ever actually made any real contributions besides just<br=

oard!<br> But if not, then please understand that we already have more volunteer<br> supervisors than we need, so that sort of thing gets very frustrating for<b= r> those of us dedicating our own time and effort for free to actually<br> accomplish all the goals.<br></blockquote><div><br></div></div><div>Well, s= ure I&#39;m willing to help. =A0The reason I started out like this was to g= auge whether these problems were actually seen to be problems by the commun= ity -- you get a lot of projects that are so inward-facing that suggestions= that it should be otherwise are taken as insults.</div> <div><br></div><div>While my coding abilities aren&#39;t bad, I figure that= &#39;s not what I&#39;m best helping with here. =A0Key things I&#39;d sugge= st I could help with are:</div><div><ul><li>A simple D brand identity. =A0N= othing complex, just an official pronouncement that &quot;this is our logo/= logotype, this is our color palette, these are the one or two fonts we use,= here&#39;s how we describe ourselves, here are some simple guidelines on h= ow to build a D-branded site/document&quot;. =A0This could be hashed out an= d maintained in a small GH repo.</li> <li>Applying that to <a href=3D"http://d-programming-language.org" target= =3D"_blank">d-programming-language.org</a>.</li><li>Coming up with a long l= ist of D community sites/wikis/tutorials/howtos/documentation/link lists. = =A0Identifying projects that overlap domains and drumming up support for th= ese to be merged into the most popular of them or into <a href=3D"http://d-= programming-language.org" target=3D"_blank">d-programming-language.org</a>.= =A0**I do think this is possible!**</li> </ul></div></div> </blockquote></div><br> --90e6ba53a7dc6a377904a6d5c06d--
Jun 29 2011
prev sibling next sibling parent Chris Molozian <chris cmoz.me> writes:
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

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_gene
ators>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 06/29/11 09:38, James Fisher wrote:
 On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <doob me.com 
 <mailto:doob me.com>> wrote:

     On 2011-06-28 23:09, Walter Bright wrote:

         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/b
ob/master/index.dd> 
 is nonexistent (anyone disagree?).

Jun 29 2011
prev sibling next sibling parent reply James Fisher <jameshfisher gmail.com> writes:
--90e6ba613b24ee5c3d04a6d652d0
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 9:29 AM, Walter Bright
<newshound2 digitalmars.com>wrote:

 On 6/28/2011 11:46 PM, Jacob Carlborg wrote:

 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.
 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. --90e6ba613b24ee5c3d04a6d652d0 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 9:29 AM, Walter Bright <= span dir=3D"ltr">&lt;<a href=3D"mailto:newshound2 digitalmars.com">newshoun= d2 digitalmars.com</a>&gt;</span> wrote:<br><blockquote class=3D"gmail_quot= e" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"=

<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> I think it makes it hard when most of the pages are written in DDOC. It doe= sn&#39;t<br> help to attract web designers.<br> </blockquote> <br></div> I have no idea what professional web designers use, but I did many web page= s using html in a regular text editor.<br> <br> It was awful.<br></blockquote><meta http-equiv=3D"content-type" content=3D"= text/html; charset=3Dutf-8"><div><br class=3D"Apple-interchange-newline">I = agree that HTML isn&#39;t great to work with directly. =C2=A0Even in the re= alm of small static sites, the general movement is towards treating HTML as= a presentation format. =C2=A0If one wants a more convenient, non-semantic = wrapper over it, we have things like <a href=3D"http://haml-lang.com/">HAML= </a>, <a href=3D"http://haml-lang.com/">Jade</a>, and a million other thing= s.</div> <div><br></div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex= ;border-left:1px #ccc solid;padding-left:1ex;"> Using Ddoc literally doubled my productivity at creating web pages. Further= more, I can easily change them. This came in really handy when David redid = the look &amp; feel.<br></blockquote><meta http-equiv=3D"content-type" cont= ent=3D"text/html; charset=3Dutf-8"><blockquote class=3D"gmail_quote" style= =3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> <br> For example, I am able to create the C++ manuals for the Kindle and the <a = href=3D"http://digitalmars.com" target=3D"_blank">digitalmars.com</a> web p= ages from the exact same source text, simply by using a different set of .d= doc macros.<br> <br> (Although you can supposedly convert html directly to Kindle books, in real= ity you&#39;ll discover you need to put out different html than you would f= or web display.)<br></blockquote><div><br></div><div>I respect that it incr= eased your personal productivity. =C2=A0What&#39;s worth questioning is whe= ther it increases the productivity of the growing community as a whole.</di= v> <div><br></div><div>I don&#39;t aim to proselytize one mini-language over a= nother, as they&#39;re much of a muchness. =C2=A0But I&#39;d hope to convin= ce people that:</div><div><ul><li>Besides required functionality, the key r= eason to choose one markup/documentation/html-generating format is populari= ty. =C2=A0It opens up development to new users, frees up maintainers of old= documentation generators, and gives you new tools to use for free. =C2=A0M= arkup formats are one area where Might Is Right.</li> <li>The documentation and the D website are separate problems and shouldn&#= 39;t be conflated. =C2=A0Many other languages take the approach of separati= ng them and putting documentation in a subsite (e.g. <a href=3D"http://doc.= d-programming-language.org/">http://doc.d-programming-language.org/</a>). = =C2=A0X-site coherence can be maintained with pretty much just CSS. =C2=A0A= s we all know, dividing the problem is the first step to conquering it.</li=

--90e6ba613b24ee5c3d04a6d652d0--
Jun 29 2011
parent "Nick Sabalausky" <a a.a> writes:
"James Fisher" <jameshfisher gmail.com> wrote in message 
news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 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.

Popularity should *never* be a significant concern. That's how we end up with complete shit like PHP becoming widespread.
Jun 29 2011
prev sibling next sibling parent reply James Fisher <jameshfisher gmail.com> writes:
--90e6ba1ef66810dda304a6d738ce
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 10:59 AM, Don <nospam nospam.com> wrote:

 Chris Molozian wrote:

  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.
 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. --90e6ba1ef66810dda304a6d738ce Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 10:59 AM, Don <span dir= =3D"ltr">&lt;<a href=3D"mailto:nospam nospam.com">nospam nospam.com</a>&gt;= </span> wrote:<br><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .= 8ex;border-left:1px #ccc solid;padding-left:1ex;"> Chris Molozian wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> =C2=A0I very much agree. When it comes to lightweight markup languages for= use in web (and more) templating there&#39;s: Markdown &lt;<a href=3D"http= ://daringfireball.net/projects/markdown/" target=3D"_blank">http://daringfi= reball.net/<u></u>projects/markdown/</a>&gt;, Markdown Extra &lt;<a href=3D= "http://michelf.com/projects/php-markdown/extra/" target=3D"_blank">http://= michelf.com/projects/<u></u>php-markdown/extra/</a>&gt;, Haml &lt;<a href= =3D"http://haml-lang.com/" target=3D"_blank">http://haml-lang.com/</a>&gt;,= Textile &lt;<a href=3D"http://textile.thresholdstate.com/" target=3D"_blan= k">http://textile.<u></u>thresholdstate.com/</a>&gt;... to name just a few.= Is it worth maintaining another tool?<br> <br> When it comes to documentation within source files couldn&#39;t D adopt one= of the many different &lt;<a href=3D"http://en.wikipedia.org/wiki/Comparis= on_of_documentation_generators" target=3D"_blank">http://en.wikipedia.org/w= iki/<u></u>Comparison_of_documentation_<u></u>generators</a>&gt;documentati= on generators? <br> </blockquote> <br> Look at how many of those tools support D.<div class=3D"im"><br> <br> &gt; Again wouldn&#39;t that mean less custom tools to maintain.<br> <br></div> I doubt it. The source for DDoc is only 2000 lines of code (and it&#39;s si= mple code). D has enough unique features that you need to fight with your d= ocument generation system, if it doesn&#39;t natively support D.</blockquot= e> <div><br></div><div>Perhaps we should drop the &quot;what&#39;s better than= DDOC&quot; issue for the moment. =C2=A0The real issue is relegating it to = where it belongs, which is (surprise) documenting D code. =C2=A0Which means= separating out the stdlib documentation on <a href=3D"http://d-programming= -language.org">d-programming-language.org</a> from ... everything else, in = the tradition of</div> <div><ul><li><meta http-equiv=3D"content-type" content=3D"text/html; charse= t=3Dutf-8"><a href=3D"http://python.org/">http://python.org/</a>=C2=A0vs=C2= =A0<meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8"=
<a href=3D"http://docs.python.org/">http://docs.python.org/</a></li>

"><meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8">= <a href=3D"http://www.ruby-lang.org/en/">http://www.ruby-lang.org/</a>=C2= =A0vs=C2=A0<a href=3D"http://www.ruby-doc.org/stdlib/">http://www.ruby-doc.= org/</a></li> <li><meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8= "><a href=3D"http://www.perl.org/">http://www.perl.org/</a>=C2=A0vs=C2=A0<m= eta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8"><a h= ref=3D"http://perldoc.perl.org/">http://perldoc.perl.org/</a></li> <li><meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8= "><a href=3D"http://nodejs.org/">http://nodejs.org/</a>=C2=A0vs=C2=A0<meta = http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-8"><a href= =3D"http://nodejs.org/docs/v0.4.8/api/">http://nodejs.org/docs/v0.4.8/api/<= /a></li> <li>and others.</li></ul><div>This thread is flitting between topics, for r= easons that are entirely my own. =C2=A0Perhaps new threads would be appropr= iate for:</div></div><div><ul><li>Separating <a href=3D"http://d-programmin= g-language.org">d-programming-language.org</a> from <a href=3D"http://docs.= d-programming-language.org">docs.d-programming-language.org</a></li> <li>D brand identity</li><li>Package management.</li></ul></div></div> --90e6ba1ef66810dda304a6d738ce--
Jun 29 2011
parent "Nick Sabalausky" <a a.a> writes:
"James Fisher" <jameshfisher gmail.com> wrote in message 
news:mailman.1280.1309343205.14074.digitalmars-d puremagic.com...
 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.
 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

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?
Jun 29 2011
prev sibling next sibling parent Adam Richardson <simpleshot gmail.com> writes:
--0015174c432e5a7aeb04a6d7ba0c
Content-Type: text/plain; charset=ISO-8859-1

On Wed, Jun 29, 2011 at 4:29 AM, Walter Bright
<newshound2 digitalmars.com>wrote:

 On 6/28/2011 11:46 PM, Jacob Carlborg wrote:

 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 --0015174c432e5a7aeb04a6d7ba0c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Wed, Jun 29, 2011 at 4:29 AM, Walter Bright <span dir=3D"ltr">&lt;<a hre= f=3D"mailto:newshound2 digitalmars.com">newshound2 digitalmars.com</a>&gt;<= /span> wrote:<br><div class=3D"gmail_quote"><blockquote class=3D"gmail_quot= e" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"=

<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> I think it makes it hard when most of the pages are written in DDOC. It doe= sn&#39;t<br> help to attract web designers.<br> </blockquote> <br></div> I have no idea what professional web designers use, but I did many web page= s using html in a regular text editor.<br> <br> It was awful.<br> <br> Using Ddoc literally doubled my productivity at creating web pages. Further= more, I can easily change them. This came in really handy when David redid = the look &amp; feel.<br></blockquote><div><br></div><div>HTML is a fantasti= c for crafting web pages (and many web developers have IDE&#39;s that facil= itate 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.=A0</div> <div><br></div><div>Using ddoc to automatically generate documentation for = the API content within the site seems wise. However, using ddoc for the ent= ire website does present some challenges.</div><div><br></div><div>I&#39;ll= admit that I looked through to see what I could help out with on the websi= te, but ddoc stopped me in my tracks. I&#39;ll take time to learn how to us= e D to build my next web framework, because D seems like a great tool for t= he job. However, I&#39;d rather not take the time to learn how to turn buil= d websites with ddoc, as it&#39;s just not built for web site development.= =A0</div> <div><br></div><div>That said, David has shown that you can make great prog= ress with just ddoc (really, David, you&#39;ve done fantastic work.)</div><= div><br></div><div>Adam</div></div> --0015174c432e5a7aeb04a6d7ba0c--
Jun 29 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--90e6ba21212304c95204a6d98975
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 12:25 PM, Walter Bright
<newshound2 digitalmars.com>wrote:

 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.

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. --90e6ba21212304c95204a6d98975 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 12:25 PM, Walter Bright = <span dir=3D"ltr">&lt;<a href=3D"mailto:newshound2 digitalmars.com">newshou= nd2 digitalmars.com</a>&gt;</span> wrote:<br><blockquote class=3D"gmail_quo= te" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;= "> <div class=3D"im">Ddoc is:</div> <br> 1. Rather trivial to learn &amp; use. A website/book/community devoted to h= ow to use it is completely unnecessary. It&#39;s fairly obvious how to use = it (for someone with a basic familiarity with HTML) by simply looking at a = couple examples.<br> <br> 2. It automatically tracks the D language, so D code examples are always pr= operly highlighted.<br> <br> 3. It is always available and installed for anyone who installs D.<br> <br> 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 upda= tes.<br> <br> 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 operati= ng systems.<br> <br> 6. And lastly, it works, it delivers, and has for many years. It&#39;s prov= en its worth.<br></blockquote><div><br></div><div>OK. =C2=A0These are all g= ood reasons to maintain code documentation in Ddoc -- i.e., the Phobos docu= mentation. =C2=A0Let&#39;s drop the argument over replacing the documentati= on format. =C2=A0What I&#39;m not convinced of is that Ddoc is has any adva= ntage over a generic markup format when it comes to the homepage, associate= d pages (FAQ, acknowledgements, etc.), howtos, or even the language referen= ce. =C2=A0When I look over any of those documents -- <a href=3D"https://git= hub.com/D-Programming-Language/d-programming-language.org/blob/master/lex.d= d">lex.dd</a> to take a random example -- I don&#39;t see any semantics tha= t can&#39;t be expressed even in something as simple as Markdown. =C2=A0For= cing people to write their howtos in Ddoc is asking too much for no good re= ason.</div> </div> --90e6ba21212304c95204a6d98975--
Jun 29 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--90e6ba3fcc5501497404a6da54f2
Content-Type: text/plain; charset=UTF-8

On Wed, Jun 29, 2011 at 2:39 PM, Ary Manzana <ary esperanto.org.ar> wrote:
 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)
 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. --90e6ba3fcc5501497404a6da54f2 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div class=3D"gmail_quote">On Wed, Jun 29, 2011 at 2:39 PM, Ary Manzana <sp= an dir=3D"ltr">&lt;<a href=3D"mailto:ary esperanto.org.ar">ary esperanto.or= g.ar</a>&gt;</span> wrote:<blockquote class=3D"gmail_quote" style=3D"margin= :0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> There are many tools to syntax highlight code using HTML. Making the compil= er (or some part of it) do it is... hmmm... it&#39;s not the compiler&#39;s= job!<br> <br> Come on, it&#39;s not that hard to highlight with an external javascript (N= ick Sabalausky, please no comments :-P :-))</blockquote><div><br></div><div=
GP.</div><div><br></div><blockquote class=3D"gmail_quote" style=3D"margin:=

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 webs= ite styles or antyhing. And you can do the main website with another framew= ork.<br> </blockquote></div><br><div>A related thought here: are we aware of GitHub = site hosting? =C2=A0AFAICT <a href=3D"http://d-p-l.org">d-p-l.org</a> doesn= &#39;t use it, so I guess the repo is being pulled to another server? =C2= =A0As the content is (I think?) entirely static, GH hosting would be easier= , more maintainable, and cheaper. =C2=A0And no out-of-sync issues -- I saw = a thread today with someone complaining the site hadn&#39;t been pulled fro= m GH ...</div> <div><br></div><div>For the main site: while I&#39;ve not used it, I hear G= H&#39;s inbuilt support for <a href=3D"https://github.com/mojombo/jekyll">J= ekyll</a>, a static site generator, is great. =C2=A0<a href=3D"https://gith= ub.com/mojombo/jekyll/wiki/sites">It&#39;s pretty well recognized</a>, comp= letely customizable, and I suspect well within our requirements. =C2=A0Some= examples of sites built on it:</div> <div><br></div><div><meta http-equiv=3D"content-type" content=3D"text/html;= charset=3Dutf-8"><a href=3D"http://joelbradbury.net/">http://joelbradbury.= net/</a></div><div><meta http-equiv=3D"content-type" content=3D"text/html; = charset=3Dutf-8"><a href=3D"http://domain51.com/">http://domain51.com/</a><= /div> <div><meta http-equiv=3D"content-type" content=3D"text/html; charset=3Dutf-= 8"><a href=3D"http://jimeh.me/">http://jimeh.me/</a></div><div><meta http-e= quiv=3D"content-type" content=3D"text/html; charset=3Dutf-8"><a href=3D"htt= p://neilang.com/">http://neilang.com/</a></div> <div><br></div><div>Of course, we don&#39;t have to use Jekyll, and can rol= l our own static site.</div> --90e6ba3fcc5501497404a6da54f2--
Jun 29 2011
prev sibling next sibling parent "Lars T. Kyllingstad" <public kyllingen.NOSPAMnet> writes:
On Wed, 29 Jun 2011 14:18:42 +0000, Adam D. Ruppe wrote:
 
 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
Jun 29 2011
prev sibling next sibling parent reply Dejan Lekic <dejan.lekic tiscali.co.uk> writes:
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.
Jun 29 2011
next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
Dejan Lekic wrote:
 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.
Jun 29 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/29/11 1:33 PM, Adam Ruppe wrote:
 Dejan Lekic wrote:
 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.

One thing I didn't think about about is the necessity of a consistent logo. That alone is an excellent suggestion. Andrei
Jul 02 2011
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 6/29/2011 11:19 AM, Dejan Lekic wrote:
 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."
Jun 29 2011
parent "Nick Sabalausky" <a a.a> writes:
"Walter Bright" <newshound2 digitalmars.com> wrote in message 
news:iufs0j$pnj$1 digitalmars.com...
 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...
Jun 30 2011
prev sibling next sibling parent Chris Molozian <chris cmoz.me> writes:
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


On 06/29/11 19:19, Dejan Lekic wrote:
 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.

Jun 29 2011
prev sibling next sibling parent Adam Richardson <simpleshot gmail.com> writes:
--0015174c432e0935fe04a6df39ca
Content-Type: text/plain; charset=ISO-8859-1

On Wed, Jun 29, 2011 at 2:14 PM, Walter Bright
<newshound2 digitalmars.com>wrote:

 On 6/29/2011 4:03 AM, Adam Richardson wrote:

 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.
  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 --0015174c432e0935fe04a6df39ca Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Wed, Jun 29, 2011 at 2:14 PM, Walter Bright <span dir=3D"ltr">&lt;<a hre= f=3D"mailto:newshound2 digitalmars.com">newshound2 digitalmars.com</a>&gt;<= /span> wrote:<br><div class=3D"gmail_quote"><blockquote class=3D"gmail_quot= e" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"=

<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> I&#39;ll admit that I looked through to see what I could help out with on t= he<br> website, but ddoc stopped me in my tracks.<br> </blockquote> <br></div> How did it stop you?</blockquote><div><br></div><div>I&#39;m a web develope= r by trade, and ddoc, while nice for generating documentation, is not as ni= ce (relatively speaking) for managing a website. I&#39;d rather bring in el= ements of ddoc into an html site rather than try to bring in the appropriat= e html into ddocs (that&#39;s not to say that D wouldn&#39;t handle templat= ing for the site, just that the site wouldn&#39;t be built on top of ddoc.)= </div> <div><br></div><div>For example:</div><div><ol><li>Use simple templating sy= stem written in D for site.</li><li>Pages within templating system are buil= t using HTML, CSS, Javascript.</li><li>DDoc material=A0that&#39;s pulled fr= om D source=A0is dynamically brought in to the pages in the site using the = templating system.</li> </ol><div>DDoc would be used, but not as the foundation for the site.</div>= </div><div><br></div><div>=A0</div><blockquote class=3D"gmail_quote" style= =3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div cl= ass=3D"im"> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> it&#39;s just not built for web site development.<br> </blockquote> <br></div> Anything you can do in HTML, you can do in Ddoc.</blockquote><div><br></div=
<div>This is true. That said, what does the &quot;Anything you can do in X=

rimary tool for managing the website?=A0</div> <div><br></div><div>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&#39;ve carefully crafted a systems programming language t= hat provides many of the functional programming features I value, =A0whilst= maintaining succinct, clear syntax that affords great parsimony.</div> <div><br></div><div>For the same reason, I would prefer not to manage a web= site using DDoc, but rather use tools that are crafted specifically for the= job and then augment those tools with DDoc.</div><div><br></div><div>Adam<= /div> </div> --0015174c432e0935fe04a6df39ca--
Jun 29 2011
prev sibling next sibling parent reply Adam Richardson <simpleshot gmail.com> writes:
--0015174c432e95a0b704a6df424b
Content-Type: text/plain; charset=ISO-8859-1

On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky <a a.a> wrote:

 "James Fisher" <jameshfisher gmail.com> wrote in message
 news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 I don't aim to proselytize one mini-language over another, as they're

 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

 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 --0015174c432e95a0b704a6df424b Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky <span dir=3D"ltr">&lt;a a.= a&gt;</span> wrote:<br><div class=3D"gmail_quote"><blockquote class=3D"gmai= l_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left= :1ex;"> &quot;James Fisher&quot; &lt;<a href=3D"mailto:jameshfisher gmail.com">jame= shfisher gmail.com</a>&gt; wrote in message<br> news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...<br> <div class=3D"im">&gt;<br> &gt; I don&#39;t aim to proselytize one mini-language over another, as they= &#39;re much<br> &gt; of a muchness. =A0But I&#39;d hope to convince people that:<br> &gt;<br> &gt; =A0 - Besides required functionality, the key reason to choose one<br> &gt; =A0 markup/documentation/html-generating format is popularity. =A0It o= pens up<br> &gt; =A0 development to new users, frees up maintainers of old documentatio= n<br> &gt; =A0 generators, and gives you new tools to use for free. =A0Markup for= mats are<br> &gt; one<br> &gt; =A0 area where Might Is Right.<br> <br> </div>Popularity should *never* be a significant concern. That&#39;s how we= end up<br> with complete shit like PHP becoming widespread.<br></blockquote><div><br><= /div><div>Easy :) While I wouldn&#39;t use PHP for systems programming, PHP= is a solid tool for building websites.</div><div><br></div><div>Adam=A0</d= iv> </div> --0015174c432e95a0b704a6df424b--
Jun 29 2011
parent reply "Nick Sabalausky" <a a.a> writes:
"Adam Richardson" <simpleshot gmail.com> wrote in message 
news:mailman.1291.1309377741.14074.digitalmars-d puremagic.com...
 On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky <a a.a> wrote:

 "James Fisher" <jameshfisher gmail.com> wrote in message
 news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 I don't aim to proselytize one mini-language over another, as they're

 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

 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.
Jun 29 2011
next sibling parent "Nick Sabalausky" <a a.a> writes:
"Nick Sabalausky" <a a.a> wrote in message 
news:iug1fa$14v6$1 digitalmars.com...
 "Adam Richardson" <simpleshot gmail.com> wrote in message 
 news:mailman.1291.1309377741.14074.digitalmars-d puremagic.com...
 On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky <a a.a> wrote:

 "James Fisher" <jameshfisher gmail.com> wrote in message
 news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 I don't aim to proselytize one mini-language over another, as they're

 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

 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".
 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.

Jun 29 2011
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-06-29 22:16, Nick Sabalausky wrote:
 "Adam Richardson"<simpleshot gmail.com>  wrote in message
 news:mailman.1291.1309377741.14074.digitalmars-d puremagic.com...
 On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky<a a.a>  wrote:

 "James Fisher"<jameshfisher gmail.com>  wrote in message
 news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 I don't aim to proselytize one mini-language over another, as they're

 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

 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. -- /Jacob Carlborg
Jun 29 2011
parent reply "Nick Sabalausky" <a a.a> writes:
"Jacob Carlborg" <doob me.com> wrote in message 
news:iuh6jn$3df$2 digitalmars.com...
 On 2011-06-29 22:16, Nick Sabalausky wrote:
 "Adam Richardson"<simpleshot gmail.com>  wrote in message
 news:mailman.1291.1309377741.14074.digitalmars-d puremagic.com...
 On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky<a a.a>  wrote:

 "James Fisher"<jameshfisher gmail.com>  wrote in message
 news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 I don't aim to proselytize one mini-language over another, as they're

 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

 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.
Jun 30 2011
parent Jacob Carlborg <doob me.com> writes:
On 2011-06-30 10:13, Nick Sabalausky wrote:
 "Jacob Carlborg"<doob me.com>  wrote in message
 news:iuh6jn$3df$2 digitalmars.com...
 On 2011-06-29 22:16, Nick Sabalausky wrote:
 "Adam Richardson"<simpleshot gmail.com>   wrote in message
 news:mailman.1291.1309377741.14074.digitalmars-d puremagic.com...
 On Wed, Jun 29, 2011 at 3:48 PM, Nick Sabalausky<a a.a>   wrote:

 "James Fisher"<jameshfisher gmail.com>   wrote in message
 news:mailman.1279.1309339361.14074.digitalmars-d puremagic.com...
 I don't aim to proselytize one mini-language over another, as they're

 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

 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.

A brick wall actually sounds better :) -- /Jacob Carlborg
Jun 30 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
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? :)
Jun 29 2011
prev sibling next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 6/29/11, Nick Sabalausky <a a.a> wrote:
 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.
Jun 29 2011
parent reply "Nick Sabalausky" <a a.a> writes:
"Andrej Mitrovic" <andrej.mitrovich gmail.com> wrote in message 
news:mailman.1295.1309381293.14074.digitalmars-d puremagic.com...
 On 6/29/11, Nick Sabalausky <a a.a> wrote:
 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.
Jun 29 2011
parent reply LULZ <no-tact less.pretense.com> writes:
 Yea, exactly. I certainly appreciate the guy's intent to be

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.
Jun 29 2011
parent "Nick Sabalausky" <a a.a> writes:
"Andrej Mitrovic" <andrej.mitrovich gmail.com> wrote in message 
news:mailman.1298.1309383687.14074.digitalmars-d puremagic.com...
 Overreacting troll is overreacting. ;]

Troll feeder is troll feeding :)
Jun 30 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
Overreacting troll is overreacting. ;]
Jun 29 2011
prev sibling next sibling parent Jose Armando Garcia <jsancio gmail.com> writes:
On Wed, Jun 29, 2011 at 3:42 PM, Walter Bright
<newshound2 digitalmars.com> wrote:
 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...
Jun 29 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 6/30/11, KennyTM~ <kennytm gmail.com> wrote:
 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.
Jun 29 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
Vim can syntax highlight rest syntax, that's really sweet.
Jun 29 2011
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On 2011-06-30 13:12, Walter Bright wrote:
 On 6/30/2011 12:27 PM, Nick Sabalausky wrote:
 "Walter Bright"<newshound2 digitalmars.com> wrote in message
 news:iuig3e$2m1k$1 digitalmars.com...
 
 Back ticks are used for D raw string literals, and I now think that was
 a mistake.

What would you have used instead?

D has other methods for raw literals, so the ` are not only ugly, they're redundant.

Actually, I find the backticks to be by far the most pleasant way to get raw strings in D. I don't particularly like the other syntaxes for it (particularly q{}). It may be that other considerations make it so that it would have been better not to use backticks for raw strings, but I really like it, and I use them all the time. - Jonathan M Davis
Jun 30 2011
prev sibling next sibling parent "Simen Kjaeraas" <simen.kjaras gmail.com> writes:
On Thu, 30 Jun 2011 22:36:13 +0200, Daniel Gibson <metalcaedes gmail.com>  
wrote:


 Sadly, still nobody uses the profiler.

Are you sure? I've used it several times. But maybe there should be an article on it or something. (On why it should be used and how this is done)

Bring in the iPads! -- Simen
Jun 30 2011
prev sibling next sibling parent "Simen Kjaeraas" <simen.kjaras gmail.com> writes:
On Thu, 30 Jun 2011 23:52:38 +0200, Daniel Gibson <metalcaedes gmail.com>  
wrote:

 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:

 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

And standard Norwegian layout has them on AltGr+8/9. The pain. But using US int'l has the added advantage of confusing the hell out of my cow-orkers when they try to use my confuser (which has thus earned that title :p). -- Simen
Jun 30 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
Doesn't OSX have something equivalent to AutoHotkey?

Also, last I heard there was an AHK version for .NET, maybe OSX can
use that via the Mono project. That might be a long shot though.
Jun 30 2011
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On 2011-06-30 15:59, simendsjo wrote:
 On 01.07.2011 00:49, Simen Kjaeraas wrote:
 On Thu, 30 Jun 2011 23:52:38 +0200, Daniel Gibson
 
 <metalcaedes gmail.com> wrote:
 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:
 Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

And standard Norwegian layout has them on AltGr+8/9. The pain. But using US int'l has the added advantage of confusing the hell out of my cow-orkers when they try to use my confuser (which has thus earned that title :p).

Switch to programmer dvorak and they'll never touch your computer again.

I switched to dvorak _and_ got one of these: http://www.kinesis- ergo.com/advantage.htm No one is going to be using my computer with my keyboard. Though honestly, as much as I like dvorak, I wouldn't advise that anyone switch to it. Too many programs assume qwerty, so all of their shortcuts are designed for it. Stuff like the shortcuts for cut, copy, and paste are on completely different places on the keyboard and don't work as well (only cut can be done with just your left hand). I had to completely remap vim to be able to use it. Other programs need their keys or shortcuts remapped to work very well. It just causes problems for stuff that assumes qwerty. So, it's likely more pain than its worth. My keyboard is awesome regardless of whether you use qwerty or dvork though. I can actually type numbers on it without looking, which I could never do on a normal keyboard, because the keys aren't vertically aligned on a normal keyboard. It's expensive, but I'm quite happy that I bought it. - Jonathan M Davis
Jun 30 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
For ultimate escaping use:

auto str = q"EOS
    Weeee I'm a string ""``'q{\
EOS";

Of course then you have to make sure 'EOS' is a unique name too. You
could use some funky unicode character sequence for that, just to be
sure. :p
Jun 30 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
I've heard Colemak is more programmer-oriented than Dvorak. But these
are all "what works for you is the best" layouts.

Personally my problems are never writing code, but localizing and
browsing it. E.g. what's in this or that structure, field names, where
it's defined, etc. IDE features basically.
Jun 30 2011
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On 2011-06-30 17:29, simendsjo wrote:
 On 01.07.2011 02:19, Jonathan M Davis wrote:
 On 2011-06-30 15:59, simendsjo wrote:
 On 01.07.2011 00:49, Simen Kjaeraas wrote:
 On Thu, 30 Jun 2011 23:52:38 +0200, Daniel Gibson
 
 <metalcaedes gmail.com> wrote:
 Am 30.06.2011 23:50, schrieb KennyTM~:
 On Jul 1, 11 05:39, bearophile wrote:
 Jonathan M Davis:
 Actually, I find the backticks to be by far the most pleasant way
 to get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Python's `xyz` is equivalent to repr(xyz). I think it is removed in Python 3 more because `...` is not worth the specialness as repr(). But D's `...` is much more worthy as a convenient literal syntax when involving '"' or '\'. (I know some keyboard doesn't have '[' and ']'. So having no '`' shouldn't be the reason it is removed from the language.)

Keyboards without []? This makes programming nearly impossible O_O

And standard Norwegian layout has them on AltGr+8/9. The pain. But using US int'l has the added advantage of confusing the hell out of my cow-orkers when they try to use my confuser (which has thus earned that title :p).

Switch to programmer dvorak and they'll never touch your computer again.

I switched to dvorak _and_ got one of these: http://www.kinesis- ergo.com/advantage.htm No one is going to be using my computer with my keyboard. Though honestly, as much as I like dvorak, I wouldn't advise that anyone switch to it. Too many programs assume qwerty, so all of their shortcuts are designed for it. Stuff like the shortcuts for cut, copy, and paste are on completely different places on the keyboard and don't work as well (only cut can be done with just your left hand). I had to completely remap vim to be able to use it. Other programs need their keys or shortcuts remapped to work very well. It just causes problems for stuff that assumes qwerty. So, it's likely more pain than its worth. My keyboard is awesome regardless of whether you use qwerty or dvork though. I can actually type numbers on it without looking, which I could never do on a normal keyboard, because the keys aren't vertically aligned on a normal keyboard. It's expensive, but I'm quite happy that I bought it. - Jonathan M Davis

Looks ergonomically "correct", but pretty massive.

It's not really any wider than a normal keyboard, and it's only a little deeper (in spite of the fact that it has that gap in the middle). However, it is much taller. So, it works most anywhere that a normal keyboard would, but it won't work very well in some places where height matters (e.g. keyboard trays). - Jonathan M Davis
Jun 30 2011
prev sibling next sibling parent James Fisher <jameshfisher gmail.com> writes:
--bcaec51f990565998e04a713f182
Content-Type: text/plain; charset=UTF-8

The Compose Key is fantastic.  It's a tragedy it's not enabled by default.

On Sat, Jul 2, 2011 at 11:47 AM, Mike Wey <mike-wey example.com> wrote:

 On 06/30/2011 11:45 PM, Daniel Gibson wrote:

 Am 30.06.2011 23:41, schrieb simendsjo:

 On 30.06.2011 23:39, bearophile wrote:

 Jonathan M Davis:

  Actually, I find the backticks to be by far the most pleasant way to
 get raw
 strings in D.

I don't have backticks on my keyboard, so I use them only when they are needed. They have even removed the backticks in the Python2 -> Python3 transition partially because of this (and partially because there is a more obvious way to do it in Python, and Python tries to keep only one obvious way to do things). Bye, bearophile

Yeah, I hate backticks too.. I have to press Shift+` followed by space. But often space won't work as the text editor understands that space cannot be accented or something. So I often press ` twice and backspace to delete the last one. This gives me 4 key presses just for a single character... Wee...

On Linux/X11 this could be fixed by disabling "dead keys" (at least as long as you don't need them to place accents on letters, which depends on the languages you're writing in). Dunno what the equivalent to this setting for Windows or OSX is though. Cheers, - Daniel

And if you still need some accents you can enable the compose key: http://www.hermit.org/Linux/**ComposeKeys.html<http://www.hermit.org/Linux/ComposeKeys.html> -- Mike Wey

--bcaec51f990565998e04a713f182 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable The Compose Key is fantastic. =C2=A0It&#39;s a tragedy it&#39;s not enabled= by default.<br><br><div class=3D"gmail_quote">On Sat, Jul 2, 2011 at 11:47= AM, Mike Wey <span dir=3D"ltr">&lt;<a href=3D"mailto:mike-wey example.com"=
mike-wey example.com</a>&gt;</span> wrote:<br>

x #ccc solid;padding-left:1ex;"><div><div></div><div class=3D"h5">On 06/30/= 2011 11:45 PM, Daniel Gibson wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> Am 30.06.2011 23:41, schrieb simendsjo:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> On 30.06.2011 23:39, bearophile wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> Jonathan M Davis:<br> <br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> Actually, I find the backticks to be by far the most pleasant way to<br> get raw<br> strings in D.<br> </blockquote> <br> I don&#39;t have backticks on my keyboard, so I use them only when they<br> are needed. They have even removed the backticks in the Python2 -&gt;<br> Python3 transition partially because of this (and partially because<br> there is a more obvious way to do it in Python, and Python tries to<br> keep only one obvious way to do things).<br> <br> Bye,<br> bearophile<br> </blockquote> <br> Yeah, I hate backticks too.. I have to press Shift+` followed by space.<br> But often space won&#39;t work as the text editor understands that space<br=

to delete the last one. This gives me 4 key presses just for a single<br> character... Wee...<br> </blockquote> <br> On Linux/X11 this could be fixed by disabling &quot;dead keys&quot; (at lea= st as<br> long as you don&#39;t need them to place accents on letters, which depends<= br> on the languages you&#39;re writing in).<br> Dunno what the equivalent to this setting for Windows or OSX is though.<br> <br> Cheers,<br> - Daniel<br> </blockquote> <br></div></div> And if you still need some accents you can enable the compose key:<br> <a href=3D"http://www.hermit.org/Linux/ComposeKeys.html" target=3D"_blank">= http://www.hermit.org/Linux/<u></u>ComposeKeys.html</a><br> <br> -- <br><font color=3D"#888888"> Mike Wey<br> </font></blockquote></div><br> --bcaec51f990565998e04a713f182--
Jul 02 2011
prev sibling parent Johannes Pfau <spam example.com> writes:
Adam D. Ruppe wrote:
Andrei:
 Yah, agreed. I've done some work on that in the past; ideally each
 construct would generate a div/span with its own class and then
 everything would be controlled by CSSs.

Yes, indeed. I'd like to go a little further than it goes now too, specifically, I'd like for any D identifiers - function names, etc. - that's outputted by the generator to be a macro too. For example, in code snippets or in function signatures. MyStruct myfunction(); Shouldn't just output, it should be like: $(DDOC_GLOBAL_NAME module.name, MyStruct) $(DDOC_PSYMBOL myFunction)(); (or maybe wrapping the return value in yet another macro. The more information we have, the better.) Why? So the global name can be translated right into a link. Ideally, you should be able to click on *any* D name in the docs and go right to it. The compiler can tell the scope too - global if the name is from another module. _NAME if it's from this module. _LOCAL if it's a local variable in a function example. This way, the macro can link straight to anything, with all the accuracy of the compiler's scoping and overload resolution rules. A textual post-processor can't be that accurate, so the links won't necessarily be accurate. But, even if the compiler did nothing but identify identifiers and pass the name to a macro, that'd be an improvement since it can always link to a search engine, (Like my own http://dpldocs.info/NAME ) for the final resolution. This lack of easy cross-referencing in examples and signatures, especially across modules, is the only problem I have with ddoc itself right now.

I tried to do something similar some time ago, but I never finished it. It might help to understand how ddoc works and what needs to be changed to output "semantic macros". I also thought about implementing something like DDOC_GLOBAL_NAME. IIRC toPrettyChars() already returns the complete name, so it shouldn't be difficult. The changes: https://bitbucket.org/jpf/dmd-ddoc-old/changeset/7db05853d613 https://bitbucket.org/jpf/dmd-ddoc-old/changeset/680c738df87a https://bitbucket.org/jpf/dmd-ddoc-old/changeset/e831b01351c8 And here's a list of the new macros: https://bitbucket.org/jpf/dmd-ddoc-old/wiki/Home (The DDOC2_TEXT and WHITESPACE macros are only for backward compatibility) -- Johannes Pfau
Jul 03 2011