docs: Convert 404 page to rST

[PATCH] docs: Convert 404 page to rST

Posted by Martin Kletzander 1 year, 2 months ago

There is no markup equivalent for any of the <s/> or <del/> HTML tags, so this
is the only thing I came up with and it looks like it works.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
---
Sorry if I'm trampling on someone else's patches, I just figured out how to keep
the strike-through text Peter mentioned, so I'm sending it to "share the
knowledge" ;)

 docs/404.html.in     | 19 -------------------
 docs/404.rst         | 16 ++++++++++++++++
 docs/css/libvirt.css |  4 ++++
 docs/meson.build     |  7 +------
 4 files changed, 21 insertions(+), 25 deletions(-)
 delete mode 100644 docs/404.html.in
 create mode 100644 docs/404.rst

diff --git a/docs/404.html.in b/docs/404.html.in
deleted file mode 100644
index 0ac76f125af6..000000000000
--- a/docs/404.html.in
+++ /dev/null
@@ -1,19 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>404 page not found</h1>
-
-    <p>
-      Someone appears to have eaten the <del>penguin</del>
-      page you were looking for. You might want to try
-    </p>
-    <ul>
-      <li>going back to the <a href="https://libvirt.org/">home page</a> to find
-        a collection of links to interesting pages on this site</li>
-      <li>using the search box at the top right corner of the screen to
-        locate the content on this site or mailing list archives</li>
-    </ul>
-
-  </body>
-</html>
diff --git a/docs/404.rst b/docs/404.rst
new file mode 100644
index 000000000000..927a3e618b59
--- /dev/null
+++ b/docs/404.rst
@@ -0,0 +1,16 @@
+==================
+404 page not found
+==================
+
+.. role:: del
+   :class: del
+
+.. contents::
+
+Someone appears to have eaten the :del:`penguin` page you were looking
+for. You might want to try
+
+* going back to the `home page <https://libvirt.org/>`_ to find a collection
+  of links to interesting pages on this site
+* using the search box at the top right corner of the screen to
+  locate the content on this site or mailing list archives
diff --git a/docs/css/libvirt.css b/docs/css/libvirt.css
index 097dfcbe8e51..82f95d4a6808 100644
--- a/docs/css/libvirt.css
+++ b/docs/css/libvirt.css
@@ -636,3 +636,7 @@ th p, td p {
 #contents p.topic-title {
     display: none;
 }
+
+span.del {
+    text-decoration: line-through;
+}
diff --git a/docs/meson.build b/docs/meson.build
index a90c59866a71..96ca21509047 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,6 +22,7 @@ docs_html_in_files = [
 ]
 
 docs_rst_files = [
+  '404',
   'aclpolkit',
   'advanced-tests',
   'api',
@@ -251,12 +252,6 @@ html_xslt_gen += {
   'depends': aclperms_gen,
 }
 
-html_xslt_gen += {
-  'name': '404',
-  'source': 'docs' / '404.html.in',
-  'href_base': '/',
-}
-
 hvsupport_html_in = custom_target(
   'hvsupport.html.in',
   output: 'hvsupport.html.in',
-- 
2.39.1

Re: [PATCH] docs: Convert 404 page to rST

Posted by Peter Krempa 1 year, 2 months ago

On Tue, Feb 21, 2023 at 08:28:14 +0100, Martin Kletzander wrote:
> There is no markup equivalent for any of the <s/> or <del/> HTML tags, so this
> is the only thing I came up with and it looks like it works.
> 
> Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
> ---
> Sorry if I'm trampling on someone else's patches, I just figured out how to keep
> the strike-through text Peter mentioned, so I'm sending it to "share the
> knowledge" ;)
> 
>  docs/404.html.in     | 19 -------------------
>  docs/404.rst         | 16 ++++++++++++++++
>  docs/css/libvirt.css |  4 ++++
>  docs/meson.build     |  7 +------
>  4 files changed, 21 insertions(+), 25 deletions(-)
>  delete mode 100644 docs/404.html.in
>  create mode 100644 docs/404.rst

[...]

> diff --git a/docs/meson.build b/docs/meson.build
> index a90c59866a71..96ca21509047 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -22,6 +22,7 @@ docs_html_in_files = [
>  ]
>  
>  docs_rst_files = [
> +  '404',
>    'aclpolkit',
>    'advanced-tests',
>    'api',
> @@ -251,12 +252,6 @@ html_xslt_gen += {
>    'depends': aclperms_gen,
>  }
>  
> -html_xslt_gen += {
> -  'name': '404',
> -  'source': 'docs' / '404.html.in',
> -  'href_base': '/',
> -}
> -
>  hvsupport_html_in = custom_target(
>    'hvsupport.html.in',
>    output: 'hvsupport.html.in',

The 404 page is special in the way how it requires the 'href_base'
parameter to be set and the implications in doing that.

The reason for it is that it needs to work in an arbitrarily deep broken
URI e.g.: https://libvirt.org/asdfasdfzsdf/ssdfgsdg/

There relative URIs will not work properly.

On the other hand we can't get rid of the 'href_base' parameter as we do
want relative URIs to work properly for viewing the webpage from disk.
This also causes the 404 page break horribly when viewed from anywhere
else than the web server.

If you preserve the "absolute" href base for 404:

Reviewed-by: Peter Krempa <pkrempa@redhat.com>