Cross referencing in Ddoc

[Sönke Ludwig]

Am 31.12.2013 00:37, schrieb Walter Bright:
> On 12/30/2013 3:13 PM, Sönke Ludwig wrote:
>> Am 30.12.2013 23:13, schrieb Walter Bright:
>>> On 12/30/2013 1:25 PM, Sönke Ludwig wrote:
>>>> Identifiers in documentation comments that are function parameters or
>>>> are names that are in scope at the associated declaration are
>>>> emphasized
>>>> in the output.
>>>>
>>>> So the same problem is already reality - you already have to go through
>>>> the documentation to see if there are any mis-highlighted words.
>>>
>>> 1. having a bad idea is not justification for doing it again :-)
>>
>> Of course not, but my point was that the mistake has already been made,
>> so we may as well make the best out of it... not really doing it again
>> in that sense.
>>
>> But if the decision is that in fact this was a mistake, it should get
>> removed and replaced by a proper solution sooner rather than later (it's
>> not that bad to lose some highlighting and Phobos uses $(D ...) anyway,
>> so just removing it wouldn't hurt much).
> 
> Ddoc is very heavily used. I don't believe we can make such silent,
> breaking changes.
> 

It's just word highlighting! Breaking changes in the language are one
thing, but this kind of fix is a whole different category. Keeping it
will only make the problem worse over time. If there is a reasonable
deprecation path, that would be better, of course, but the current
situation is the worst of all possibilities.

> 
>> And in that regard I'd like to
>> point to "D's goals for embedded documentation"
>> <http://dlang.org/ddoc.htm>. I very much agree with them, but the
>> current reality looks like the opposite - lots of macro-pseudo-HTML
>> markup, very difficult to read unprocessed in many places. So something
>> like using "#" or "()" to mark symbols + automatic cross referencing for
>> marked symbols would be a *really* nice to have.
> 
> I don't see any particular advantage to using (name) rather than $(REF
> name), and some serious disadvantages with false positives like
> func(param). Oops! A markup language should really strive to minimize
> special syntax. (I'm often tripped up by false positives in the wacky
> markup languages in Skype, Github, Reddit, etc., each of which feels
> compelled to reinvent markup.)

It's not "(name)", but "name()" or "name(param)", which is recognized as
a function call. "#name" also forces recognition as an identifier, as
well as "::name" in C++'s case.

I agree that going overboard with special syntax is a bad idea, but
symbols in a code documentation language is such a fundamental thing
that it should surely be among the first things, if not *the* first
thing, that deserves a concise syntax.

Also, the official first four goals of DDOC are:

> 1. It looks good as embedded documentation, not just after it is
>    extracted and processed.
> 2. It's easy and natural to write, i.e. minimal reliance on <tags> and
>    other clumsy forms one would never see in a finished document.
> 3. It does not repeat information that the compiler already knows from
>    parsing the code.
> 4. It doesn't rely on embedded HTML, as such will impede extraction
>    and formatting for other purposes.

Using $(XREF), $(TABLE $(TR $(TD ...))), $(LINK a b) $(D ...) and so on
is nothing but markup. If we go that route, we could as well remove all
syntax, except for the macros:

$(SUMMARY ...)
$(SECTION See_Also
   ...
)
$(PARAMS
  $(PARAM x ...)
  $(PARAM y ...)
)
$(SECTION Example
  $(CODEBLOCK
    ...
  )
)

But you added the syntax for a reason back then (readability ...and
writability). And the same goes for the auto-detection of identifiers. I
think the only problem is that the default would have been better off
the other way around.