bug#43000: [Web pages] Proposed changes to tour/index.html

bug#43000: [Web pages] Proposed changes to tour/index.html

[Thérèse Godefroy]

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

Hello,

We are planning to migrate all templated pages on gnu.org to HTML5 in
order to improve accessibility. But before doing this, deprecated tags
such as <tt> and <acronym> need to be removed. Emacs has 2 templated
pages that contain <tt>: manual/emacs.html (maybe not in  use anymore),
and tour/index.html. I fixed the latter, but also had some fun restyling
it.

Summary of the changes:

* Replace <tt> with <kbd> or <code>: <kbd> for keyboard entries, and
<code> for the rest.

* Replace tables that are only used for layout with floating divs or
display:table + media queries.

* Modernize the "real" tables.

* Use the Emacs stylesheet, header and footer instead of the www.gnu.org
boilerplace.

The diff is rather big, but at least you can examine the page locally
because it doesn't need anything outside the emacs directory.

All the best,
Thérèse

PS. I sent a first draft to Nicolas Petton a few weeks ago, but there
were quite a few issues.

[-- Attachment #2: emacs.diff.gz --]
[-- Type: application/gzip, Size: 17779 bytes --]

bug#43000: [Web pages] Proposed changes to tour/index.html

[Stefan Kangas]

Hi Thérèse,

Thérèse Godefroy <godef.th@free.fr> writes:

> We are planning to migrate all templated pages on gnu.org to HTML5 in
> order to improve accessibility. But before doing this, deprecated tags
> such as <tt> and <acronym> need to be removed. Emacs has 2 templated
> pages that contain <tt>: manual/emacs.html (maybe not in  use anymore),
> and tour/index.html. I fixed the latter, but also had some fun restyling
> it.
>
> Summary of the changes:
>
> * Replace <tt> with <kbd> or <code>: <kbd> for keyboard entries, and
> <code> for the rest.
>
> * Replace tables that are only used for layout with floating divs or
> display:table + media queries.
>
> * Modernize the "real" tables.
>
> * Use the Emacs stylesheet, header and footer instead of the www.gnu.org
> boilerplace.
>
> The diff is rather big, but at least you can examine the page locally
> because it doesn't need anything outside the emacs directory.

Thanks for working on this.

I applied the patch and looked at the result in Firefox.  I couldn't
find anything that looked wrong during a cursory visual inspection.

(And the Guided Tour in particular looks much better.)

Best regards,
Stefan Kangas

bug#43000: [Web pages] Proposed changes to tour/index.html

[Thérèse Godefroy]

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

Hello Stephan,

Le 24/08/2020 à 04:13, Stefan Kangas a écrit :
[...)

> I applied the patch and looked at the result in Firefox.  I couldn't
> find anything that looked wrong during a cursory visual inspection.
> 
> (And the Guided Tour in particular looks much better.)
> 
> Best regards,
> Stefan Kangas
> 

Thanks for looking at the proposed layout. I made some minor adjustments
to the dl lists and tables. The idea is to place all command definitions
on a white backgrond (or any color you choose), whether they are in a
list or a table. The attached patch should be applied on top of the
first one.

Best,
Thérèse

[-- Attachment #2: emacs.1.diff --]
[-- Type: text/x-patch, Size: 2278 bytes --]

--- tour/index.html
+++ tour/index.1.html
@@ -40,8 +40,19 @@
 }
 dt {
-    margin: 2em 0 1em;
+    padding: .8em 3% 0;
+    margin: 0;
 }
 dd {
-    margin: 0 0 2em 3%;
+    padding: .5em 6% .8em;
+    margin: 0 0 8px;
+}
+dd p {
+    margin: 0;
+}
+dl {
+    margin: 0 0 2em;
+}
+dt, dd {
+    background: white;
 }
 kbd {
@@ -59,5 +70,4 @@
 }
 .screenshot {
-    text-align: center;
     margin: 0 auto;
     padding: .4em 0;
@@ -66,4 +76,8 @@
     margin: 0 auto 1.5em;
 }
+dl .command-screenshot {
+    margin: .7em auto 0;
+    padding: 0;
+}
 .xsmall {
     width: 15em;
@@ -122,13 +136,12 @@
     vertical-align: middle;
     padding: .5em 1em;
-    border-bottom: 2px solid #f5f5ed;
 }
-td:first-child {
-    border-right: 2px solid #f5f5ed;
+.commands td, .lists td {
+    border-bottom: 4px solid #f5f5ed;
 }
-
-.commands td:first-child {
+.commands td:first-child, .lists td:first-child {
     text-align: right;
     width: 30%;
+    border-right: 2px solid #f5f5ed;
 }
 .commands.calculate td:first-child {
@@ -138,5 +151,4 @@
     width: 48%;
 }
-
 .lists {
     margin-bottom: 1.5em;
@@ -145,12 +157,5 @@
     margin: 0;
 }
-.lists td:first-child {
-    text-align: right;
-    width: 30%; 
-}
-.lists.third table {
-}
 .lists.third td:first-child {
-    text-align: right;
     width: 40%; 
     margin: 0;
@@ -158,8 +163,13 @@
 .operations {
     table-layout: fixed;
+    border: 1px solid #ccc;
 }
-.operations thead {
+.operations thead td {
     font-weight: bold;
-    border-bottom: 4px solid #f5f5ed;
+    background: #ffe;
+    border-bottom: 1px solid #ccc;
+}
+.operations td:first-child {
+    border-right: 1px solid #ccc;
 }
 .operations.languages td:first-child {
@@ -1212,9 +1222,9 @@
   name of the mode:</p>
 
-<table class="commands">
+<table class="commands modes">
   <tr><td><kbd>M-x&nbsp;java-mode</kbd></td><td>Mode for editing Java files</td></tr>
   <tr><td><kbd>M-x&nbsp;python-mode</kbd></td><td>Mode for editing Python files</td></tr>
   <tr><td><kbd>M-x&nbsp;text-mode</kbd></td><td>Mode for editing text files</td></tr>
-  <tr><td><kbd>M-x&nbsp;fundamental-mode</kbd></td><td>Mode with no specializations at all</td></tr>
+  <tr><td><kbd>M-x fundamental-mode</kbd></td><td>Mode with no specializations at all</td></tr>
 </table>
 

bug#43000: [Web pages] Proposed changes to tour/index.html

[Stefan Kangas]

Thérèse Godefroy <godef.th@free.fr> writes:

> Thanks for looking at the proposed layout. I made some minor adjustments
> to the dl lists and tables. The idea is to place all command definitions
> on a white backgrond (or any color you choose), whether they are in a
> list or a table. The attached patch should be applied on top of the
> first one.

Looks even better.  The proposed colors LGTM, and should be easy enough
to change for anyone who feels like tweaking it later.

[Nit. Regarding the "Tour" in #1, it says "(Click on any of these
pictures for a larger view.)" but the first picture is missing a link.]

> -<table class="commands">
> +<table class="commands modes">
>    <tr><td><kbd>M-x&nbsp;java-mode</kbd></td><td>Mode for editing Java files</td></tr>
>    <tr><td><kbd>M-x&nbsp;python-mode</kbd></td><td>Mode for editing Python files</td></tr>
>    <tr><td><kbd>M-x&nbsp;text-mode</kbd></td><td>Mode for editing text files</td></tr>
> -  <tr><td><kbd>M-x&nbsp;fundamental-mode</kbd></td><td>Mode with no specializations at all</td></tr>
> +  <tr><td><kbd>M-x fundamental-mode</kbd></td><td>Mode with no specializations at all</td></tr>
>  </table>

Should the "&nbsp;" really be removed here?

I think the proposed changes should be installed.  Thanks again.

Best regards,
Stefan Kangas

bug#43000: [Web pages] Proposed changes to tour/index.html

[Thérèse Godefroy]

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

Le 26/08/2020 à 23:58, Stefan Kangas a écrit :
[...]
> [Nit. Regarding the "Tour" in #1, it says "(Click on any of these
> pictures for a larger view.)" but the first picture is missing a link.]

Thanks for catching this sneaky bug! It only affects wide screens (above
55em). What happens is that the big numbers are outside the normal flow,
and cover part  of the image. There are 2 ways to fix this:

* Push the numbers to the bottom layer with "z-index: -1".

* Give them enough margin to keep clear of the screenshots (9em works fine).

I chose the first option because it only takes one definition.

>> -<table class="commands">
>> +<table class="commands modes">
>>    <tr><td><kbd>M-x&nbsp;java-mode</kbd></td><td>Mode for editing Java files</td></tr>
>>    <tr><td><kbd>M-x&nbsp;python-mode</kbd></td><td>Mode for editing Python files</td></tr>
>>    <tr><td><kbd>M-x&nbsp;text-mode</kbd></td><td>Mode for editing text files</td></tr>
>> -  <tr><td><kbd>M-x&nbsp;fundamental-mode</kbd></td><td>Mode with no specializations at all</td></tr>
>> +  <tr><td><kbd>M-x fundamental-mode</kbd></td><td>Mode with no specializations at all</td></tr>
>>  </table>
> 
> Should the "&nbsp;" really be removed here?

In fact, it doesn't make any difference because the line wraps at the
second dash anyway. I wanted another wrapping point for very narrow
screens, but finally decided to linearize the tables below 35em.

The latest changes are in emacs.2.diff (attached).


I think it would be just as well to use dl lists for all the command
definitions. If the definitions are very short, they can be on the same
line as the command. We can even line them up vertically, table-like.


> I think the proposed changes should be installed.  Thanks again.

Would you like me to install them?

Best,
Thérèse

[-- Attachment #2: emacs.2.diff --]
[-- Type: text/x-patch, Size: 6039 bytes --]

--- tour/index.html
+++ tour/index.2.html
@@ -36,14 +36,41 @@
     margin: 2em 0 1.5em;
 }
-p, ul {
+p {
     margin: 0 0 1.5em 0;
 }
+kbd {
+    font-size: larger;
+    background: #ffe;
+}
+#content pre {
+    width: 12em;
+    margin: 0 auto 1.5em;
+}
+
+/* Lists */
+ul, ol  {
+    padding: 0 5%;
+    margin: 0 0 1.5em 0;
+}
+ol li {
+    list-style-type: decimal;
+}
+li {
+    margin: 0 0 .7em 1em;
+}
+ul.replace {
+    padding: .7em 5%;
+    background: white;
+}
+ul.replace li:last-child {
+    margin-bottom: 0;
+}
 dt {
-    padding: .8em 3% 0;
+    padding: .7em 3% 0;
     margin: 0;
 }
 dd {
-    padding: .5em 6% .8em;
-    margin: 0 0 8px;
+    padding: .5em 8% .7em;
+    margin: 0 0 .5em;
 }
 dd p {
@@ -56,12 +83,4 @@
     background: white;
 }
-kbd {
-    font-size: larger;
-    background: #ffe;
-}
-#content pre {
-    width: 12em;
-    margin: 0 auto 1.5em;
-}
 
 /* Images */
@@ -129,4 +148,5 @@
 /* Tables */
 table {
+    table-layout: fixed;
     width: 100%;
     background: white;
@@ -135,19 +155,19 @@
 td {
     vertical-align: middle;
-    padding: .5em 1em;
+    padding: .5em 1em .3em;
 }
-.commands td, .lists td {
+.commands tr, .lists tr {
     border-bottom: 4px solid #f5f5ed;
 }
 .commands td:first-child, .lists td:first-child {
     text-align: right;
-    width: 30%;
-    border-right: 2px solid #f5f5ed;
+    width: 28%;
+    padding-right: 0;
 }
 .commands.calculate td:first-child {
-    width: 42%;
+    width: 40%;
 }
 .commands.modes td:first-child {
-    width: 48%;
+    width: 43%;
 }
 .lists {
@@ -157,8 +177,4 @@
     margin: 0;
 }
-.lists.third td:first-child {
-    width: 40%; 
-    margin: 0;
-}
 .operations {
     table-layout: fixed;
@@ -180,4 +196,41 @@
 }
 
+@media (max-width: 35em) {
+  .commands td {
+    display: block;
+  }
+  .lists td {
+    display: inline-block;
+  }
+  .commands td, .lists td {
+    padding: 0;
+    border: none;
+  }
+  .commands td:first-child, .lists td:first-child {
+    width: auto;
+    text-align: left;
+    position: relative;
+    right: 1em;
+    margin-bottom: .2em;
+  }
+  .commands.calculate td:first-child,
+  .commands.modes td:first-child {
+    width: auto;
+  }
+  .commands tr, .lists tr {
+    display: block;
+    padding: .4em .5em .2em 1.5em;
+  }
+  .operations {
+    table-layout: auto;
+  }
+  .operations td {
+    padding: .5em;
+  }
+  .operations.replacements td:first-child {
+    width: auto;
+  }
+}
+
 @media (min-width: 55em) {
   .intro {
@@ -206,9 +259,7 @@
   p.number {
     position: relative;
-    padding-top: 2em;
+    z-index: -1;
     font-size: 4em;
-  }
-  td {
-    padding: .5em 1em;
+    padding-top: 2em;
   }
   .lists {
@@ -537,16 +588,13 @@
   jump anyway.</p>
 
-<div class="lists third">
-  <table>
-    <tr><td><kbd>C-u&nbsp;3&nbsp;C-p</kbd></td><td>Back 3 lines</td></tr>
-    <tr><td><kbd>C-u&nbsp;10&nbsp;C-f</kbd></td><td>Forward 10 characters</td></tr>
-    <tr><td><kbd>M-1&nbsp;M-0&nbsp;C-f</kbd></td><td>Forward 10 characters</td></tr>
-  </table>
-  <table>
-    <tr><td><kbd>C-u&nbsp;C-n</kbd></td><td>Forward 4 lines</td></tr>
-    <tr><td><kbd>C-u&nbsp;C-u&nbsp;C-n</kbd></td><td>Forward 16 lines</td></tr>
-    <tr><td><kbd>C-u&nbsp;C-u&nbsp;C-u&nbsp;C-n</kbd></td><td>Forward 64 lines</td></tr>
-  </table>
-</div>
+<table class="commands">
+  <tr><td><kbd>C-u&nbsp;3&nbsp;C-p</kbd></td><td>Back 3 lines</td></tr>
+  <tr><td><kbd>C-u&nbsp;10&nbsp;C-f</kbd></td><td>Forward 10 characters</td></tr>
+  <tr><td><kbd>M-1&nbsp;M-0&nbsp;C-f</kbd></td><td>Forward 10 characters</td></tr>
+  <tr><td><kbd>C-u&nbsp;C-n</kbd></td><td>Forward 4 lines</td></tr>
+  <tr><td><kbd>C-u&nbsp;C-u&nbsp;C-n</kbd></td><td>Forward 16 lines</td></tr>
+  <tr><td><kbd>C-u&nbsp;C-u&nbsp;C-u&nbsp;C-n</kbd></td><td>Forward 64 lines</td></tr>
+</table>
+
 <p>You can jump directly to a particular line number in a buffer:</p>
 
@@ -655,8 +703,12 @@
   argument for <kbd>C-k</kbd> can be used to kill multiple lines:</p>
 
-<table class="commands">
-  <tr><td><kbd>C-k</kbd></td><td>Kill line</td></tr>
-  <tr><td><kbd>C-u&nbsp;10&nbsp;C-k</kbd></td><td>Kill 10 lines</td></tr>
-</table>
+<div class="lists">
+  <table>
+    <tr><td><kbd>C-k</kbd></td><td>Kill line</td></tr>
+  </table>
+  <table>
+    <tr><td><kbd>C-u&nbsp;10&nbsp;C-k</kbd></td><td>Kill 10 lines</td></tr>
+  </table>
+</div>
 
 <p>The following commands operate on the region, and are the closest analogs to
@@ -692,5 +744,5 @@
   through previously killed items.</p>
 
-<table class="commands">
+<table class="commands yank">
   <tr><td><kbd>C-y</kbd></td><td>Yanks last killed text</td></tr>
   <tr><td><kbd>M-y</kbd></td><td>Replace yanked text with previously killed
@@ -775,5 +827,5 @@
 <p>These commands help you to issue previously issued queries:</p>
 
-<table class="commands search">
+<table class="commands">
   <tr><td><kbd>C-s&nbsp;C-s</kbd></td><td>Search for most recently searched item</td></tr>
   <tr><td><kbd>C-s&nbsp;M-p</kbd></td><td>Previous item in search history</td></tr>
@@ -805,5 +857,5 @@
   the search string. Here are some of the options available at each prompt:</p>
 
-<ul>
+<ul class="replace">
   <li>Type <kbd>y</kbd> to replace the current match.</li>
   <li>Type <kbd>n</kbd> to skip to the next match without replacing.</li>
@@ -915,5 +967,5 @@
 
 <p style="text-align:center">
-  <kbd>M-d&nbsp;C-d&nbsp;M-u,&nbsp;[SPC]&nbsp;C-y&nbsp;C-n&nbsp;C-a</kbd></p>
+  <kbd>M-d&nbsp;C-d&nbsp;M-u, [SPC]&nbsp;C-y&nbsp;C-n&nbsp;C-a</kbd></p>
 
 <p>After we record that key sequence as a macro, we can type <kbd>M-0&nbsp;F4</kbd> to
@@ -969,6 +1021,6 @@
 <p>For example, if I remember that I want to activate <em>narrowing</em>, but
   don't remember how, I can type <kbd>C-h&nbsp;a&nbsp;narrow&nbsp;RET</kbd> which shows a brief
-  list of commands having to do with <em>narrow</em>, one of which is <kbd>M-x</kbd>
-  <kbd>narrow-to-region</kbd>.</p>
+  list of commands having to do with <em>narrow</em>, one of which is <kbd>M-x
+  narrow-to-region</kbd>.</p>
 
 <h2>More useful features</h2>

bug#43000: [Web pages] Proposed changes to tour/index.html

[Stefan Kangas]

Thérèse Godefroy <godef.th@free.fr> writes:

>> I think the proposed changes should be installed.  Thanks again.
>
> Would you like me to install them?

Yes, please.

bug#43000: [Web pages] Proposed changes to tour/index.html

[Thérèse Godefroy]

Le 01/09/2020 à 16:36, Stefan Kangas a écrit :
> Thérèse Godefroy <godef.th@free.fr> writes:
> 
>>> I think the proposed changes should be installed.  Thanks again.
>>
>> Would you like me to install them?
> 
> Yes, please.
> 
Done.

bug#43000: [Web pages] Proposed changes to tour/index.html

[Stefan Kangas]

Hi Thérèse,

Thérèse Godefroy <godef.th@free.fr> writes:

> Done.

Thanks for doing that; it looks much better.

I'm seeing some oddities when navigating using the top row menu now:

1. I go to https://www.gnu.org/software/emacs/
2. I click Download in the top row menu
3. I click Home

I now end up at: https://www.gnu.org/savannah-checkouts/gnu/emacs/emacs.html

I would expect to end up back at https://www.gnu.org/software/emacs/

Could this be related to your recent changes?

Best regards,
Stefan Kangas

bug#43000: [Web pages] Proposed changes to tour/index.html

[Therese Godefroy]

Le 06/09/2020 à 05:47, Stefan Kangas a écrit :
[...]
> I'm seeing some oddities when navigating using the top row menu now:
> 
> 1. I go to https://www.gnu.org/software/emacs/
> 2. I click Download in the top row menu
> 3. I click Home
> 
> I now end up at: https://www.gnu.org/savannah-checkouts/gnu/emacs/emacs.html
> 
> I would expect to end up back at https://www.gnu.org/software/emacs/
> 
> Could this be related to your recent changes?
> 
> Best regards,
> Stefan Kangas
> 

Hello Stefan,

I don't think this has to do with recent changes. It has to do with URL
rewriting by an Apache module.

The URLs in your navigation links are relative to the current directory,
which happens to be on Savannah:
      <a href="emacs.html">Home</a>
      <a href="download.html">Download</a>

If you want them to be rewritten to the software directory, you need to
make the URLs relative to server root:
      <a href="/software/emacs/emacs.html">Home</a>
      <a href="/software/emacs/download.html">Download</a>

As a bonus, you will be able to move files from one directory to another
without breaking the links. For instance, the navlinks will be the same
in emacs.html and tour/index.html.

All the best,
Thérèse

bug#43000: [Web pages] Proposed changes to tour/index.html

[Stefan Kangas]

Therese Godefroy <thg@gnu.org> writes:

> I don't think this has to do with recent changes. It has to do with URL
> rewriting by an Apache module.
>
> The URLs in your navigation links are relative to the current directory,
> which happens to be on Savannah:
>       <a href="emacs.html">Home</a>
>       <a href="download.html">Download</a>
>
> If you want them to be rewritten to the software directory, you need to
> make the URLs relative to server root:
>       <a href="/software/emacs/emacs.html">Home</a>
>       <a href="/software/emacs/download.html">Download</a>
>
> As a bonus, you will be able to move files from one directory to another
> without breaking the links. For instance, the navlinks will be the same
> in emacs.html and tour/index.html.

Making the links absolute has the unfortunate side-effect that it
becomes harder to test the site locally during development, right?
I'd hope that there is some way to avoid that.

I see that there is a 302 (temporary) redirect here:

$ curl https://www.gnu.org/software/emacs/index.html
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>302 Found</title>
</head><body>
<h1>Found</h1>
<p>The document has moved <a
href="https://www.gnu.org/savannah-checkouts/gnu/emacs/emacs.html">here</a>.</p>
<hr>
<address>Apache/2.4.7 Server at www.gnu.org Port 443</address>
</body></html>

Do you know if this is expected?

Best regards,
Stefan Kangas

bug#43000: [Web pages] Proposed changes to tour/index.html

[Therese Godefroy]

Hello Stefan,

Le 07/09/2020 à 05:13, Stefan Kangas a écrit :
[...]
> Making the links absolute has the unfortunate side-effect that it
> becomes harder to test the site locally during development, right?
> I'd hope that there is some way to avoid that.

The only way I know of is to mount the emacs directory at the root of a
local web server. It's pretty convenient, in fact. But of course you
won't do all the fancy things that the gnu server does.

> I see that there is a 302 (temporary) redirect here:
> 
> $ curl https://www.gnu.org/software/emacs/index.html
> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
> <html><head>
> <title>302 Found</title>
> </head><body>
> <h1>Found</h1>
> <p>The document has moved <a
> href="https://www.gnu.org/savannah-checkouts/gnu/emacs/emacs.html">here</a>.</p>
> <hr>
> <address>Apache/2.4.7 Server at www.gnu.org Port 443</address>
> </body></html>
> 
> Do you know if this is expected?

I think this is expected, because you get it every time the index is
rewritten to another file. For instance, you get a 302 with gsrc
(index.html is rewritten to gsrc.html) but not with barcode (index.html
is a real file).

There are 2 sorts of rewrite directives:

* Some are in the Apache config. You and I can't change them (unless you
are a sysadmin). One of the things they do is rewrite
/software/emacs/emacs.html to /savannah-checkouts/gnu/emacs/emacs.html:

    RewriteCond /var/www/savannah-checkouts/gnu/$1 -d
    RewriteRule ^/software/([^/]+)(.*)$ /savannah-checkouts/gnu/$1$2

* Others are generated from the .symlinks files, which webmasters and
package maintainers can edit. Emacs has at least one:

    https://www.gnu.org/software/emacs/.symlinks

Here is the first line:

    emacs.html index.html

It is used to generate an entry in a rewrite map which is processed by a
series of directives. The last one ends with [R,L], explaining the 302.

Best,
Thérèse

bug#43000: [Web pages] Proposed changes to tour/index.html

[Stefan Kangas]

Hi Therese,

Therese Godefroy <thg@gnu.org> writes:

> I think this is expected, because you get it every time the index is
> rewritten to another file.

OK, thank you.  I'm therefore closing this bug.

Best regards,
Stefan Kangas