Why I'm hesitating to switch to D

Johannes Pfau spam at example.com
Sun Jul 3 04:28:17 PDT 2011


Adam D. Ruppe wrote:
>Andrei:
>> Yah, agreed. I've done some work on that in the past; ideally each
>> construct would generate a div/span with its own class and then
>> everything would be controlled by CSSs.
>
>Yes, indeed. I'd like to go a little further than it goes now too,
>specifically, I'd like for any D identifiers - function names,
>etc. - that's outputted by the generator to be a macro too.
>
>For example, in code snippets or in function signatures.
>
>
>MyStruct myfunction();
>
>Shouldn't just output, it should be like:
>
>$(DDOC_GLOBAL_NAME module.name, MyStruct) $(DDOC_PSYMBOL myFunction)();
>
>(or maybe wrapping the return value in yet another macro. The more
>information we have, the better.)
>
>Why? So the global name can be translated right into a link.
>Ideally, you should be able to click on *any* D name in the
>docs and go right to it.
>
>
>The compiler can tell the scope too - global if the name is from
>another module. _NAME if it's from this module. _LOCAL if it's
>a local variable in a function example.
>
>
>This way, the macro can link straight to anything, with all
>the accuracy of the compiler's scoping and overload resolution
>rules.
>
>
>A textual post-processor can't be that accurate, so the links
>won't necessarily be accurate.
>
>But, even if the compiler did nothing but identify identifiers
>and pass the name to a macro, that'd be an improvement since it
>can always link to a search engine,
>(Like my own http://dpldocs.info/NAME ) for the final resolution.
>
>
>
>This lack of easy cross-referencing in examples and signatures,
>especially across modules, is the only problem I have with ddoc
>itself right now.

I tried to do something similar some time ago, but I never finished it.
It might help to understand how ddoc works and what needs to be changed
to output "semantic macros". I also thought about implementing
something like DDOC_GLOBAL_NAME. IIRC toPrettyChars() already returns
the complete name, so it shouldn't be difficult. 

The changes:
https://bitbucket.org/jpf/dmd-ddoc-old/changeset/7db05853d613
https://bitbucket.org/jpf/dmd-ddoc-old/changeset/680c738df87a
https://bitbucket.org/jpf/dmd-ddoc-old/changeset/e831b01351c8

And here's a list of the new macros:
https://bitbucket.org/jpf/dmd-ddoc-old/wiki/Home
(The DDOC2_TEXT and WHITESPACE macros are only for backward
compatibility)

-- 
Johannes Pfau



More information about the Digitalmars-d mailing list