On 2010-08-05 17:42:58 -0400, Walter Bright <newshound2@digitalmars.com> said:

> 64 bit C on Windows uses a different ABI, the exception handling support is different, there's no linker (oops), etc. It's a much harder job.

Which makes me think of two small unimportant questions I'm curious about:

What will be the 64-bit D calling convention? Will it follow the host platform's C calling convention? or will it be more uniform across platforms?

Also, why is 32-bit D using its own calling convention instead of reusing an already existing one? Why not use the host platform's C calling convention?


-- 
Michel Fortin
michel.fortin@michelf.com
http://michelf.com/

On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <doob@me.com> wrote:

> On 2010-08-06 17:41, Alexander Malakhov wrote:
>> Steven Schveighoffer <schveiguy@yahoo.com> писал(а) в своём письме Fri,
>> 06 Aug 2010 18:28:41 +0700:
>>
>>> 2. It seems like the documentation is HTML written as ddoc. I see $(P)
>>> tags, $(LI) tags, etc. Can't we just write it as HTML?
>>
>> I have had exactly same thought when I've first seen DDoc a week ago
>>
>>
>>> I think many would feel much more comfortable that way.
>>
>> I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
>> pretty
>> straightforward
>>
>>> It's also more supported by editors. I forgot a closing parentheses on
>>> one tag, and it screwed up the entire page. I had to find it by hand,
>>> whereas an HTML editor could red-flag a tag without a closing tag, or
>>> you could run it through an XML verifier (if it's xhtml).
>>
>> Good points. And XML is not going to disappear anytime soon, so there will
>> always be a lot of people familiar with it, as wall as tool for it.
>> So I think it would be reasonable to have <tag/> syntax and HTML tags
>> like <B>, <I> etc.
>>
>> Also, for example, what if I want to put extra ')' paren into $(D text)?
>> I think there is (simple) solution, but that is one more thing to learn.
>> In the end it's just markup language and I don't see much use in learning
>> more then one of them.

>>
>> One reason of it I can think of: parsing speed and ambiguities (same as
>> with <templates>)
>>
>> Anyway, when D will take over the world, they will have to change HTML
>> syntax to fit what everyone already knows )
>
> One reason is why HTML is not used directly is that you could output the documentation in other formats than HTML, like PDF. A second reason to use macros (i.e. $(B arg)) instead of HTML is that this allows you to have the macro expand into something like this <span class="bold">arg</span> instead of <b>arg<b>. Of course one could define a language in XML to use instead of the macros.

Does ddoc output in pdf?  And besides, most of the tags *are* html tags, they're even the same tag name.  I can't imagine there's no htmltopdf program that would do exactly that.

Regarding the <span class="bold"> thing, can't you just do this in css:

b {
   whatever;
}

and override what <b> does?  There are probably macros which do other things that xhtml/css cannot do, but I don't think we should use macros for every html element.  For example, the $(V1) and $(V2) tags.  We need a good solution for that, and I think having dmd work those out is fine.  I also don't mind using the macros for more dynamic stuff.  I just think the formatting stuff can remain html, and all the macros should be defined/documented somewhere.

I like this explanation from Alexander:

In the end it's just markup language and I don't see much use in learning more then one of them.

It's just a thought, it might be blowing out of proportion a bit.  Granted I think I would have felt more comfortable using html directly, but it wasn't that hard to learn, and I was able to work through the issues.  I just wish I had some editor help...

-Steve

On 06.08.2010 19:23, Steven Schveighoffer wrote:
> On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <doob@me.com> wrote:
> 
>> On 2010-08-06 17:41, Alexander Malakhov wrote:
>>> Steven Schveighoffer <schveiguy@yahoo.com> писал(а) в своём письме Fri, 06 Aug 2010 18:28:41 +0700:
>>>
>>>> 2. It seems like the documentation is HTML written as ddoc. I see $(P)
>>>> tags, $(LI) tags, etc. Can't we just write it as HTML?
>>>
>>> I have had exactly same thought when I've first seen DDoc a week ago
>>>
>>>
>>>> I think many would feel much more comfortable that way.
>>>
>>> I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
>>> pretty
>>> straightforward
>>>
>>>> It's also more supported by editors. I forgot a closing parentheses on one tag, and it screwed up the entire page. I had to find it by hand, whereas an HTML editor could red-flag a tag without a closing tag, or you could run it through an XML verifier (if it's xhtml).
>>>
>>> Good points. And XML is not going to disappear anytime soon, so there
>>> will
>>> always be a lot of people familiar with it, as wall as tool for it.
>>> So I think it would be reasonable to have <tag/> syntax and HTML tags
>>> like <B>, <I> etc.
>>>
>>> Also, for example, what if I want to put extra ')' paren into $(D text)?
>>> I think there is (simple) solution, but that is one more thing to learn.
>>> In the end it's just markup language and I don't see much use in
>>> learning
>>> more then one of them.
> 
>>>
>>> One reason of it I can think of: parsing speed and ambiguities (same as
>>> with <templates>)
>>>
>>> Anyway, when D will take over the world, they will have to change HTML syntax to fit what everyone already knows )
>>
>> One reason is why HTML is not used directly is that you could output the documentation in other formats than HTML, like PDF. A second reason to use macros (i.e. $(B arg)) instead of HTML is that this allows you to have the macro expand into something like this <span class="bold">arg</span> instead of <b>arg<b>. Of course one could define a language in XML to use instead of the macros.
> 
> Does ddoc output in pdf?  And besides, most of the tags *are* html tags, they're even the same tag name.  I can't imagine there's no htmltopdf program that would do exactly that.
> 
> Regarding the <span class="bold"> thing, can't you just do this in css:
> 
> b {
>    whatever;
> }
> 
> and override what <b> does?  There are probably macros which do other things that xhtml/css cannot do, but I don't think we should use macros for every html element.  For example, the $(V1) and $(V2) tags.  We need a good solution for that, and I think having dmd work those out is fine.  I also don't mind using the macros for more dynamic stuff.  I just think the formatting stuff can remain html, and all the macros should be defined/documented somewhere.
> 
> I like this explanation from Alexander:
> 
> In the end it's just markup language and I don't see much use in learning more then one of them.
> 
> It's just a thought, it might be blowing out of proportion a bit. Granted I think I would have felt more comfortable using html directly, but it wasn't that hard to learn, and I was able to work through the issues.  I just wish I had some editor help...
> 
> -Steve

A simple html to pdf conversion might not produce good results.
In the long term something like http://sphinx.pocoo.org together with
ReStructuredText might be the best solution (for general documentation,
not for api documentation though). But the initial effort to 'port' the
existing documentation is quite high.

-- 
Johannes Pfau

On Fri, 06 Aug 2010 19:56:55 +0200, Johannes Pfau wrote:

> A simple html to pdf conversion might not produce good results.

Converting *anything* to PDF might not produce good results. :)

There's at least one excellent, open-source HTML-to-PDF converter:

   http://code.google.com/p/wkhtmltopdf/

There is also the very good Prince XML, which is free for non-commercial use:

  http://princexml.com/

> in the long term something like http://sphinx.pocoo.org together with ReStructuredText might be the best solution (for general documentation, not for api documentation though). But the initial effort to 'port' the existing documentation is quite high.

That would just introduce a different markup language that someone will have to learn. I like ReST and have used it extensively -- but why not Markdown, or MediaWiki Markup, or Texinfo, or etc. ad nauseum?

Meanwhile, the intial effort to 'port' the existing documentation to HTML is zero. :)

Best,
Graham

Steven Schveighoffer wrote:
> On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <doob@me.com> wrote:
> 
>> On 2010-08-06 17:41, Alexander Malakhov wrote:
>>> Steven Schveighoffer <schveiguy@yahoo.com> писал(а) в своём письме Fri,
>>> 06 Aug 2010 18:28:41 +0700:
>>>
>>>> 2. It seems like the documentation is HTML written as ddoc. I see $(P)
>>>> tags, $(LI) tags, etc. Can't we just write it as HTML?
>>>
>>> I have had exactly same thought when I've first seen DDoc a week ago
>>>
>>>
>>>> I think many would feel much more comfortable that way.
>>>
>>> I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
>>> pretty
>>> straightforward
>>>
>>>> It's also more supported by editors. I forgot a closing parentheses on
>>>> one tag, and it screwed up the entire page. I had to find it by hand,
>>>> whereas an HTML editor could red-flag a tag without a closing tag, or
>>>> you could run it through an XML verifier (if it's xhtml).
>>>
>>> Good points. And XML is not going to disappear anytime soon, so there will
>>> always be a lot of people familiar with it, as wall as tool for it.
>>> So I think it would be reasonable to have <tag/> syntax and HTML tags
>>> like <B>, <I> etc.
>>>
>>> Also, for example, what if I want to put extra ')' paren into $(D text)?
>>> I think there is (simple) solution, but that is one more thing to learn.
>>> In the end it's just markup language and I don't see much use in learning
>>> more then one of them.
> 
>>>
>>> One reason of it I can think of: parsing speed and ambiguities (same as
>>> with <templates>)
>>>
>>> Anyway, when D will take over the world, they will have to change HTML
>>> syntax to fit what everyone already knows )
>>
>> One reason is why HTML is not used directly is that you could output the documentation in other formats than HTML, like PDF. A second reason to use macros (i.e. $(B arg)) instead of HTML is that this allows you to have the macro expand into something like this <span class="bold">arg</span> instead of <b>arg<b>. Of course one could define a language in XML to use instead of the macros.
> 
> Does ddoc output in pdf?  And besides, most of the tags *are* html tags, they're even the same tag name.  I can't imagine there's no htmltopdf program that would do exactly that.

The reason they're the same is that the docs were originally written in html. The original conversion to ddoc was done via search and replace.
One of the HUGE benefits of ddoc is that it does highlighting of the D code. That instantly saved Walter a lot of time.
Seriously, converting it to ddoc did improve productivity.

On Fri, 06 Aug 2010 14:26:48 -0400, Don <nospam@nospam.com> wrote:

> Steven Schveighoffer wrote:
>>  Does ddoc output in pdf?  And besides, most of the tags *are* html tags, they're even the same tag name.  I can't imagine there's no htmltopdf program that would do exactly that.
>
> The reason they're the same is that the docs were originally written in html. The original conversion to ddoc was done via search and replace.
> One of the HUGE benefits of ddoc is that it does highlighting of the D code. That instantly saved Walter a lot of time.
> Seriously, converting it to ddoc did improve productivity.

Oh, I totally agree for the code samples.  And some of the other macros like $(V1).

But the manual markup, like marking every paragraph like this:

   $(P This is some text that is in a paragraph, and for some reason, we need a special
       tag for it instead of using &lt;p&gt;, one that is hard to find the closing
       tag for, because every tag's closing tag is simply a lone close parentheses
       like this:)

doesn't really make much difference than using <p>...</p>.  The advantage of using html tags for formatting like this means editors will recognize tags, and everyone and their mother knows what html tags look like.

-Steve

On 8/6/10 11:24 AM, Graham Fawcett wrote:
> On Fri, 06 Aug 2010 19:56:55 +0200, Johannes Pfau wrote:
>
>> A simple html to pdf conversion might not produce good results.
>
> Converting *anything* to PDF might not produce good results. :)
>
> There's at least one excellent, open-source HTML-to-PDF converter:
>
>     http://code.google.com/p/wkhtmltopdf/

For what it's worth I've been using wkhtmltopdf to generate PDF versions of the D site and documentation.  My hope is that generating them can become part of the build and that the latest versions can be always available for download instead of the somewhat-outdated version that the site currently links to.  I've filed a couple of bugs with wkhtmltopdf and they're being fixed--the developer is great.

The output isn't as nice as what Sphinx might generate, but it's not bad either.

Steven Schveighoffer wrote:

> On Fri, 06 Aug 2010 14:26:48 -0400, Don <nospam@nospam.com> wrote:
> 
>> Steven Schveighoffer wrote:
>>>  Does ddoc output in pdf?  And besides, most of the tags *are* html
>>> tags, they're even the same tag name.  I can't imagine there's no
>>> htmltopdf program that would do exactly that.
>>
>> The reason they're the same is that the docs were originally written in
>> html. The original conversion to ddoc was done via search and replace.
>> One of the HUGE benefits of ddoc is that it does highlighting of the D
>> code. That instantly saved Walter a lot of time.
>> Seriously, converting it to ddoc did improve productivity.
> 
> Oh, I totally agree for the code samples.  And some of the other macros
> like $(V1).
> 
> But the manual markup, like marking every paragraph like this:
> 
>     $(P This is some text that is in a paragraph, and for some reason, we
> need a special
>         tag for it instead of using &lt;p&gt;, one that is hard to find the
> closing
>         tag for, because every tag's closing tag is simply a lone close
> parentheses
>         like this:)
> 
> doesn't really make much difference than using <p>...</p>.  The advantage of using html tags for formatting like this means editors will recognize tags, and everyone and their mother knows what html tags look like.
> 
> -Steve

One trick that can work wonders here is treating ddoc as lisp code, most editors are very helpful with that.

Steven Schveighoffer wrote:
> On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <doob@me.com> wrote:
> 
>> On 2010-08-06 17:41, Alexander Malakhov wrote:
>>> Steven Schveighoffer <schveiguy@yahoo.com> писал(а) в своём письме Fri,
>>> 06 Aug 2010 18:28:41 +0700:
>>>
>>>> 2. It seems like the documentation is HTML written as ddoc. I see $(P)
>>>> tags, $(LI) tags, etc. Can't we just write it as HTML?
>>>
>>> I have had exactly same thought when I've first seen DDoc a week ago
>>>
>>>
>>>> I think many would feel much more comfortable that way.
>>>
>>> I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
>>> pretty
>>> straightforward
>>>
>>>> It's also more supported by editors. I forgot a closing parentheses on
>>>> one tag, and it screwed up the entire page. I had to find it by hand,
>>>> whereas an HTML editor could red-flag a tag without a closing tag, or
>>>> you could run it through an XML verifier (if it's xhtml).
>>>
>>> Good points. And XML is not going to disappear anytime soon, so there will
>>> always be a lot of people familiar with it, as wall as tool for it.
>>> So I think it would be reasonable to have <tag/> syntax and HTML tags
>>> like <B>, <I> etc.
>>>
>>> Also, for example, what if I want to put extra ')' paren into $(D text)?
>>> I think there is (simple) solution, but that is one more thing to learn.
>>> In the end it's just markup language and I don't see much use in learning
>>> more then one of them.
> 
>>>
>>> One reason of it I can think of: parsing speed and ambiguities (same as
>>> with <templates>)
>>>
>>> Anyway, when D will take over the world, they will have to change HTML
>>> syntax to fit what everyone already knows )
>>
>> One reason is why HTML is not used directly is that you could output the documentation in other formats than HTML, like PDF. A second reason to use macros (i.e. $(B arg)) instead of HTML is that this allows you to have the macro expand into something like this <span class="bold">arg</span> instead of <b>arg<b>. Of course one could define a language in XML to use instead of the macros.
> 
> Does ddoc output in pdf?

I have an experimental std.ddoc that generates TeX.

I understand your arguments - they're pretty much echoing those of myself and of Janice Caron when we first saw the Phobos docs. It didn't take me a long time to appreciate ddoc. Right now I'm considering converting my entire website to use ddoc. HTML is a pile of dung to actually write text in, and somehow I always up editing the raw HTML no matter how much editors are trying to hide it from me.

So how about this - give it a while and it's not impossible that your view might change.


Andrei

On Fri, 06 Aug 2010 15:02:26 -0400, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:

> Steven Schveighoffer wrote:
>> On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <doob@me.com> wrote:
>>
>>> On 2010-08-06 17:41, Alexander Malakhov wrote:
>>>> Steven Schveighoffer <schveiguy@yahoo.com> писал(а) в своём письме Fri,
>>>> 06 Aug 2010 18:28:41 +0700:
>>>>
>>>>> 2. It seems like the documentation is HTML written as ddoc. I see $(P)
>>>>> tags, $(LI) tags, etc. Can't we just write it as HTML?
>>>>
>>>> I have had exactly same thought when I've first seen DDoc a week ago
>>>>
>>>>
>>>>> I think many would feel much more comfortable that way.
>>>>
>>>> I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
>>>> pretty
>>>> straightforward
>>>>
>>>>> It's also more supported by editors. I forgot a closing parentheses on
>>>>> one tag, and it screwed up the entire page. I had to find it by hand,
>>>>> whereas an HTML editor could red-flag a tag without a closing tag, or
>>>>> you could run it through an XML verifier (if it's xhtml).
>>>>
>>>> Good points. And XML is not going to disappear anytime soon, so there will
>>>> always be a lot of people familiar with it, as wall as tool for it.
>>>> So I think it would be reasonable to have <tag/> syntax and HTML tags
>>>> like <B>, <I> etc.
>>>>
>>>> Also, for example, what if I want to put extra ')' paren into $(D text)?
>>>> I think there is (simple) solution, but that is one more thing to learn.
>>>> In the end it's just markup language and I don't see much use in learning
>>>> more then one of them.
>>
>>>>
>>>> One reason of it I can think of: parsing speed and ambiguities (same as
>>>> with <templates>)
>>>>
>>>> Anyway, when D will take over the world, they will have to change HTML
>>>> syntax to fit what everyone already knows )
>>>
>>> One reason is why HTML is not used directly is that you could output the documentation in other formats than HTML, like PDF. A second reason to use macros (i.e. $(B arg)) instead of HTML is that this allows you to have the macro expand into something like this <span class="bold">arg</span> instead of <b>arg<b>. Of course one could define a language in XML to use instead of the macros.
>>  Does ddoc output in pdf?
>
> I have an experimental std.ddoc that generates TeX.
>
> I understand your arguments - they're pretty much echoing those of myself and of Janice Caron when we first saw the Phobos docs. It didn't take me a long time to appreciate ddoc. Right now I'm considering converting my entire website to use ddoc. HTML is a pile of dung to actually write text in, and somehow I always up editing the raw HTML no matter how much editors are trying to hide it from me.

Heh. by editor I meant vim :)   I meant syntax highlighting, and matching tags, not something like frontpage.

I wouldn't mind the current docs, but I'd like to have some document to know what tags are defined and what they mean (like a ddocdoc), and how to define new tags.  Maybe this already exists?

The one issue I had is that closing tags are hard to spot.  When I edited the arrays.dd file, first vim refused to do any syntax highlighting, so everything was black and white (horror!).  Second, while adding anchors to all the headers (which by the way are still in html), I missed one closing parentheses.  So ddoc decided to match the global closing $(D_SPEC tag with the opening $(LNAME2 tag I forgot to close.  The result was no menu appeared on the left.  A proper html editor (not wysiwyg) would have highlighted tags, and flagged the missing <a> closing tag if I had done the anchors that way.

I'm not saying html is the end-all of the docs, I think we need some sort of macro system.  But perhaps we can use an already-existing one instead of ddoc.

> So how about this - give it a while and it's not impossible that your view might change.

I don't plan on writing tons of standalone ddoc documentation :)  I generally just comment my functions and let ddoc take care of the generation.  For documenting code, I think ddoc is great.  But the spec is not code.  It contains code snipits, and I think ddoc is great for those, but simply spitting out a bullet list is handled just fine by html or some other standard markup language.

-Steve