$(D code) -> code

[CyberShadow]

http://forum.dlang.org/post/m9btie$pcl$1@digitalmars.com

[CyberShadow]

I should probably diff the original and new .html files. Right as soon as I figure out why my DMD is not building.

[andralex]

Gotta say, looks pretty neat.

[kuettler]

Are backticks supported by ddox? To me, backticks are a huge improvement and this should probably go in in any case.

[kuettler]

It seems you did not catch all cases with nested parenthesis. See std/array.d:29. I spend some time to come up with this beast. This seemed to work.

perl -p -e 's/\$\(D ([^\$()]*+(\((?:[^\$()]*+|(?1))*\))*[^\$()]*)\)/`$1`/g' std/algorithm.d

[CyberShadow]

I'm seeing unexpected differences in the output, which seems to indicate that the backtick syntax is not synonymous with the $(D ...) syntax. At least one difference is that D keywords are no longer highlighted (wrapped in <b> tags).

[CyberShadow]

Ping @adamdruppe

[adamdruppe]

Where is $(D) defined?

I doubt they're identical though, unless you defined the DDOC_BACKQUOTED=$(D $0) somewhere,

[CyberShadow]

Where is $(D) defined?

According to git grep, it's defined in 7 places (twice in the same file, on consecutive lines).

I doubt they're identical though, unless you defined the DDOC_BACKQUOTED=$(D $0) somewhere,

Ah, I can work with that! Thanks.

[CyberShadow]

Hmm, DDOC_BACKQUOTED = $(D $0) is already in dlang.org.ddoc.

I made this test file:

/**
`true`
$(D true)

Macros:
D=<code>$0</code>
DDOC_BACKQUOTED = $(D $0)

*/
module foo;

The command: dmd -o- -D foo.d
Creates a file with these lines:

<code>true</code>
<code><b>true</b></code>

So it looks like there's something magical about $(D ...).

[andralex]

There's something magical about "true" so you may want to try another word. "$(D ...)" is not magical.

[CyberShadow]

How odd. Indeed, this doesn't apply to all keywords.

Anyway, the d_inlinecode CSS class has a font-weight: bold rule so I suppose it doesn't matter, it just cloggs up the diffs.

However, there are more differences. For example, the current symbol is no longer highlighted in green.

See e.g. std.algorithm.map: original and with backticks.

There's also some weird interaction between raw HTML in Ddoc and backticks. Here's std.datetime -
original and with backticks. Notice the difference in the second paragraph.

I think someone needs to take another look at the DMD side of things before we move forward on this front.

[adamdruppe]

On Sat, Jan 17, 2015 at 04:04:47AM -0800, Vladimir Panteleev wrote:

However, there are more differences. For example, the current symbol is no longer highlighted in green.

That was actually intentional, I turned off all the highlighting
in these blocks (my first draft did full highlighting, including
keywords, strings, etc., but we figured that was too D-specific
and rolled it back to no highlight.)

We could change my call to highlightCode3 over to plain highlightCode
if we still want the PSYMBOL, easy change.

There's also some weird interaction between raw HTML in Ddoc and backticks. Here's std.datetime -
original and [with backticks](and http://dump.thecybershadow.net/8156a6401fa879b0a7fb17fe7c5c0659/std_datetime.html). Notice the difference in the second paragraph.

I don't know what's going on with that yet.

[CyberShadow]

That was actually intentional, I turned off all the highlighting in these blocks (my first draft did full highlighting, including keywords, strings, etc., but we figured that was too D-specific and rolled it back to no highlight.)

It seems to me that this is a mutually-exclusive choice. Do we want the backticks to not be D-specific, or do we want them to be synonymous with $(D ...)?

[adamdruppe]

On Sat, Jan 17, 2015 at 04:04:47AM -0800, Vladimir Panteleev wrote:

There's also some weird interaction between raw HTML in Ddoc and backticks. Here's std.datetime -

OK, the closing > is translated into > by dmd for some reason.

Something I've never actually understood is why ddoc cares if
it is in a html tag or not. Why does it watch for < and skip
over html tags (with hacky code btw, see line 2289 of doc.c)
anyway?

That code is definitely responsible, but I don't know why it
is called yet.

[adamdruppe]

On Sat, Jan 17, 2015 at 06:28:51AM -0800, Vladimir Panteleev wrote:

It seems to me that this is a mutually-exclusive choice. Do we want the backticks to not be D-specific, or do we want them to be synonymous with $(D ...)?

$(D) itself is a middle ground - the current symbol is highlighted,
but nothing else is. We can do that here too.

[adamdruppe]

Something I've never actually understood is why ddoc cares if it is in a html tag or not.

I guess it is so the embedded HTML "feature" works with partial escaping outside it. I guess it is logical if you're into embedded html.

Regardless, this was an off by one bug - the for loop incremented the counter, missing the opening <, thus causing it to think the > was orphaned... which made the browser abandon the whole section of code as a mangled opening tag.

dlang/dmd#4306

[quickfur]

There are merge conflicts due to recently merged PRs. Please rebase? (You might have to redo std/algorithm/* from scratch, though -- git doesn't understand the concept of moving content between files and gets very confused when stuff is moved around, like when std.algorithm got split up.)

[CyberShadow]

Recreating this pull request is not a problem, but I'm waiting for dlang/dmd#4306 to be merged first.

[CyberShadow]

GitHub tags are silly.

[quickfur]

heh

[andralex]

rebase, after that we should be good to go

[andralex]

so what's blocking this?

[CyberShadow]

Nothing, in my queue

[CyberShadow]

@adamdruppe I found another problem, apparently it can't handle newlines?

/// `bar
/// baz`.
int foo;

This says:

test.d(3): Error: variable test.foo unmatched --- in DDoc comment

The error message is also misleading.

There's a lot of line breaks (for word wrapping) inside $(D ...) blocks across the Phobos documentation, I think this should be working.

[CyberShadow]

I think I figured out the error message: a newline silently terminates a (which I think is wrong), but as there is no newline at the end of the last DDoc line, it complains that the second (which should close the code block) is opening an unterminated block.

[adamdruppe]

On Mon, Jan 26, 2015 at 05:08:33PM -0800, Vladimir Panteleev wrote:

I think I figured out the error message: a newline silently terminates a ` (which I think is wrong),

My first draft did it differently, but this current behavior matches
github, etc., allowing lone ` to be displayed as literal values.

Was also needed for linker error copy pasta that goes like `foo'.

but as there is no newline at the end of the last DDoc line, it complains that the second ` (which should close the code block) is opening an unterminated block.

But yes, it shouldn't do that, I'll look into it probably tomorrow.

[CyberShadow]

OK, this introduces an inconvenience:

If you have text such as:

Foo bar foo bar `foo bar foo bar` foo bar ...

and you want to add text before the , but doing so puts the line over the line length limit. So you go to rewrap it, but now the wrap point falls between the .... So now you have to decide between replacing the backticks back to a $D(...)macro, or wrapping the line early and putting the entire...` on a new line.

[andralex]

What's going on?

[CyberShadow]

We need to decide whether to make the backticks work more like on GitHub, or more like $(D ...), with respect to how they react to line breaks.

[quickfur]

The current implementation of ... has the requirement that it must be contained on a single line. The code explicitly checks for the case where it spans multiple lines, and treats the backticks as separate characters. I'm sure there's a reason for this (prevent runaway code blocks when a backtick is missing, I'm guessing?), but for now, if the code snippet contains a space, you should just use $(D ...).

[CyberShadow]

but for now, if the code snippet contains a space, you should just use $(D ...).

I suppose I could restrict this pull to just blocks of code without whitespace, then?

[quickfur]

That would be a good start, yes. Though the question of whether or not linebreaks should be allowed, is probably something to be discussed.

[CyberShadow]

Hmm.

@adamdruppe Guess what, I found another problem. The leading underscores are not handled at all between backticks:

/// No backticks  : _foo
/// With backticks: `_foo`
int foo;

The second line emits a _ in the output HTML.

[CyberShadow]

Another problem, it doesn't work inside macro definitions:

/// $(FOO foo)
/// Macros:
///  FOO=[`$1`]
int x;

This will print the backticks verbatim.

[CyberShadow]

As hacky as it sounds, maybe it would have been easier to make even backticks be synonymous with $(D and odd ones with ).

[quickfur]

This is because ddoc comments are (conceptually) processed in two stages: first the ddoc-specific engine parses the raw text and inserts things like code markup macros when code snippets are encountered, parse section headings and bracket them with heading macros, etc.. This stage is also where backticks are processed. The second stage is the macro expansion, which only knows about $(...) and expands those macros recursively. It doesn't know anything about headings, keywords, blank lines, etc., it just does straight string substitution with macros.

So basically, if you put backticks inside a macro definition, by the time the backticks are expanded we're already in the macro expansion stage, so the backtick code doesn't trigger.

[CyberShadow]

Rebased with just the changes compatible with the current compiler. Merge quickly :)

[quickfur]

oops, wrong button, sorry about that

[andralex]

One middle ground is to allow at most one line difference between the opening and closing backtick. The problem I'm trying to avoid is some unmatched backtick "matching" one 30 lines below.

[kuettler]

Why not having backticks on one line only? As it is a shortcut, the documentation writer can happily decide whether to use them. If there has to be a limit (and I agree there should be), let the rule be very simple.

[CyberShadow]

Because then other documentation writers may be forced to go and convert backticks into $(D ...) macros just because they added some text before them.

[kuettler]

Yes, this would be the case. I suspect this to be rare. Furthermore, the
respective writer might find a different arrangement. To me this seems
reasonable.

On Mon, Feb 16, 2015 at 10:30 AM, Vladimir Panteleev <
notifications@github.com> wrote:

Because then other documentation writers may be forced to go and convert
backticks into $(D ...) macros just because they added some text before
them.

—
Reply to this email directly or view it on GitHub
#2877 (comment)
.

[CyberShadow]

I guess this is going nowhere. If someone changes their mind, this patch is easy enough to recreate on top of master.