Feature Request - Raw HTML in ddoc comments

Janice Caron caron800 at googlemail.com
Sun Mar 2 03:38:25 PST 2008


On 02/03/2008, Derek Parnell <derek at psych.ward> wrote:
>  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.
>
> "

You see, the problem is, I have no control whatsoever over Phobos's
build process. When Walter does a release, he just types "make", and
all of the source files, std.xml.d included, get built with the exact
same command line options. I can't change that. And I /certainly/
don't want to go messing around with the makefile or fiddling with
what ddoc does. That's /way/ outside my area. Therefore, I cannot
influence 1, 2, 3, or 4.

The only one I can influence is 5, but if I put the macro definition
actually /inside/ std.xml.d, then it has the same effect as not using
a macro at all.


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

I thought not. But am I getting it now?


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

which is exactly the same as not using macros at all. I mean, I might
as well just put

    this function converts &amp;amp; to &amp;

directly into the ddoc comments. (That's how things are right now, by
the way). Using macros which were themselves defined in the same
source code wouldn't make the result any less format dependent.


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

Right! And that's what I've been trying to get at all along. I have no
control - /zero/ control - over how Phobos web pages are generated
from Phobos source files. That is completely out of my hands. The
/only/ thing I am able to do is to put ddoc comments inside the source
file, and trust the automated build process to churn out the
documentation when the next release happens.

So far as I can tell, the only way to make this format-independent
would be if those macro definitions were present in wherever the
Phobos build process gets its defintions for $(I ...) etc from.

To that end, I believe that the only solution available to me would be
for Walter to add the following macros to the default macros:

    For HTML generation:
    $(AMP) -> &amp;
    $(LT) -> &lt;
    $(GT) -> &gt;
    $(QUOT) -> &quot;
    $(APOS) -> &apos;

    For non-HTML generation:
    $(AMP) -> &
    $(LT) -> <
    $(GT) -> >
    $(QUOT) -> "
    $(APOS) -> '

And while where at it, some macros to emit colon and right-bracket
would be handy too, since these get (sometimes erroneously)
interpetted as special to ddoc.

I think this affects everyone though - not just people who commit to
Phobos. Sure - if you have some degree of control over the build
process you can change what macros are used to expand the ddoc, but I
believe that the /default/ macros should be sufficient to allow one to
write format-independent ddoc comments, and right now, they are not.

Correct me if I'm wrong - but I believe I've got it right this time. :-)



More information about the Digitalmars-d mailing list