Feature Request - Raw HTML in ddoc comments

[Derek Parnell]

On Sun, 2 Mar 2008 07:51:21 +0000, Janice Caron wrote:

> On 02/03/2008, Derek Parnell <derek at psych.ward> wrote:
>> I already told you!
> 
> But I asked a follow-up question, which you didn't answer.

But you didn't actually ask that question. So I didn't answer it.

>> That's why I have doubts about you actually reading
>>  stuff.
> 
> Oh, don't doubt me on that one. I'm very studious. And actually, your
> implication there is kinda insulting, because it sort of assumes I'm
> too stupid to get it (or else actually lying!). Well, maybe I am too
> stupid to get it. Maybe that's the explanation.
> 
>> So here it is again...
>>
>>   this function converts $(AMP)amp$(SC) to $(AMP)
>>
>> AMP=&
>>  SC=;
> 
> And here's my followup question again. WHERE do I write
> 
>     AMP=&
>     SC=;

This is the first time I've seen this question.

But of course you already know the answer because you've read the
documentation, which clearly states where macros a defined.

But in any case, here is the quote from the documentation...

"
Macro definitions come from the following sources, in the specified order: 
 1. Predefined macros.
 2. Definitions from file specified by sc.ini's DDOCFILE setting.
 3. Definitions from *.ddoc files specified on the command line.
 4. Runtime definitions generated by Ddoc.
 5. Definitions from any Macros: sections.
"
 

> (although in fact I believe it should be "AMP=&amp;", not "AMP=&",
> because "&amp;", not "&", is what needs to appear in the generated
> HTML source).

See, you are getting it. You're right and I'm wrong.
 
> WHERE do I write that? Do I write it in the source code of my .d file?
> Because, my understanding is that the .d source should only contain
> the macros, not the macro definitions.

You're understanding is not quite accurate I'm afraid.

> (In fact, those definitions
> /must/ be external to the .d file, because otherwise you wouldn't want
> HTML-specific defintions in a destination-independent file).

Well, rather than "must" I'd use "should". You are allowed to put macro
definitions in your source code, but it can lead to format-dependant
layouts.

Here is a quick example that you can compile with the -D switch to see what
I mean.

// ------------

/******************
 * main is the entry point.
 *
 * Macros:
 *   AMP=&amp;
 *
 * Description:
 * For demo purposes, this function converts $(AMP)amp; to $(AMP)
 *
 * Params:
 *  pArgs = A list of strings from the command line.
 *
 */

void main(string[] pArgs)
{

}

// -------------

Now compile this with "dmd -D"


I would not recommend doing it this way. I'd put the macro definition in a
.ddoc file and put that on the command line too.


> Thank you for your kind understanding of my clear lack of intelligence!

You're welcome.

-- 
Derek Parnell
Melbourne, Australia
skype: derek.j.parnell