Have you ever seen how _ddoc has a bunch of random names prefixed with underscores throughout the source? Or ever used _ddoc and found random words italicized?

Take a gander at this old file I generated with `dmd -D simpledisplay.d` a long time ago:

http://arsdnet.net/ddoc/simpledisplay.html

See in the "setClipboardText" function, near the top, how it says "copies some /text/ to the clipboard"? Why is that italic?

Or, under `struct Pen`, it says "the foreground _color_", underlined?

This is the old ddoc style, but the new style has the same thing:
http://arsdnet.net/dcode/simpledisplay.html#setClipboardText - text is still in a weird font there.


That's a ddoc "feature" that will highlight any occurrence in the text of a name that happens to be in scope. It is almost never what you actually want. In this example, it highlights "text" and "color" because they are the names of function parameters, but in the documentation, I was using the plain English words and did not desire emphasis.

Ddoc forces you to opt out of this by prefixing the words with an underscore. This is extremely common, since you almost never want ddoc's default behavior:

https://github.com/dlang/phobos/blob/master/std/range/interfaces.d#L8

"around _range objects "

https://github.com/dlang/phobos/blob/master/std/algorithm/mutation.d#L765

"$(REF_ALTTEXT input _range, isInputRange, std,_range,primitives)"

Yes, even in links, you have to escape common words.

https://github.com/dlang/phobos/blob/master/std/algorithm/mutation.d#L4

"generic _mutation algorithms"


https://github.com/dlang/phobos/blob/master/std/stdio.d#L826

"Calls $(HTTP cplusplus.com/reference/clibrary/cstdio/_fflush.html, _fflush)"



The leading underscore is common because the default behavior it escapes is extremely undesirable.


I propose that we kill it in a three step process:


1) Define the macros it implies to return $0, basically erasing themselves, in both the Phobos and the default dmd macro definitions. Then, if you don't write the leading underscore, the behavior is the same before and after.

2) Remove all occurrences of the leading underscore in Phobos and druntime. This can take as long as it takes, at least going forward we won't use it anymore.

3) Optionally, officially deprecate any detected uses of the old behavior, pending removal so `_front` is literally printed `_front` and `range` is plain `range` instead of `front` and `$(DDOC_PSYMBOL range)` (or whatever it is, it has I believe two macros depending on the context).


Step 3 is optional since having it doesn't really *hurt* once step one is complete, unless you hit some unlucky case where you actually want the underscore (such as maybe linking to some weird external resource, or discussing a mangled C name).

But I consider step one to be an absolute must, this "feature" has been a minor, but constant annoyance to most ddoc users I have talked to, and step two to be a REALLY nice thing to do.

what say yall?



BTW this was one of the first things I decided I'd kill with fire in dpldocs. I support detecting the underscore... just so I can warn me to fix it, and ignore it in generation. I have never seen any redeeming value to this ddocism.

On 03/05/2017 10:58 PM, Adam D. Ruppe wrote:
> Have you ever seen how _ddoc has a bunch of random names prefixed with
> underscores throughout the source? Or ever used _ddoc and found random
> words italicized?
>
[...excellently stated argument snipped...]
>
> I propose that we kill it [...]
> what say yall?
>

I'm tempted to raise a pitchfork and unleash a bloodcurdling "kill it with fire!!!", but honestly, I actually don't especially care whether ddoc fixes this or not.

And why don't I care? For one reason and one reason only:

If it's fixed, then great, but if not...well, there's enough I dislike about ddoc anyway that I've already resigned to the idea that a few years from now, I very well may not be using it anyway, but rather some replacement (quite possibly yours, now that I've actually taken a look and find it to be very similar to what I had already started planning out in my head).

If people want ddoc to be really good and widely used, then yes, "hear hear". But in all honestly, I'd rather just switch to something else or even write my own than try to change minds on ddoc (or ddox) matters.

On Monday, 6 March 2017 at 04:32:45 UTC, Nick Sabalausky (Abscissa) wrote:
> And why don't I care?

Oh, I agree. tbh my agenda here is more to reduce the merge conflict burden on my fork than to actually improve ddoc. I get sick of `git pull upstream master` eating an extra 5 minutes because HEAD shows the sane `gets a range` while master shows the `gets a _range`.

So I want to get that upstreamed to lessen my work, and I'm offering a way that benefits them too so it becomes a win/win proposition.

On Monday, March 06, 2017 03:58:11 Adam D. Ruppe via Digitalmars-d wrote:
> Have you ever seen how _ddoc has a bunch of random names prefixed with underscores throughout the source? Or ever used _ddoc and found random words italicized?

> But I consider step one to be an absolute must, this "feature" has been a minor, but constant annoyance to most ddoc users I have talked to, and step two to be a REALLY nice thing to do.
>
> what say yall?

My big problem with how it currently works with ddoc is it seems way too ad-hoc with regards to when something is highlighted or not. I'd much rather have it never highlighted and then have to add the macros to do it manually. Right now, without actually looking at the resulting documentation, I'm never sure whether certain things are going to be highlighted or not. I expect that if I spent more time trying to get documentation just right, I'd be much more familiar with how it really works, but as it stands, I suspect that a lot of the documentation I write has stuff highlighted when it shouldn't be or not highlighted when it should be.

- Jonathan M Davis

On Monday, 6 March 2017 at 05:27:12 UTC, Jonathan M Davis wrote:
> My big problem with how it currently works with ddoc is it seems way too ad-hoc with regards to when something is highlighted or not.

There's two rules: DDOC_PSYMBOL highlights any text that happens to match the current declaration name, and DDOC_PARAM highlights anything that matches any of the current parameters. Run dmd -D over this:

---
/++ foo.baz are bar module
        Macros:
                DDOC_PSYMBOL=PSYMBOL-$0
                DDOC_PARAM=PARAM-$0
+/
module foo.baz.bar;

/// foo and baz are bar outer
struct baz {
        /// foo and baz are bar range and Range
        void foo(Range)(int bar) {}
}
---


You'll get something like this:



foo.baz are PSYMBOL-bar module

    baz
    Declaration

    struct PSYMBOL-baz;

    foo and PSYMBOL-baz are bar outer
        foo
        Declaration

        void PSYMBOL-foo(Range)(int PARAM-bar);

        PSYMBOL-foo and baz are PARAM-bar range and Range




So you can see what's going on more clearly there: there's two kinds of highlights for name and params. It applies in the declaration ddoc outputs, AND in the comment text. The name also includes the last part of the module name, so `std.range` forces you to write `_range` in the module declaration comment.

But, as you could see from the real world example in my other post, function parameters and names are often regular words that appear in the text or in links.... and you almost never actually want them highlighted. Hence the extremely frequent escaping.



The highlighting in the declaration is OK, we could keep that if we are fine with just jumping to the compiler and ripping the highlight out there (or doing a css hack such that the highlighted things are displayed normally, but that'd still break links that mention them so the compiler is the best realistic option), but I don't think it is that useful anyway so defining the macro out of existence gives us the easiest path forward.

> I suspect that a lot of the documentation I write has stuff highlighted when it shouldn't be or not highlighted when it should be.

indeed.

On Monday, 6 March 2017 at 03:58:11 UTC, Adam D. Ruppe wrote:
> I propose that we kill it in a three step process:

+1 yes please