[ELPA] CSS improvements

[ELPA] CSS improvements

[Adam Porter]

[-- Attachment #1: Type: text/plain, Size: 340 bytes --]

Hi Stefan, Philip, et al,

ELPA's CSS currently has a few small issues: some elements have no top 
margins, so they run into preceding elements; and some heading levels 
have the same appearance as normal body text.

The attached patches resolve these problems and make, especially, 
package documentation much easier to read.

Thanks,
Adam

[-- Attachment #2: 0001-html-layout.css-p-Improve-margins.patch --]
[-- Type: text/x-patch, Size: 803 bytes --]

From c846798ff3f4cb19308c875cc37bf0a48537aa6d Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 11 Sep 2022 08:25:48 -0500
Subject: [PATCH 1/2] * html/layout.css (p): Improve margins

Previously, paragraphs only had bottom margins, which caused them to
have nearly no spacing between them and other, non-paragraph page
elements.  This change maintains the same spacing between paragraphs,
while adding space after other elements, which looks *much* better.
---
 html/layout.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/html/layout.css b/html/layout.css
index 48f9aa5fc7..59d88a3bec 100644
--- a/html/layout.css
+++ b/html/layout.css
@@ -127,7 +127,7 @@ pre .kw {
 }
 
 p {
-  margin-bottom: 2em;
+  margin: 1em 0 1em 0;
 }
 
 p.centered {
-- 
2.34.0


[-- Attachment #3: 0002-html-layout.css-h4-h5-Margins-text-decoration.patch --]
[-- Type: text/x-patch, Size: 856 bytes --]

From 5596bf6d98b1f00f2250f0c86f119b83bcda2131 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 11 Sep 2022 08:33:51 -0500
Subject: [PATCH 2/2] * html/layout.css (h4, h5): Margins, text-decoration

The margin changes add whitespace after other page elements, matching
the margins of other heading levels.  The text decorations visually
distinguish them from normal body text.  The result is much more
readable.
---
 html/layout.css | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/html/layout.css b/html/layout.css
index 59d88a3bec..dbd7a9626e 100644
--- a/html/layout.css
+++ b/html/layout.css
@@ -92,6 +92,14 @@ h3 {
   font-size: 1.5em;
   margin: 1.2em 0px;
 }
+h4 {
+  margin: 1em 0px;
+  text-decoration: underline;
+}
+h5 {
+  margin: 1em 0px;
+  text-decoration: italic;
+}
 
 a {
   color: #c73a6c;
-- 
2.34.0

Re: [ELPA] CSS improvements

[Stefan Monnier]

Hi Adam,

Adam Porter [2022-09-11 08:38:12] wrote:
> ELPA's CSS currently has a few small issues: some elements have no top
> margins, so they run into preceding elements; and some heading levels have
> the same appearance as normal body text.

I have very little practice with CSS, so if you could point me to some
concrete places (URL plus where in that page) which are improved, I'd
really appreciate it.
[ Clearly, that won't help me find out potential regressions, but it's
  better than nothing.  ]

Other than that, your patches look good, thanks (no need to resend
them).


        Stefan

Re: [ELPA] CSS improvements

[Philip Kaludercic]

Adam Porter <adam@alphapapa.net> writes:

> Hi Stefan, Philip, et al,
>
> ELPA's CSS currently has a few small issues: some elements have no top
> margins, so they run into preceding elements; and some heading levels
> have the same appearance as normal body text.
>
> The attached patches resolve these problems and make, especially,
> package documentation much easier to read.

I wonder if this could also be addressed by rethinking the "reset"-rule
at the beginning of layout.css.  I have tried removing it in Firefox,
and it doesn't look that bad (except for a few broken spacing rules that
shouldn't be that hard to solve).

> Thanks,
> Adam

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Hi Adam,
>
> Adam Porter [2022-09-11 08:38:12] wrote:
>> ELPA's CSS currently has a few small issues: some elements have no top
>> margins, so they run into preceding elements; and some heading levels have
>> the same appearance as normal body text.
>
> I have very little practice with CSS, so if you could point me to some
> concrete places (URL plus where in that page) which are improved, I'd
> really appreciate it.
> [ Clearly, that won't help me find out potential regressions, but it's
>   better than nothing.  ]

I've looked around and found at least two examples (that should
suffice for two patches):

- https://elpa.gnu.org/packages/vertico.html

  Look for a code block that is followed by a paragraph.  There is
  almost no space above a paragraph, but enough above.

- https://elpa.gnu.org/packages/ement.html

  Section 2.1 has a h4 title that is about the same size as the
  paragraph that follows it.  It appears at first as though the title is
  part of the paragraph, especially because the paragraph has a lot of
  space below it.

  Btw, Adam it seems there is some peculiar rendering just below the
  "2. Usage" title:  On GitHub there appears to be a manual TOC, while
  on the elpa.gnu.org it appears as a list with three empty elements.

> Other than that, your patches look good, thanks (no need to resend
> them).
>
>
>         Stefan

Re: [ELPA] CSS improvements

[Stefan Monnier]

> I've looked around and found at least two examples (that should
> suffice for two patches):
>
> - https://elpa.gnu.org/packages/vertico.html
>
>   Look for a code block that is followed by a paragraph.  There is
>   almost no space above a paragraph, but enough above.

Eww, yes that was poor.

> - https://elpa.gnu.org/packages/ement.html
>
>   Section 2.1 has a h4 title that is about the same size as the
>   paragraph that follows it.  It appears at first as though the title is
>   part of the paragraph, especially because the paragraph has a lot of
>   space below it.
>
>   Btw, Adam it seems there is some peculiar rendering just below the
>   "2. Usage" title:  On GitHub there appears to be a manual TOC, while
>   on the elpa.gnu.org it appears as a list with three empty elements.

Great, thanks, installed.

BTW, regarding the second patch: I'm no fan of underline, so it'd be
nice to find some other solution (bold maybe?).  Also, in that
ement.html page, I see now that the "2.1 Bindings" heading is
underlined, but the "2.1.1 Room buffers" is left unchanged whereas the
patch seemed to want to make it italics.

Is it a problem in the CSS or am I missing something?


        Stefan

Re: [ELPA] CSS improvements

[Philip Kaludercic]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I've looked around and found at least two examples (that should
>> suffice for two patches):
>>
>> - https://elpa.gnu.org/packages/vertico.html
>>
>>   Look for a code block that is followed by a paragraph.  There is
>>   almost no space above a paragraph, but enough above.
>
> Eww, yes that was poor.
>
>> - https://elpa.gnu.org/packages/ement.html
>>
>>   Section 2.1 has a h4 title that is about the same size as the
>>   paragraph that follows it.  It appears at first as though the title is
>>   part of the paragraph, especially because the paragraph has a lot of
>>   space below it.
>>
>>   Btw, Adam it seems there is some peculiar rendering just below the
>>   "2. Usage" title:  On GitHub there appears to be a manual TOC, while
>>   on the elpa.gnu.org it appears as a list with three empty elements.
>
> Great, thanks, installed.
>
> BTW, regarding the second patch: I'm no fan of underline, so it'd be
> nice to find some other solution (bold maybe?).  Also, in that
> ement.html page, I see now that the "2.1 Bindings" heading is
> underlined, but the "2.1.1 Room buffers" is left unchanged whereas the
> patch seemed to want to make it italics.
>
> Is it a problem in the CSS or am I missing something?

Yes there is, italics are set using "font-style: italic", not
"text-decoration".

>
>         Stefan

Re: [ELPA] CSS improvements

[Adam Porter]

[-- Attachment #1: Type: text/plain, Size: 1401 bytes --]

Hi Stefan, Philip,

On 9/11/22 10:04, Philip Kaludercic wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> Btw, Adam it seems there is some peculiar rendering just below
>>> the "2. Usage" title:  On GitHub there appears to be a manual
>>> TOC, while on the elpa.gnu.org it appears as a list with three
>>> empty elements.

Yes, that's caused by the table of contents in the readme, which is
generated for GitHub's renderer, which isn't compatible with Org's
exporter.  I'm not yet sure how to solve that problem, but I will when I
can.

>> Great, thanks, installed.

Thanks.

>> BTW, regarding the second patch: I'm no fan of underline, so it'd
>> be nice to find some other solution (bold maybe?).

Agreed.  I chose underline at first, because making H4s bold caused them 
to stand out more than H3s.  The new patches attached here make both H3 
and H4 bold, which seems to look good.  H5s remain italic.

>> Also, in that ement.html page, I see now that the "2.1 Bindings"
>> heading is underlined, but the "2.1.1 Room buffers" is left
>> unchanged whereas the patch seemed to want to make it italics.
>> 
>> Is it a problem in the CSS or am I missing something?
> 
> Yes there is, italics are set using "font-style: italic", not 
> "text-decoration".

Well, that's embarrassing.  Apparently I hadn't written CSS in too long. 
  The attached patches correct that as well.

Thanks,
Adam

[-- Attachment #2: 0001-html-layout.css-p-Improve-margins.patch --]
[-- Type: text/x-patch, Size: 803 bytes --]

From c846798ff3f4cb19308c875cc37bf0a48537aa6d Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 11 Sep 2022 08:25:48 -0500
Subject: [PATCH 1/2] * html/layout.css (p): Improve margins

Previously, paragraphs only had bottom margins, which caused them to
have nearly no spacing between them and other, non-paragraph page
elements.  This change maintains the same spacing between paragraphs,
while adding space after other elements, which looks *much* better.
---
 html/layout.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/html/layout.css b/html/layout.css
index 48f9aa5fc7..59d88a3bec 100644
--- a/html/layout.css
+++ b/html/layout.css
@@ -127,7 +127,7 @@ pre .kw {
 }
 
 p {
-  margin-bottom: 2em;
+  margin: 1em 0 1em 0;
 }
 
 p.centered {
-- 
2.34.0


[-- Attachment #3: 0002-html-layout.css-h4-h5-Margins-decoration-weight-styl.patch --]
[-- Type: text/x-patch, Size: 890 bytes --]

From 4b09b19b6953d84fc6aee63167d180815ade030b Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 11 Sep 2022 08:33:51 -0500
Subject: [PATCH 2/2] * html/layout.css (h4, h5): Margins, decoration, weight,
 style

The margin changes add whitespace after other page elements, matching
the margins of other heading levels.  The other changes visually
distinguish them from normal body text.  The result is much more
readable.
---
 html/layout.css | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/html/layout.css b/html/layout.css
index 59d88a3bec..f7fd276900 100644
--- a/html/layout.css
+++ b/html/layout.css
@@ -90,8 +90,17 @@ h2 {
 
 h3 {
   font-size: 1.5em;
+  font-weight: bold;
   margin: 1.2em 0px;
 }
+h4 {
+  margin: 1em 0px;
+  text-decoration: underline;
+}
+h5 {
+  margin: 1em 0px;
+  font-style: italic;
+}
 
 a {
   color: #c73a6c;
-- 
2.34.0

Re: [ELPA] CSS improvements

[Stefan Monnier]

> diff --git a/html/layout.css b/html/layout.css
> index 48f9aa5fc7..59d88a3bec 100644
> --- a/html/layout.css
> +++ b/html/layout.css
> @@ -127,7 +127,7 @@ pre .kw {
>  }
>  
>  p {
> -  margin-bottom: 2em;
> +  margin: 1em 0 1em 0;
>  }
>  
>  p.centered {
> -- 
> 2.34.0

Hmm... this patch seems like it's the same as the one I already installed.

> diff --git a/html/layout.css b/html/layout.css
> index 59d88a3bec..f7fd276900 100644
> --- a/html/layout.css
> +++ b/html/layout.css
> @@ -90,8 +90,17 @@ h2 {
>  
>  h3 {
>    font-size: 1.5em;
> +  font-weight: bold;
>    margin: 1.2em 0px;
>  }
> +h4 {
> +  margin: 1em 0px;
> +  text-decoration: underline;
> +}
> +h5 {
> +  margin: 1em 0px;
> +  font-style: italic;
> +}
>  
>  a {
>    color: #c73a6c;

An this one seems to also be based on the old version of the file.
Furthermore it still uses underline for h4 rather than bold, AFAICT.

I pushed what I think you intended to send instead :-)


        Stefan

Re: [ELPA] CSS improvements

[Adam Porter]

Hi Stefan,

On 9/11/22 16:27, Stefan Monnier wrote:

> Hmm... this patch seems like it's the same as the one I already 
> installed.

Oops, I didn't realize you'd already installed that.

> An this one seems to also be based on the old version of the file. 
> Furthermore it still uses underline for h4 rather than bold, AFAICT.
> 
> I pushed what I think you intended to send instead :-)

My apologies.  I shouldn't have been rushing to send patches before
bed.  Thanks for your help.