Fix Issue 17594 - Define DDOC_BLANKLINE as an empty HTML paragraph, t…

[andralex]

…hus obviating the need to wrap text in $(P ...)

There are two typographical notions related to DDOC_BLANKLINE: "paragraph separator" (LaTeX: \par) and "vertical space" (LaTeX: \vspace). Of these, "paragraph separator" is the closest and most useful.

Paragraph separators must enjoy somewhat special treatment: adjacent paragraph separators should be merged together so empty paragraphs do not increase vertical spacing. Even if a paragraph has only whitespace, it should be considered empty and merged along with surrounding separators. LaTeX's \par is defined as such.

Fortunately, in HTML empty paragraphs designated as <p></p> do the same thing:

• Runs of <p></p> and whitespace (either between the tags or between tag pairs) are always merged together so there's no difference in text rendering
• If <p></p> is inserted between two paragraphs <p>... text ...</p> and <p>... more text ...</p>, it produces no additional spacing between paragraphs
• If <p></p> is inserted between two blocks of text that are not tagged with <p> (e.g. are body-level), a paragraph separator space is inserted.

That all means with this PR, we don't need to use $(P ...) around text in .dd files.

This change will enter in effect after dlang/dmd#5344 is merged.

[dlang-bot]

Thanks for your pull request, @andralex!

Bugzilla references

Fix	Bugzilla	Description
✓	17594	Define DDOC_BLANKLINE as an empty HTML paragraph, thus obviating the need to wrap text in $(P ...)

[CyberShadow]

Hmm. Seems like there's two notions at play here, depending on the output format:

• Paragraph separator (LaTeX's \par).
• Paragraph block (HTML's <p>).

As I understand, this tries to simulate paragraph separators in HTML by using an empty <p> block.

What happens if the surrounding text is already in a <p> block? I'm pretty sure that paragraph tags aren't nestable, meaning that in <p>a<p></p>b</p>, the b text is going to be completely outside any paragraph block.

It would certainly be a lot nicer to see a proper attempt at dlang/dmd#4338 instead of trying to hack our way around this problem,

Let's see what the doc tester results are going to look like.

[aG0aep6G]

We already have something similar in std.ddoc: DDOC_BLANKLINE = $(DIVC blankline)$(LF).

I suggest moving that to dlang.org.ddoc if the behavior is desired for the whole site. I'd prefer the div because it doesn't make a statement about its content, so it's less of a violation of semantic HTML.

[andralex]

@aG0aep6G good idea, done.

[adamdruppe]

On Tue, Jul 04, 2017 at 05:39:38PM +0000, Andrei Alexandrescu wrote: @adamdruppe see dlang/dmd#5344

yeah i just saw that merged after i commented and went back and deleted the comment since it no longer applies

[andralex]

Unrelated: @CyberShadow @s-ludwig I see a lot of errors in http://dtest.dlang.io/results/c0008ecf5c03916698a3295aeab89f0ac72bfa29/6c1f175178e8d33718e19c8aff2fb0c8fab2f349/build.log, even in a successful build, which I assume are benign. Is anyone looking over those? Are those adversely affecting the produced ddox?

[CyberShadow]

Front page has regressed (layout slightly broken, example roulette gone)

[CyberShadow]

https://github.com/dlang/dlang.org/blob/master/spec/expression.dd#L38-L45 looks fine, but new rendered version has a gratuitous amount of empty space between the definitions of Expression and CommaExpression

[andralex]

@CyberShadow thx. Looked into that, it's because that text is inside a <pre> block. Previously a \n was inserted which was rendered as an empty line. Then with <p> the space is larger, and with <div blankline> it's even larger. I remove the empty line because it was out of place in the first time.

[andralex]

Still investigating why the example roulette is gone. Insights?

[CyberShadow]

I remove the empty line because it was out of place in the first time.

There's going to be a lot of instances of these, that one was just an example; changing the source one at a time is not a "scalable solution".

I think a better approach would be a CSS rule that completely hides the divs in pre blocks, as pre blocks are already preformatted and don't need extra markup to indicate where empty lines should be.

[CyberShadow]

Still investigating why the example roulette is gone. Insights?

@@ -250,6 +257,7 @@ Neptune</code>
     var rouletteIndex = Math.floor(Math.random() * examples.length);
     var rouletteChild = examples[rouletteIndex];
     rouletteChild.style.display = "block";
+<div class="blankline"></div>
 
     // build a list of the titles of all examples and add an option chooser to
     // allow switching between them

It's inserting HTML in inline <script> blocks.

[CyberShadow]

The two-column layout on the download page is gone:

http://dtest.dlang.io/artifact/website-d3d32993d3f11fb3e18268c54c009f64183fbd17-0c2fbcb56f339375b16748f88170942e/web/download.html

[CyberShadow]

Either way, seems like this change breaks a lot of stuff, so will require a careful review of all changed pages. Before we further invest into it, do you have any simpler alternatives in mind? Perhaps defining this macro only on spec / article pages?

[adamdruppe]

On Tue, Jul 04, 2017 at 06:13:19PM +0000, Vladimir Panteleev wrote: It's inserting HTML in inline `<script>` blocks.

This is why for adrdox I ditched random macros and went with a context-aware implementation instead. Some of this is done with "magic macros" - they look like ddoc, but are actually treated specially. For example, $(RAW_HTML) is passed through without modification (it just counts matching parens to find the end) and could be used for stuff like inline javascript. Maybe ddoc needs something similar too.

[CyberShadow]

Maybe ddoc needs something similar too.

That would be https://issues.dlang.org/show_bug.cgi?id=16498 :)

[andralex]

I think a better approach would be a CSS rule that completely hides the divs in pre blocks, as pre blocks are already preformatted and don't need extra markup to indicate where empty lines should be.

That's a pretty cool idea, could you please implement it in parallel with this?

[CyberShadow]

That's a pretty cool idea, could you please implement it in parallel with this?

OK:

pre div.blankline { display: none; }

Here's your implementation :)

[andralex]

@CyberShadow cool, I added that to the css and also similar directives for lists (we want lists to be compactly spaced). I've also restricted the blanklines thing to the spec.

[CyberShadow]

I understand this commit is no longer needed.

[CyberShadow]

Ditto

[CyberShadow]

Let's see what this looks like

[andralex]

I assume this still appears as a change because it was a tab.

[CyberShadow]

Heh, indeed

[CyberShadow]

LGTM. Please rebase to squash the redundant commits.

[s-ludwig]

@andralex:

Unrelated: @CyberShadow @s-ludwig I see a lot of errors in http://dtest.dlang.io/results/c0008ecf5c03916698a3295aeab89f0ac72bfa29/6c1f175178e8d33718e19c8aff2fb0c8fab2f349/build.log, even in a successful build, which I assume are benign. Is anyone looking over those? Are those adversely affecting the produced ddox?

I'll open a ticked against DDOX for these. Usually this will result in a raw type being displayed instead of one that is properly cross linked.

[CyberShadow]

Heh, I wrote to squash unrelated commits, not all of them...