On Fri, Aug 6, 2010 at 21:02, Andrei Alexandrescu < SeeWebsiteForEmail@erdani.org> wrote:

>
> I have an experimental std.ddoc that generates TeX.
>

>From a 'pure ddoc' file or from a .d file?
It transforms ddoc mark-up into TeX mak-up?

Would it allow (theoretically) for literate programming?

weave("file.ld"); // creates file.tex
tangle("file.ld"); // creates file.d



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

I still would like DDoc to allow for some sectioning:

/**
section: sectionName
some section comments. This section is all about fun and foo.
*/

// fun doc
fun();

//foo doc
foo();

/**
section: next section,about bar and baz
*/
etc.

But, as far as I understand it, right the comments are all associated to the next declaration.

Philippe

Michel Fortin wrote:
> What will be the 64-bit D calling convention? Will it follow the host platform's C calling convention?

Yes.

> or will it be more uniform across platforms?

No.

> Also, why is 32-bit D using its own calling convention instead of reusing an already existing one?

Generates smaller/faster code.

> Why not use the host platform's C calling convention?

Which one of a dozen or so <g>? Everyone else ditched all the plethora of calling conventions when going to 64 bit, and I see no good reason not to join them.

BCS wrote:
> While you fix that, could you also add support for another linker to the win32 version?

Which one are you thinking about?

Steven Schveighoffer wrote:
> I just did (fixed a lot of stuff in the array page).

Thank you.

> A couple comments:
> 1. There is no guideline for updating the spec (at least that I could find).  I deduced $(V1) and $(V2) and figured out what $(LNAME2) is, but lack of guidelines may be partially to blame for why few people edit it.
> 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?

Nooooo, I tried to get away from that! HTML is a horrible format. Besides, I've also had thoughts of being able to use the macros to generate things like Latex output or man page output from the same source text.


> I think many would feel much more comfortable that way.  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).

I often make that mistake. But the editor I use (microemacs) has a fabulous feature, F3, which finds the matching ( { [ < > ] } ) #ifdef/#elif/#else/#endif when the cursor is placed on one of those. It makes it utterly trivial to find the mismatch.

BTW, back when the doc was in HTML, it was absolutely rife with mismatched HTML open and close tags. The fact that browsers would render it anyway I did not regard as a feature. The Ddoc macro format helps enormously in generating *correct* HTML. I've now got the entire D website using Ddoc, and the macros have enabled me to establish a common, and customizable, look and feel across the entire site just by adjusting the macro definitions.

The other feature of the macro method is, obviously, that they can be customized to generate all sorts of things. I believe that candydoc relies on that.

Alexander Malakhov wrote:
> 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.

  RPAREN=)

  $(D text $(RPAREN) )

You'll see a few of those in the macros, in particular $(DOLLAR) to embed a dollar sign. It's not so bad, every markup language needs an escape method.

This is the same method used in some text editors (e.g. Scite uses this
exact same method for variables, $() ).

2010/8/7 Walter Bright <newshound2@digitalmars.com>

> Alexander Malakhov wrote:
>
>> 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.
>>
>
>  RPAREN=)
>
>  $(D text $(RPAREN) )
>
> You'll see a few of those in the macros, in particular $(DOLLAR) to embed a dollar sign. It's not so bad, every markup language needs an escape method.
>

Don wrote:
> 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.

Here's what it has done, and this is real live experience because they were originally 100% html:

1. Yes, Don is right. It has improved ENORMOUSLY the productivity in those documents. I'm talking doubling or even tripling it.

2. I can comment out sections with $(COMMENT blah blah) and have them elided from the output. HTML comments remain in the output.

3. It has enabled the site to be written in correct, conforming HTML. Previously, it was a mess, and I didn't know what was wrong with it because it rendered ok anyway.

4. HTML has zero provision for conditional compilation. Want two HTML pages from the same source? Write two HTML pages. Note that the D1 and D2 docs are generated from the same source, this makes it easy to determine what's different between them.

5. It enabled me to produce a common look & feel for the whole site, which is hundreds of pages. This was just impossible before.

6. Even better, I can *change* the look and feel of the site with just editting a handful of macros.

7. I can update URLs across the site trivially, such as if bugzilla changes its URL.

8. As Don mentioned, it will automagically syntax highlight D code.

9. Grep doesn't work well with HTML tags. You really need an HTML-aware editor. Ddoc works with any editor (all you really need is a parentheses matcher).

10. HTML is a visually butt-ugly format that makes my eyes bleed pus. Very hard to read.

Lutger wrote:
>> 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.
> One trick that can work wonders here is treating ddoc as lisp code, most editors are very helpful with that. 

I hadn't thought of that, but you're right. All you need is a parenthesis matching command. Heck, I think I even wrote one for Emacs 25 years ago.

On Thu, 05 Aug 2010 22:34:34 +0000, mwarning wrote:

> On Thu, 05 Aug 2010 13:55:40 -0700, Walter Bright wrote:
> 
>> Adam Ruppe wrote:
>>> To abandon DMD for that is language suicide.
>> 
>> Well, one reason (certainly not the only one) I keep with the current dmd back end is that I don't need to spend time convincing some other organization to fix/improve/customize it for better D support. I can just get it done.
>> 
>> Being in control of the toolchain has a lot of benefits.
>> 
>> For example, look at gdb, and trying to get it to support D - not for the patches themselves, but getting them accepted into the standard gdb.
> 
> Thanks for the clarification.
> Imho, doing/checking everything already has taken years and will
> continue to take many years. I don't think it's a very viable concept.

.. but I hope it works out well. :)

On Friday, August 06, 2010 15:27:36 Walter Bright wrote:
> BCS wrote:
> > While you fix that, could you also add support for another linker to the win32 version?
> 
> Which one are you thinking about?

Presumably Microsoft's linker if that's at all possible.

Unfortunately, having to use dmc for C or C++ in order to link it with D code in Windows would make D a non-starter for any project that couldn't be in pure D where I work. Most of our stuff is cross-platform between Linux and Windows, using gcc on Linux and Visual Studio on Windows, and I don't think that there's any hope of getting anyone to switch to using dmc. If D code could be linked with code generated by Microsoft's compiler, then I'd have a much better chance of getting folks where I work to use D. As it is, it would have to be for standalone projects only, and most of our projects aren't standalone.

- Jonathan M Davis