Andrei's Google Talk

[Walter Bright]

Johannes Pfau wrote:
> On 15.08.2010 23:27, Walter Bright wrote:
>> retard wrote:
>>>  - the markup/macro syntax is NIH new.
>> Not really. The macro syntax is copied from make. And it's utterly trivial.
>>
>> I'd like to know how the macro system is inadequate for generating
>> Latex, man, etc. format.
> 
> I think it's not a problem with the macro system, but with the few
> macros emitted by dmd: There are enough macros for the doc comments
> (DDOC_SUMMARY, DDOC_DESCRIPTION, ...) but not for the types. DDOC_DECL,
> DDOC_DECL_DD and DDOC_*_MEMBERS are just not enough to extract detailed
> information.

Ok.

> This also puts quite some restrictions on the layout of the
> resulting documentation. In this case ddoc is very tied to html: These
> macros seem modeled directly after the DD DT DL html elements.

They are.


> I tried to enhance the ddoc output over the last few weeks and it's not
> ready to be released yet, but for example this is the macro structure
> I've chosen for function definitions:
> 
> DDOC_FUNCTION
>     DDOC_FUNCTION_HEADER_CONTAINER
>         DDOC_FUNCTION_TEMPLATE_HEADER
>         DDOC_FUNCTION_HEADER
>             DDOC_TYPE_FUNCTION
>                 DDOC_FUNCTION_PREFIX
>                 DDOC_TYPE_MODIFIER
>                 DDOC_EXTRA_MODIFIER
>                 DDOC_TRUST
>                 DDOC_FUNCTION_RETURN_TYPE
>                 DDOC_FUNCTION_NAME
>                 DDOC_FUNCTION_PARAMETERS
>                     DDOC_FUNCTION_LPAREN
>                     DDOC_FUNCTION_PARAMETER
>                         DDOC_FUNCTION_PARAMETER_STC (storage class)
>                         DDOC_FUNCTION_PARAMETER_TYPE
>                         DDOC_FUNCTION_PARAMETER_NAME
>                         [DDOC_FUNCTION_PARAMETER_DEFAULT]
>                         [DDOC_FUNCTION_COMMA]
>                     [DDOC_FUNCTION_VARARGS]
>                     DDOC_FUNCTION_RPAREN
>             DDOC_DECLARATION_SEMICOLON
>         DDOC_DITTO
>             DDOC_FUNCTION_HEADER...
>             DDOC_FUNCTION_TEMPLATE_HEADER...
>             DDOC_TEMPLATE_HEADER
>     DDOC_FUNCTION_DOC
> 
> One major aspect in my changes is that there should be no hardcoded
> output: everything can be redefined through macros, though sane defaults
> should be provided. Example:
> DDOC_DECLARATION_SEMICOLON=;
> DDOC_FUNCTION_VARARGS=...;
> DDOC_FUNCTION_COMMA=,;

This seems excessive.

> With more macros you can generate advanced looking documentation, for
> example, this is what I currently have:
> druntime docs: http://jpf.byethost10.com/druntime/doc/object.html
> simple tests:
> http://jpf.byethost10.com/demo/doc/ddoc/tests/simple/vars.html (druntime
> 2.047 in the right upper corner is still hardcoded...)
> 
> I also have xml output, but the xml ddoc file isn't complete yet
> (template support is missing)
> http://jpf.byethost10.com/demo_xml/ddoc/tests/simple/
> 
> And there's also a problem with phobos:in some cases the sources contain
> html. In other cases there are custom macros in modules which can only
> emit html(std.math, TABLE_SV, ...)

These should be fixed, but that's not a problem with Ddoc.

> and afaik you can't override module level macros with .ddoc files?

Right.