Am 31.12.2013 17:48, schrieb Andrei Alexandrescu:
On 12/31/13 1:28 AM, Sönke Ludwig wrote:
Am 31.12.2013 05:39, schrieb Andrei Alexandrescu:
On 12/30/13 1:00 PM, Walter Bright wrote:
On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
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.
As I mentioned elsewhere, I dislike the requirement to use the inverse
feature. Consider maintenance - I add a symbol, and then have to grep
the rest of the module for any inadvertent collisions? Features should
be positive ones, not negative.
Your arguments are convincing.
Andrei
The argument in isolation is sound, no doubt. But alone it doesn't lead
to a solution*. There are a lot of arguments regarding the current
situation and if the decision is not to use the existing _negative rule,
then all of those should be carefully taken into account.
- Visual noise and effort when using $(XREF) style macros
- $(XREF) isn't sufficient! A multitude of macros is actually needed
- There is no standard set of macros, it's project specific
-> The whole documentation needs to be revised when moving code between
projects!
- Macros need to be carefully crafted so that they don't encode
knowledge about the final documentation/file structure
- Macros alone can't cope with nested directory structures
- The cognitive load for multiple such macros would very likely cause
them to go unused in many cases
In a nutshell, "good cross-referencing is hard".
I don't think so at all (on the technical level). What is the issue with
using the #identifier.chain pattern for example? It seems simple enough
and I can't imagine a more natural thing than to reference symbols in
documentation the same way as in code.
That's exactly the
experience of anyone who's created an index. In publishing there are
automatic index generators and they're universally known to be vastly
inferior to professional-produced ones. I've created my own index by
hand for TDPL and it's been difficult, but probably the result is better
than an automated index.
But index generation is a higher level issue. The basis for it is to
have some kind of universal anchor that can be used as a reference.
#identifier.chain or $(REF identifier.chain) is nothing more than that
and just solves the issue of supporting arbitrary nested scopes and
different file system or document hierarchies.
