On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright wrote:
> https://help.github.com/articles/basic-writing-and-formatting-syntax/
>
> Anyone interested in picking up the flag?
>
> (I know this has come up before, and I've been opposed to it, but I've changed my mind.)

These are great news. We are using harbored-mod (https://github.com/dlang-community/harbored-mod) which does this for quite some time, but it feels like a second-class citizen compared to the ddoc.

On 12/6/17 6:41 AM, Nemanja Boric wrote:
> On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright wrote:
>> https://help.github.com/articles/basic-writing-and-formatting-syntax/
>>
>> Anyone interested in picking up the flag?
>>
>> (I know this has come up before, and I've been opposed to it, but I've changed my mind.)
> 
> These are great news. We are using harbored-mod (https://github.com/dlang-community/harbored-mod) which does this for quite some time, but it feels like a second-class citizen compared to the ddoc.

Speaking of that tool, I suspect Ddoc's Markdown support will have to do the same as harboured-mod does with respect to the bits of Markdown syntax that are already claimed by Ddoc [1]

[1] https://github.com/dlang-community/harbored-mod#differences-from-vanilla-markdown

On 12/6/17 8:24 AM, Adrian Matoga wrote:
> On Wednesday, 6 December 2017 at 12:13:56 UTC, Walter Bright wrote:
>> On 12/5/2017 8:11 PM, Walter Bright wrote:
>>> (I know this has come up before, and I've been opposed to it, but I've changed my mind.)
>>
>> Part of this change of mind was driven by the bit of markdown that Ddoc already supports - the backticks to quote code and auto detection of URLs - and how nice that has turned out.
> 
> This is going to be the right time to deprecate the automatic change of some words that happen to be parameter names into code. :)

Yes, please!

-Steve

On Wednesday, 6 December 2017 at 15:08:53 UTC, David Gileadi wrote:
> On 12/6/17 6:41 AM, Nemanja Boric wrote:
>> On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright wrote:
>>> https://help.github.com/articles/basic-writing-and-formatting-syntax/
>>>
>>> Anyone interested in picking up the flag?
>>>
>>> (I know this has come up before, and I've been opposed to it, but I've changed my mind.)
>> 
>> These are great news. We are using harbored-mod (https://github.com/dlang-community/harbored-mod) which does this for quite some time, but it feels like a second-class citizen compared to the ddoc.
>
> Speaking of that tool, I suspect Ddoc's Markdown support will have to do the same as harboured-mod does with respect to the bits of Markdown syntax that are already claimed by Ddoc [1]
>
> [1] https://github.com/dlang-community/harbored-mod#differences-from-vanilla-markdown

The markdown lib used in harbored-mod comes from vibe-d (renamed as dmarkdown), so it will likely automatically be the case, see this part of the discussion: https://forum.dlang.org/post/p08kpm$oag$1@digitalmars.com

On Wed, Dec 06, 2017 at 10:32:38AM -0500, Steven Schveighoffer via Digitalmars-d wrote:
> On 12/6/17 8:24 AM, Adrian Matoga wrote:
> > On Wednesday, 6 December 2017 at 12:13:56 UTC, Walter Bright wrote:
> > > On 12/5/2017 8:11 PM, Walter Bright wrote:
> > > > (I know this has come up before, and I've been opposed to it,
> > > > but I've changed my mind.)
> > > 
> > > Part of this change of mind was driven by the bit of markdown that Ddoc already supports - the backticks to quote code and auto detection of URLs - and how nice that has turned out.
> > 
> > This is going to be the right time to deprecate the automatic change of some words that happen to be parameter names into code. :)
> 
> Yes, please!
[...]

+1000!

This "feature" has been the source of countless Phobos and dlang.org bugs, leading to time-wasting churn of changing `someword` into `_someword`, just to suppress the automatic change.  The underscore proliferation makes the source code quite unreadable if your module happens to be unfortunate enough to have many symbols that coincide with actual words.  It even happens inside URL macros used extensively in Phobos, meaning that you have to mangle your URLs just so DDoc doesn't destroy them by inserting "helpful" macro syntax, but that has the unfortunate side-effect of making DDoc URLs non-copy-pasteable when editing the source code.

In short, the "helpful" automatic changing of words into code has turned out to be a total disaster in practice.  For every instance where it's actually helpful, there are 99 instances where it's a nuisance.  It's time to admit that it was a bad design, and kill it with fire and extreme prejudice.


T

-- 
Без труда не выловишь и рыбку из пруда.

On 12/06/2017 01:14 PM, H. S. Teoh wrote:
> This "feature" has been the source of countless Phobos and dlang.org
> bugs, leading to time-wasting churn of changing `someword` into
> `_someword`, just to suppress the automatic change.

Isn't that controlled via a macro? We should just redefine the macro to return its argument unchanged. -- Andrei

On Wed, Dec 06, 2017 at 02:42:49PM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/06/2017 01:14 PM, H. S. Teoh wrote:
> > This "feature" has been the source of countless Phobos and dlang.org bugs, leading to time-wasting churn of changing `someword` into `_someword`, just to suppress the automatic change.
> 
> Isn't that controlled via a macro? We should just redefine the macro to return its argument unchanged. -- Andrei

Yes, the macro is DDOC_PARAM.  However, this macro is emitted from two places in ddmd/doc.d: one in highlightText(), where we'd like to suppress it, and the other in highlightCode(), where we WANT the highlighting.  Ergo, there is no way to selectively disable it only in running text without also killing any highlighting it may have had in code snippets, where it is wanted.

Perhaps a possible workaround is to use a shim in highlightText(), say, instead of using DDOC_PARAM, have it emit DDOC_PARAM_IN_TEXT, the latter of which passes its argument to DDOC_PARAM.  Then to selectively disable it, we simply redefine DDOC_PARAM_IN_TEXT to return the parameter unchanged. (And highlightCode() will continue to emit DDOC_PARAM directly, so the highlighting will still work in code snippets.)

This fancy dance seems completely redundant, though.  If we wanted to highlight the parameter in running text, we can already use the new backtick syntax `paramName`. There's really no added value in introducing yet another default macro DDOC_PARAM_IN_TEXT with a default definition that, most of the time, people don't even want anyway.


T

-- 
They pretend to pay us, and we pretend to work. -- Russian saying

On 12/6/2017 5:24 AM, Adrian Matoga wrote:
> This is going to be the right time to deprecate the automatic change of some words that happen to be parameter names into code. :)

Let's please keep that as a completely separate discussion, as the issue is orthogonal.

On 12/5/17 9:11 PM, Walter Bright wrote:
> https://help.github.com/articles/basic-writing-and-formatting-syntax/
> 
> Anyone interested in picking up the flag?
> 
> (I know this has come up before, and I've been opposed to it, but I've changed my mind.)

I didn't notice anyone pick this up yet. I'm taking a stab at it, writing it mostly from scratch. However if someone else wants to pick it up you're very welcome; my attempt is likely to be slow, especially this time of year :)

On 2017-12-06 05:11, Walter Bright wrote:
> https://help.github.com/articles/basic-writing-and-formatting-syntax/
> 
> Anyone interested in picking up the flag?
> 
> (I know this has come up before, and I've been opposed to it, but I've changed my mind.)

Finally :), this is awesome. Should we implement standard markdown, GitHub markdown or some other extension?

-- 
/Jacob Carlborg