Feature Request - Raw HTML in ddoc comments

[BCS]

Reply to Janice,

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

this can be done by alter the sc.ini file on /your/ computer and then running 
dmd (you can effect this)

>> 3. Definitions from *.ddoc files specified on the command line.

this is done by giving dmd a command line flag when you run it.

>> 4. Runtime definitions generated by Ddoc.
>> 5. Definitions from any Macros: sections.
>> "

(read the bit at the end before you jump on me for this)

If you are trying to effect the output of DMD on a project where you are 
unwilling to change that projects makefile then I guess you might be out 
of luck. 

>> 
> 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 haven't followed the details of this thread but... If you are trying to 
rebuild the phobos docs with a different set of macros and you want to do 
thins without dinking with the phobos sources or makefile, How would you 
propose changing the macros?

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

(for lack of a better place in this post to put it):

The problem with escaping raw output is that DMD would need to include something 
akin to a full lex/yacc and more to do this. This is because absolutely anything 
could be raw output. I could use DDoc to generate output for a system that 
has any arbitrary syntax. To make a system that can work with defining the 
rules that would allow DDoc to find the stuff to escape would be a huge project 
in and of it's self. To take a fun example, say I want to make ddoc generate 
D (don't ask why, I've made use of crazier things) some string would need 
to be escaped ( \n for example) but only if they are not in quotes ("\n") 
but maybe not all quotes (`\n`). 

There are other reasons to not escape; when do you escape? Say I define a 
macro like this "AB=A $(B $1))" This macro will insert an A followed by B 
expanding it's arg. This might be on top of a language package (in which 
cases the A should be escaped if it has special meaning) or as part of a 
language package (in which cases it should not be escaped).

To start having DDoc escape stuff just opens a huge can of worms that /has 
not solution/ so it just doesn't bother.

I hope some of that is useful.


>> 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.
> 
(read the bit at the end before you jump on me for this)

Are you trying to modify the docs on the /web site/ and in the /dmd.zip/?

That makes a big difference. If Walter is willing to let you do this then 
he will be willing to give you access to the stuff needed make the changes 
he will allow you to make. If he is not willing than it doesn't matter.

Talk to Walter directly (he's e-mail is around here somewhere).

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

modifying stuff above;

if you are trying to to rebuild the docs on your system in a format independent 
manner...

yes you got it right (at least the part I understand and care about). The 
doc source as it stands now is a "sick" hoge podge of formatting that needs 
to be cleaned out. This is known. This needs to be addressed at some point. 
This also is a result of much of the docs predating the advent of DDoc (lets 
all say "legacy code" :p ).