Am 30.12.2013 11:24, schrieb Jacob Carlborg:
> On 2013-12-29 19:35, Sönke Ludwig wrote:
> 
>> This is done for the DDOX based docs that were supposed to end up on the home page at some point:
> 
> BTW, although DDOX seems to be the best solution currently. It still
> feels like a workaround for something that should be fixed in the compiler.
> 

Although I think that it is more important to have a well defined documentation format that can be processed by external tools, it would indeed be much nicer if for example DMD could automatically emit $(XREF ...) or similar for recognized symbol names. Another thing that would sometimes be nice is to group functions by category (even though most of the time using different modules is arguably the better choice). Using custom HTML macros is sub optimal for many reasons and some kind of little DDOC syntax similar to sections could do wonders there.

All in all, it's good to have a built-in solution available (and especially important to facilitate a standard documentation format), but many things that a separate tool can do (global indexes, search, custom page structure, per declaration pages, etc.) would IMHO be overkill to have in the compiler. It's still a compiler after all.

On 2013-12-30 12:39, Sönke Ludwig wrote:

> Although I think that it is more important to have a well defined
> documentation format that can be processed by external tools, it would
> indeed be much nicer if for example DMD could automatically emit $(XREF
> ...) or similar for recognized symbol names. Another thing that would
> sometimes be nice is to group functions by category (even though most of
> the time using different modules is arguably the better choice). Using
> custom HTML macros is sub optimal for many reasons and some kind of
> little DDOC syntax similar to sections could do wonders there.
>
> All in all, it's good to have a built-in solution available (and
> especially important to facilitate a standard documentation format), but
> many things that a separate tool can do (global indexes, search, custom
> page structure, per declaration pages, etc.) would IMHO be overkill to
> have in the compiler. It's still a compiler after all.

Sure, it always leads back to the same problem: have the compiler available as a library. I guess the JSON output is some kind of middle ground.

-- 
/Jacob Carlborg

On 2013-12-30 11:26, Jakob Ovrum wrote:

> Yep, its only benefit is that it's a standardized set of macros and
> works for any reasonably deep hierarchy.

Not as far as I can see. What I can see it only supports one level of packages. That means basically a flat hierarchy like Phobos. All of my projects have a deeper hierarchy than that, usually one extra level of packages. I would consider a nested package to be within the limit of a reasonably deep hierarchy.

-- 
/Jacob Carlborg

Am 30.12.2013 13:47, schrieb Jacob Carlborg:
> On 2013-12-30 12:39, Sönke Ludwig wrote:
> 
>> Although I think that it is more important to have a well defined documentation format that can be processed by external tools, it would indeed be much nicer if for example DMD could automatically emit $(XREF ...) or similar for recognized symbol names. Another thing that would sometimes be nice is to group functions by category (even though most of the time using different modules is arguably the better choice). Using custom HTML macros is sub optimal for many reasons and some kind of little DDOC syntax similar to sections could do wonders there.
>>
>> All in all, it's good to have a built-in solution available (and especially important to facilitate a standard documentation format), but many things that a separate tool can do (global indexes, search, custom page structure, per declaration pages, etc.) would IMHO be overkill to have in the compiler. It's still a compiler after all.
> 
> Sure, it always leads back to the same problem: have the compiler available as a library. I guess the JSON output is some kind of middle ground.
> 

Absolutely! I hope at least the lexer will find it's way into Phobos soon. A lot of potential is effectively sleeping there.

On 12/30/13 3:39 AM, Sönke Ludwig wrote:
> Am 30.12.2013 11:24, schrieb Jacob Carlborg:
>> On 2013-12-29 19:35, Sönke Ludwig wrote:
>>
>>> This is done for the DDOX based docs that were supposed to end up on the
>>> home page at some point:
>>
>> BTW, although DDOX seems to be the best solution currently. It still
>> feels like a workaround for something that should be fixed in the compiler.
>>
>
> Although I think that it is more important to have a well defined
> documentation format that can be processed by external tools, it would
> indeed be much nicer if for example DMD could automatically emit $(XREF
> ...) or similar for recognized symbol names.

I'm not sure automatic cross-references are a good thing. Too many litter the document with links, and catch casual uses of words that happen to be indexable (consider e.g. "in" would be cross-referenced automatically).


Andrei

Am 30.12.2013 16:57, schrieb Andrei Alexandrescu:
> On 12/30/13 3:39 AM, Sönke Ludwig wrote:
>> Am 30.12.2013 11:24, schrieb Jacob Carlborg:
>>> On 2013-12-29 19:35, Sönke Ludwig wrote:
>>>
>>>> This is done for the DDOX based docs that were supposed to end up on
>>>> the
>>>> home page at some point:
>>>
>>> BTW, although DDOX seems to be the best solution currently. It still feels like a workaround for something that should be fixed in the compiler.
>>>
>>
>> Although I think that it is more important to have a well defined documentation format that can be processed by external tools, it would indeed be much nicer if for example DMD could automatically emit $(XREF ...) or similar for recognized symbol names.
> 
> I'm not sure automatic cross-references are a good thing. Too many litter the document with links, and catch casual uses of words that happen to be indexable (consider e.g. "in" would be cross-referenced automatically).
> 
> 
> Andrei
> 
> 

In my experience it is far more annoying to have the source files littered with $(MACROS) instead of putting a few _underscores to avoid bogus links (not to mention that most of the time this results in no links at all due to laziness). In some modules it may happen more frequently, but in general this seems to be rare enough for not really having to worry about it - at least in the examples that I've seen up to now.

Also remember that you often have to escape such words anyway, because they would otherwise still be highlighted as D code even without the cross references.

On 12/30/13 4:55 AM, Sönke Ludwig wrote:
> Am 30.12.2013 13:47, schrieb Jacob Carlborg:
>> On 2013-12-30 12:39, Sönke Ludwig wrote:
>>
>>> Although I think that it is more important to have a well defined
>>> documentation format that can be processed by external tools, it would
>>> indeed be much nicer if for example DMD could automatically emit $(XREF
>>> ...) or similar for recognized symbol names. Another thing that would
>>> sometimes be nice is to group functions by category (even though most of
>>> the time using different modules is arguably the better choice). Using
>>> custom HTML macros is sub optimal for many reasons and some kind of
>>> little DDOC syntax similar to sections could do wonders there.
>>>
>>> All in all, it's good to have a built-in solution available (and
>>> especially important to facilitate a standard documentation format), but
>>> many things that a separate tool can do (global indexes, search, custom
>>> page structure, per declaration pages, etc.) would IMHO be overkill to
>>> have in the compiler. It's still a compiler after all.
>>
>> Sure, it always leads back to the same problem: have the compiler
>> available as a library. I guess the JSON output is some kind of middle
>> ground.
>>
>
> Absolutely! I hope at least the lexer will find it's way into Phobos
> soon. A lot of potential is effectively sleeping there.

Yah, https://github.com/Hackerpilot/lexer-work/blob/master/lexer.d is great! More pre-review discussion?

@Brian Schott: would be awesome to encode a couple more lexer examples, such as HTML (recognition of all tags and character entities - there are comprehensive lists on the net) and C++?

Andrei

On 12/30/13 8:10 AM, Sönke Ludwig wrote:
> In my experience it is far more annoying to have the source files
> littered with $(MACROS) instead of putting a few _underscores to avoid
> bogus links (not to mention that most of the time this results in no
> links at all due to laziness).

Oh the default is to link and then disable manually? That's still manual, just the default is different :o). I can work with that.

Andrei

On 12/29/13 10:35 AM, Sönke Ludwig wrote:
> Am 29.12.2013 18:38, schrieb Jacob Carlborg:
>> A. Automatic cross reference
>
> This is done for the DDOX based docs that were supposed to end up on the
> home page at some point:

It's past time we do this. So the code is in there, we need to build it appropriately. Where do I start reading?

Andrei

Am 30.12.2013 17:31, schrieb Andrei Alexandrescu:
> On 12/29/13 10:35 AM, Sönke Ludwig wrote:
>> Am 29.12.2013 18:38, schrieb Jacob Carlborg:
>>> A. Automatic cross reference
>>
>> This is done for the DDOX based docs that were supposed to end up on the home page at some point:
> 
> It's past time we do this. So the code is in there, we need to build it appropriately. Where do I start reading?
> 
> Andrei
> 

I've just added a small alternative link below the normal Phobos documentation and added it to the "all" target of posix.mak. It will automatically call dub to build "dpl-docs" in the tools repository.

https://github.com/D-Programming-Language/dlang.org/pull/462

If there are no more issues with it, it should be the first step that actually gets something online.