DDoc and logically structured HTML

[Ary Manzana]

On 03/11/2012 12:46 PM, Stewart Gordon wrote:
> On 11/03/2012 02:26, Kevin Cox wrote:
> <snip>
>> I hate to say it but I think the ddoc system was way overthought. It
>> would be better to
>> use a markup language such as Creole that is meant to look nice and
>> you can convert that
>> into anything you want. You could leave the default html but provide
>> an api for accessing
>> a parsed tree.
>
> I think this is more or less how Java doclets work. It works because
> Java's bytecode and dynamic class loading provide a means to call an
> arbitrary method of an arbitrary compiled class that need not be part of
> the same app.
>
> But how are we going to do this with D? It seems we would need to either:
> (a) compile the doclet on the fly and pass the parse tree into it
> (b) have in said API a parse tree constructor that translates it from a
> textual representation received through stdin.
>
> Stewart.

I don't understand why you related dynamic class' loading with a 
documentation system/syntax for D.

Some hours ago you closed a very old enhancement report I submited:

http://d.puremagic.com/issues/show_bug.cgi?id=3161

(in fact I had totally forgotten I implemented that :-P, so thanks for 
reminding it to me... thought I didn't like that you closed it as invalid)

Now, I implemented it purely based on dmd's code. I didn't add anything 
else to get that done. And D is not dynamic or doesn't have dynamic 
class loading.

So... can you explain a bit more?

And does somebody know why, being dmd able to compile files, which 
requires having exact type information for every 
method/template,whatever, generates such a poor documentation?

Another question: ddoc is used (or was used) to generate d's main site. 
Wut?? So it's much more than just documenting D classes. I think this is 
wrong. That's when you end up having macros and all of that, because 
when generating a page you want to reuse things. But when documentation 
a library, hmmm... I never needed such thing. And even though I do care 
about the format of the documentation (how it looks), I definitely don't 
put formatting information inside a method's documentation (except for 
code snippets and lists).

Some simple like markdown or rdoc (well, the idea, not rdoc itself for D 
:-P) should be more than enough.

If there's interesent, I can hack dmd into producing such documentation, 
and send a pull request.