~adnano/kiln-discuss

4 2

Re: Seeking feedback for kiln 0.2.0

Details
Message ID
<CB75IBK8FIXE.2CL0WZAQW0TZT@lappythevirtual>
DKIM signature
missing
Download raw message
Hi, Adnan!

Thank you for making Kiln! 

I found what I believe may be an issue. It's not with kiln, but instead
is with the gmnitohtml utility that kiln can use to translate .gmi files
to HTML.

# Issue

When converting a `text/gemini` document to HTML using `gmnitohtml`, the
resulting HTML document contains unnecessary `<br>` tags that result in
the document being displayed with too much whitespace between lines.

# Rule

Section 5.4.1 of the `text/gemini` specification provides for the following:

> Blank lines are instances of text lines and have no special meaning.  They
> should be rendered individually as vertical blank space each time they occur.
> In this way  they are analogous to <br/> tags in HTML.  Consecutive blank lines
> should NOT be collapsed into a fewer blank lines.  Note also that consecutive
> non-blank text lines do not form any kind of coherent unit or block such as a
> "paragraph": all text lines are independent entities.

# Analysis

The requirement that blank lines are rendered individually as vertical
blank space makes sense in a situation where plain text is displayed in
what is essentially an unchanged form, which is how most (all?) gemini
clients behave. The only way to create vertical whitespace in such a
situation is to render each blank line separately.

However, in the case of a `text/gemini` document that has been rendered
into HTML, vertical whitespace will be added to the document by the
browser when it encounters a header or paragraph closing tag. This makes
the addition of a `<br>` tag between (for example) consecutive
paragraphs both unnecessary and visually disturbing.

In other words, this `text/gemini` content:

```
# Test Heading

First test paragraph goes here. 

Second test paragraph goes here.
```

Is currently being translated to this HTML:

```
<h1>Test Heading</h1>
<br>
<p>First test paragraph goes here.</p>
<br>
<p>Second test paragraph goes here.</p>
<br>
```

But should (probably) be translated to this HTML instead:

```
<h1>Test Heading</h1>
<p>First test paragraph goes here.</p>
<p>Second test paragraph goes here.</p>
```

The `text/gemini` specification requires the preservation of consecutive
blank lines, so this `text/gemini` content:

```
# Test Heading

First test paragraph goes here. 



First test paragraph goes here. 
```

Should (probably) be translated to this HTML:

```
<h1>Test Heading</h1>
<p>First test paragraph goes here.</p>
<br />
<br />
<p>Second test paragraph goes here.</p>
```

# Conclusion

The correct heuristic seems to be that the _first_ blank line should be
ignored by the `gmnitohtml` translator. This is because the vertical
whitespace that the first `<br> tag is intended to create is already
provided by the browser at the close of the HTML element (`</p>` or
`</hN>`, for example). Subsequent blank lines (consecutive blank lines
that appear after the first blank line) should be rendered as `<br />`
tags, however, in order to comply with the provision of section 5.4.1 of
the `text/gemini` specification that requires that consecutive blank
lines are not collapsed into fewer blank lines.

It may be that this doesn't make sense to implement, but I've found that
I get much better visual results if I remove the unnecessary `<br>` tags
from the HTML output files.

Thank you again for creating kiln!

Raph

Re: Seeking feedback for kiln 0.2.0

Details
Message ID
<CB788Y2ZP6HE.J6HV4YS0OIDB@nitro>
In-Reply-To
<CB75IBK8FIXE.2CL0WZAQW0TZT@lappythevirtual> (view parent)
DKIM signature
pass
Download raw message
On Fri May 7, 2021 at 12:24 PM EDT, Raph M. wrote:
>
> Hi, Adnan!
>
> Thank you for making Kiln!

Glad you like it!

> I found what I believe may be an issue. It's not with kiln, but instead
> is with the gmnitohtml utility that kiln can use to translate .gmi files
> to HTML.
>
> # Issue
>
> When converting a `text/gemini` document to HTML using `gmnitohtml`, the
> resulting HTML document contains unnecessary `<br>` tags that result in
> the document being displayed with too much whitespace between lines.
>
> # Rule
>
> Section 5.4.1 of the `text/gemini` specification provides for the
> following:
>
> > Blank lines are instances of text lines and have no special meaning.  They
> > should be rendered individually as vertical blank space each time they occur.
> > In this way  they are analogous to <br/> tags in HTML.  Consecutive blank lines
> > should NOT be collapsed into a fewer blank lines.  Note also that consecutive
> > non-blank text lines do not form any kind of coherent unit or block such as a
> > "paragraph": all text lines are independent entities.

This was the original motivation for inserting <br> tags. It requires
some CSS to remove excess margins, though. I agree that the default
behavior is not very pleasant. I was considering moving this
functionality behind a command-line flag, but I am now considering
removing <br> tags completely.

> The correct heuristic seems to be that the _first_ blank line should be
> ignored by the `gmnitohtml` translator. This is because the vertical
> whitespace that the first `<br> tag is intended to create is already
> provided by the browser at the close of the HTML element (`</p>` or
> `</hN>`, for example). Subsequent blank lines (consecutive blank lines
> that appear after the first blank line) should be rendered as `<br />`
> tags, however, in order to comply with the provision of section 5.4.1 of
> the `text/gemini` specification that requires that consecutive blank
> lines are not collapsed into fewer blank lines.

This is an interesting idea that I hadn't thought of. I may end up
adopting this approach if I don't get rid of <br> tags completely.

Thanks for the feedback!

Re: Seeking feedback for kiln 0.2.0

Details
Message ID
<CB7XMYDKHAGS.3CJI53B7Z0IOE@lappythevirtual>
In-Reply-To
<CB788Y2ZP6HE.J6HV4YS0OIDB@nitro> (view parent)
DKIM signature
missing
Download raw message
On Fri May 7, 2021 at 11:32 AM PDT, Adnan Maolood wrote:
> On Fri May 7, 2021 at 12:24 PM EDT, Raph M. wrote:
>
> > The correct heuristic seems to be that the _first_ blank line should be
> > ignored by the `gmnitohtml` translator. [snip] 
>
> This is an interesting idea that I hadn't thought of. I may end up
> adopting this approach if I don't get rid of <br> tags completely.

It would be a relatively simple change, I think. If you add a `multibr`
bool field to the `HTMLWriter` struct, it seems like all you'd need
after that would something along these lines:

```
	...
        case gemini.LineText:
		if line == "" {
			if h.multibr {
				fmt.Fprint(h.out, "<br />\n")
			}
			h.multibr = true
		} else {
			fmt.Fprintf(h.out, "<p>%s</p>\n", html.EscapeString(string(line)))
		}
	} // end of switch line := line.(type) 
	if line.String() != "" {
		h.multibr = false
	}

}
```

I can send an actual patch if it would be helpful. 

I also think your original idea of just ignoring the vertical whitespace
(and not emitting the `<br>` tags) would be a good solution as well. It
seems like there is a strong case to be made for making the behavior be
configurable via a command line flag, since different authors may prefer
different behaviors.

Raph

Re: Seeking feedback for kiln 0.2.0

Details
Message ID
<CB83Y5PS0K8Z.GTA4U51S7UDA@nitro>
In-Reply-To
<CB7XMYDKHAGS.3CJI53B7Z0IOE@lappythevirtual> (view parent)
DKIM signature
pass
Download raw message
I went ahead and adopted your approach. We'll see how it plays out.

Re: Seeking feedback for kiln 0.2.0

Details
Message ID
<CB9MQEMZI3SR.2ZDM751O4S6QI@tinytopper>
In-Reply-To
<CB83Y5PS0K8Z.GTA4U51S7UDA@nitro> (view parent)
DKIM signature
missing
Download raw message
On Sat May 8, 2021 at 12:23 PM PDT, Adnan Maolood wrote:
> I went ahead and adopted your approach. We'll see how it plays out.

It seems to work very well. Thank you, Adnan!

Raph
Reply to thread Export thread (mbox)