Am 31.12.2013 11:05, schrieb Vladimir Panteleev:
> P.S. How come your user agent (Thunderbird) is not emitting
> format=flowed messages? According to [1], it supports format=flowed, and
> can only be disabled via editing option strings.
>
> [1]:
> http://kb.mozillazine.org/Plain_text_e-mail_(Thunderbird)#Flowed_format

Although I can't promise that I didn't tamper with these settings, I didn't find any non-default value in about:config in that area, but there is a default setting "mailnews.send_plaintext_flowed = false". This is now manually set to true, let's see.

On 2013-12-31 00:37, Walter Bright wrote:

> 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.)

You never addressed any of my other suggestions. Would suggestion B, that is having a special macro that compiler knows about, be an acceptable solution? Because the current behavior is not good enough.

> My bias is towards being extremely conservative in adding new features
> to Ddoc, instead we should strive to get the max out of the existing
> system, and even rely on external post processors.

If Ddoc requires post processing to be useful it's a complete failure. Why don't we instead strive to make it the best documentation generator for D?

-- 
/Jacob Carlborg

On 2013-12-31 01:05, Sönke Ludwig wrote:

> Also, the official first four goals of DDOC are:
>
>> 1. It looks good as embedded documentation, not just after it is
>>     extracted and processed.

It certainly does not. Just have a look at the top of std.algorithm or std.uni. Hundreds of lines of Ddoc madness.

>> 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.

Fails again. As soon as you need something more advanced than the standard sections you need to use macros. The macros are just as tags, just with a different syntax and name.

>> 3. It does not repeat information that the compiler already knows from
>>     parsing the code.

You sure need to do if you want good documentation. Take a look at std.algorithm, it has over 300 lines of Ddoc code to create a symbol table that Ddoc should be able to automatically generate.

>> 4. It doesn't rely on embedded HTML, as such will impede extraction
>>     and formatting for other purposes.

As far as I know this isn't very useful. For the other formats we use, like PDF, it uses the HTML output as a base.

To me it looks like it failed on all four of these goals.

> 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.
>

I completely agree.

-- 
/Jacob Carlborg

On 2013-12-31 10:31, Marco Leise wrote:

> I am VERY much in favor of a more MarkDown style syntax and #
> for identifier references! It is also very verbose to create
> bullet-point lists and you always have to double-check you
> don't forget to replace all ) with $(RPAREN). If you misspell
> anything it is lost in the output.

I completely agree. I suggested the $(REF) macro as an alternative to automatically add cross referencing because I thought that would have a greater chance of being accepted.

-- 
/Jacob Carlborg

On 2013-12-31 11:05, Vladimir Panteleev wrote:

> I agree that a good compromise would be to lighten the syntactic overhead.
>
> How about using the $(D) macro instead of $(REF)? This macro
> syntax-highlights its parameter as D code, and in Phobos it is already
> used for identifiers, so I think a good solution would be to find and
> create cross-reference links only for $(D contents).
>
> Also, I'd like to mention a previous idea I posted here: this problem,
> and several other problems we have with DDoc, would be gone if we'd put
> what we already have with what we already have, and allow writing D code
> that gets interpreted to translate documentation comments into
> documentation output, using our existing CTFE capabilities. This way,
> the entire DDoc syntax can be reimplemented using "library" D code,
> interpreted by the compiler during documentation generation, and anyone
> could build upon it or completely replace it with another syntax.

Isn't this something Sönke has done with DDOX and with the help of the JSON output?

I've been thinking that it probably wouldn't be that hard to create a __trait that return the ddoc comments of a symbol. Don't know how much that would be different from the JSON output though.

-- 
/Jacob Carlborg

On 2013-12-30 23:10, Walter Bright wrote:

> The "query" part, meaning it highlighted each one and asked for yes/no.
>
> http://www.gnu.org/software/emacs/manual/html_node/emacs/Query-Replace.html

That doesn't sound very efficient. Regardless of that, the current macros still don't work. How do you do cross referencing for something that has a deeper hierarchy and what most of Phobos has?

Just take a look at the documentation of std.digest.crc[1]. None of the cross referencing to std.digest.digest.toHexString work. It's due to a
misconception of how the $(XREF) works.

[1] http://dlang.org/phobos/std_digest_crc.html

-- 
/Jacob Carlborg

Am Tue, 31 Dec 2013 13:27:17 +0100
schrieb Jacob Carlborg <doob@me.com>:

> On 2013-12-31 10:31, Marco Leise wrote:
> 
> > I am VERY much in favor of a more MarkDown style syntax and # for identifier references! It is also very verbose to create bullet-point lists and you always have to double-check you don't forget to replace all ) with $(RPAREN). If you misspell anything it is lost in the output.
> 
> I completely agree. I suggested the $(REF) macro as an alternative to automatically add cross referencing because I thought that would have a greater chance of being accepted.

Yes that's more practical, unfortunately. :p

-- 
Marco

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". 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.

Andrei

On 12/31/13 4:26 AM, Jacob Carlborg wrote:
> On 2013-12-31 01:05, Sönke Ludwig wrote:
>
>> Also, the official first four goals of DDOC are:
>>
>>> 1. It looks good as embedded documentation, not just after it is
>>>     extracted and processed.
>
> It certainly does not. Just have a look at the top of std.algorithm or
> std.uni. Hundreds of lines of Ddoc madness.

That's an exaggeration. The top of std.algorithm produces complex output (two tables). The rest of the documentation is nice and legible.

>>> 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.
>
> Fails again. As soon as you need something more advanced than the
> standard sections you need to use macros. The macros are just as tags,
> just with a different syntax and name.

As one who's written both, I can testify this isn't true. Ddoc macros need to be mentioned once and then the closing paren completes them. Additionally, they can expand to arbitrarily complex output. In contrast, tags need to be mentioned twice (an often-mentioned issue with writing HTML by hand), are syntactically heavier, and therefore litter the text a lot more.

>>> 3. It does not repeat information that the compiler already knows from
>>>     parsing the code.
>
> You sure need to do if you want good documentation. Take a look at
> std.algorithm, it has over 300 lines of Ddoc code to create a symbol
> table that Ddoc should be able to automatically generate.

No. There are two tables there. One is a categorization of algorithms, which is human-made. There are several solutions to materializing that table but they all would require the intervention of a human being. I figured std.algorithm adds new algorithms rarely enough to allow myself a solution that requires manual intervention.

The second table is a "cheat sheet" with human-produced short descriptions for each function. Those short descriptions wouldn't fit well with the longer descriptions.

>>> 4. It doesn't rely on embedded HTML, as such will impede extraction
>>>     and formatting for other purposes.
>
> As far as I know this isn't very useful. For the other formats we use,
> like PDF, it uses the HTML output as a base.

Again no. You are misinformed. The PDF manual is generated via LaTeX from the same ddoc sources as the HTML pages.


Andrei

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.