Thread: [PATCH] Change text direction of documentation pages
This makes the browser (tested on Firefox and Chrome. This does not
apply to Safari because it uses (what seems to be) heuristics to remove
generic information from the title and the title is displayed centered)
display the title right aligned in the tab bar allowing users to see
which page they are on, instead of only the beginning of the title being
visible, preventing switching between different documentation tabs
quickly.
This change was not generalised to other pages as the need is smaller on
other pages. For example on the home page, seeing "...open source
database" is not better than seeing "PostgreSQL: The world's...".
However this change could be beneficial for other pages as well.
---
templates/docs/docspage.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/templates/docs/docspage.html b/templates/docs/docspage.html
index f5f3e3b1..fef7f279 100644
--- a/templates/docs/docspage.html
+++ b/templates/docs/docspage.html
@@ -1,7 +1,7 @@
<!doctype html>
<html lang="en">
<head>
- <title>PostgreSQL: Documentation: {{page.display_version}}: {{page.title}}</title>
+ <title>PostgreSQL: Documentation: {{page.display_version}}: {{page.title}}</title>
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta http-equiv="Content-Type" content="text/xhtml; charset=utf-8" />
{%block meta%}{%endblock%} {# used for custom meta tags such as description which we don't want for every page #}
--
2.31.1
On Sun, Nov 7, 2021 at 5:31 PM Nils <nils@nilsand.re> wrote:
This makes the browser (tested on Firefox and Chrome. This does not
apply to Safari because it uses (what seems to be) heuristics to remove
generic information from the title and the title is displayed centered)
display the title right aligned in the tab bar allowing users to see
which page they are on, instead of only the beginning of the title being
visible, preventing switching between different documentation tabs
quickly.
This change was not generalised to other pages as the need is smaller on
other pages. For example on the home page, seeing "...open source
database" is not better than seeing "PostgreSQL: The world's...".
Interesting -- I had no idea this could be done :)
Thinking about it. I agree with the comment about the home page, but I wonder if that is the *only* case where it actually makes sense the way it is now, and that *all* other pages would be better off with this switch?
Can you (or someone else) think of another counterexample?
--
> On 24 Nov 2021, at 14:58, Magnus Hagander <magnus@hagander.net> wrote:
> On Sun, Nov 7, 2021 at 5:31 PM Nils <nils@nilsand.re <mailto:nils@nilsand.re>> wrote:
> This makes the browser (tested on Firefox and Chrome. This does not
> apply to Safari because it uses (what seems to be) heuristics to remove
> generic information from the title and the title is displayed centered)
> display the title right aligned in the tab bar allowing users to see
> which page they are on, instead of only the beginning of the title being
> visible, preventing switching between different documentation tabs
> quickly.
>
> This change was not generalised to other pages as the need is smaller on
> other pages. For example on the home page, seeing "...open source
> database" is not better than seeing "PostgreSQL: The world's...".
>
> Interesting -- I had no idea this could be done :)
Ditto.
> Thinking about it. I agree with the comment about the home page, but I wonder if that is the *only* case where it
actuallymakes sense the way it is now, and that *all* other pages would be better off with this switch?
>
> Can you (or someone else) think of another counterexample?
Looking at the precedent set by other documentation sites, I think we should do
the simpler fix of reversing the order of elements in the title tag like the
(untested) below:
- <title>PostgreSQL: Documentation: {{page.display_version}}: {{page.title}}</title>
+ <title>{{page.title}} — PostgreSQL {{page.display_version}} Documentation</title>
This will also work in all browsers and across all types of devices.
Shifting the order probably applies to more pages, but I agree that the docs
are especially interesting to tackle first.
--
Daniel Gustafsson https://vmware.com/
On 11/26/21 9:20 AM, Daniel Gustafsson wrote:
> Looking at the precedent set by other documentation sites, I think we should do
> the simpler fix of reversing the order of elements in the title tag like the
> (untested) below:
>
> - <title>PostgreSQL: Documentation: {{page.display_version}}: {{page.title}}</title>
> + <title>{{page.title}} — PostgreSQL {{page.display_version}} Documentation</title>
>
> This will also work in all browsers and across all types of devices.
>
> Shifting the order probably applies to more pages, but I agree that the docs
> are especially interesting to tackle first.
In general this is the preferred way to handle titles for web pages from
a SEO perspective (though that opens up a different topic) and I've
typically seen it done with a "|".
Overall OK with the approach, but would like to see how it renders.
Thanks,
Jonathan
Attachment
> On 26 Nov 2021, at 16:09, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 11/26/21 9:20 AM, Daniel Gustafsson wrote:
>
>> Looking at the precedent set by other documentation sites, I think we should do
>> the simpler fix of reversing the order of elements in the title tag like the
>> (untested) below:
>> - <title>PostgreSQL: Documentation: {{page.display_version}}: {{page.title}}</title>
>> + <title>{{page.title}} — PostgreSQL {{page.display_version}} Documentation</title>
>> This will also work in all browsers and across all types of devices.
>> Shifting the order probably applies to more pages, but I agree that the docs
>> are especially interesting to tackle first.
>
> In general this is the preferred way to handle titles for web pages from a SEO perspective (though that opens up a
differenttopic) and I've typically seen it done with a "|".
Looking at the docs pages on *.readthedocs.io, python.org, perldoc.perl.org,
rust-lang.org and php.net they all use variations of the dash, kubernetes.io
uses a pipe. I doubt that the choice of separator character (among commonly
used such separators) will play a huge role in SEO - but that being said, if I
Google "postgresql timestamp data type" the top hit is the 9.1 docs so maybe we
should just not care about SEO at all =)
> Overall OK with the approach, but would like to see how it renders.
I don't have a local pgweb setup for now, so feel free to pick it up and play
with it if you have time.
--
Daniel Gustafsson https://vmware.com/
On 11/29/21 4:16 AM, Daniel Gustafsson wrote:
>> Overall OK with the approach, but would like to see how it renders.
>
> I don't have a local pgweb setup for now, so feel free to pick it up and play
> with it if you have time.
Fast forward to the future, I went and played around with the suggested
patch, i.e.:
- <title>PostgreSQL: Documentation: {{page.display_version}}:
{{page.title}}</title>
+ <title>{{page.title}} — PostgreSQL {{page.display_version}}
Documentation</title>
It looks OK...but I question having the chapter/section prefix in the
title, i.e.:
"7.2 Table Expressions -- PostgreSQL 10 Documentation"
(yes, I need to update my local copy of the docs).
I think:
"Table Expressions -- PostgreSQL 10 Documentation"
would be better, esp. from the SEO perspective. This would also mean
adjusting our Open Graph tags to account for it from a display
perspective as well. And writing a function to strip out the prefix.
However, this opens up a few things:
1. On the main doc page, it now reads something like "PostgreSQL 13.5
Documentation - PostgreSQL 13 Documentation." That should be simple
enough to adjust though.
2. On this page:
https://www.postgresql.org/docs/10/typeconv-overview.html
the title would then read "Overview -- PostgreSQL 10 Documentation",
which also seems off. So perhaps the general algorithm becomes:
"Page Title -- Chapter Name -- PostgreSQL NN Documentation"
which would make that:
"Overview -- Type Conversation -- PostgreSQL 10 Documentation"
So, I think this is a little more work. I would propose this:
- In the doc loader script, extract the "chapter" name out of the
provided information and store it in DocPage OR dynamically extract it
while rendering a documentation page. I'm thinking the latter for this.
- Have a "page title" in the documentation available without the
chapter/section prefix
- Set the page title to be something like "Title w/o Prefix —
Chapter — PostgreSQL NN Documentation", with title/chapter dropped
if they're not present.
Thoughts?
Thanks,
Jonathan
Attachment
On Sun, Jan 2, 2022 at 11:03 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 11/29/21 4:16 AM, Daniel Gustafsson wrote:
>
> >> Overall OK with the approach, but would like to see how it renders.
> >
> > I don't have a local pgweb setup for now, so feel free to pick it up and play
> > with it if you have time.
>
> Fast forward to the future, I went and played around with the suggested
> patch, i.e.:
>
> - <title>PostgreSQL: Documentation: {{page.display_version}}:
> {{page.title}}</title>
> + <title>{{page.title}} — PostgreSQL {{page.display_version}}
> Documentation</title>
>
> It looks OK...but I question having the chapter/section prefix in the
> title, i.e.:
>
> "7.2 Table Expressions -- PostgreSQL 10 Documentation"
>
> (yes, I need to update my local copy of the docs).
>
> I think:
>
> "Table Expressions -- PostgreSQL 10 Documentation"
>
> would be better, esp. from the SEO perspective. This would also mean
> adjusting our Open Graph tags to account for it from a display
> perspective as well. And writing a function to strip out the prefix.
You're talking about changing just the <title> here right, and keeping
it in the <hx> tags?
> However, this opens up a few things:
>
> 1. On the main doc page, it now reads something like "PostgreSQL 13.5
> Documentation - PostgreSQL 13 Documentation." That should be simple
> enough to adjust though.
>
> 2. On this page:
>
> https://www.postgresql.org/docs/10/typeconv-overview.html
>
> the title would then read "Overview -- PostgreSQL 10 Documentation",
> which also seems off. So perhaps the general algorithm becomes:
>
> "Page Title -- Chapter Name -- PostgreSQL NN Documentation"
>
> which would make that:
>
> "Overview -- Type Conversation -- PostgreSQL 10 Documentation"
>
> So, I think this is a little more work. I would propose this:
>
> - In the doc loader script, extract the "chapter" name out of the
> provided information and store it in DocPage OR dynamically extract it
> while rendering a documentation page. I'm thinking the latter for this.
>
> - Have a "page title" in the documentation available without the
> chapter/section prefix
>
> - Set the page title to be something like "Title w/o Prefix —
> Chapter — PostgreSQL NN Documentation", with title/chapter dropped
> if they're not present.
>
> Thoughts?
Is this perhaps something that should be implemented in the docs
builder step for all HTML rather than do it one way there and then
try to change it for the website?
I do like the idea in general. But that might be a better place? (Note
that I have no idea how to actually do that, but I assume it can be
done)
--
Magnus Hagander
Me: https://www.hagander.net/
Work: https://www.redpill-linpro.com/
On 1/17/22 11:01 AM, Magnus Hagander wrote:
> On Sun, Jan 2, 2022 at 11:03 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>
>> On 11/29/21 4:16 AM, Daniel Gustafsson wrote:
>>
>>>> Overall OK with the approach, but would like to see how it renders.
>>>
>>> I don't have a local pgweb setup for now, so feel free to pick it up and play
>>> with it if you have time.
>>
>> Fast forward to the future, I went and played around with the suggested
>> patch, i.e.:
>>
>> - <title>PostgreSQL: Documentation: {{page.display_version}}:
>> {{page.title}}</title>
>> + <title>{{page.title}} — PostgreSQL {{page.display_version}}
>> Documentation</title>
>>
>> It looks OK...but I question having the chapter/section prefix in the
>> title, i.e.:
>>
>> "7.2 Table Expressions -- PostgreSQL 10 Documentation"
>>
>> (yes, I need to update my local copy of the docs).
>>
>> I think:
>>
>> "Table Expressions -- PostgreSQL 10 Documentation"
>>
>> would be better, esp. from the SEO perspective. This would also mean
>> adjusting our Open Graph tags to account for it from a display
>> perspective as well. And writing a function to strip out the prefix.
>
> You're talking about changing just the <title> here right, and keeping
> it in the <hx> tags?
Yes, just the title.
>> However, this opens up a few things:
>>
>> 1. On the main doc page, it now reads something like "PostgreSQL 13.5
>> Documentation - PostgreSQL 13 Documentation." That should be simple
>> enough to adjust though.
>>
>> 2. On this page:
>>
>> https://www.postgresql.org/docs/10/typeconv-overview.html
>>
>> the title would then read "Overview -- PostgreSQL 10 Documentation",
>> which also seems off. So perhaps the general algorithm becomes:
>>
>> "Page Title -- Chapter Name -- PostgreSQL NN Documentation"
>>
>> which would make that:
>>
>> "Overview -- Type Conversation -- PostgreSQL 10 Documentation"
>>
>> So, I think this is a little more work. I would propose this:
>>
>> - In the doc loader script, extract the "chapter" name out of the
>> provided information and store it in DocPage OR dynamically extract it
>> while rendering a documentation page. I'm thinking the latter for this.
>>
>> - Have a "page title" in the documentation available without the
>> chapter/section prefix
>>
>> - Set the page title to be something like "Title w/o Prefix —
>> Chapter — PostgreSQL NN Documentation", with title/chapter dropped
>> if they're not present.
>>
>> Thoughts?
>
> Is this perhaps something that should be implemented in the docs
> builder step for all HTML rather than do it one way there and then
> try to change it for the website?
>
> I do like the idea in general. But that might be a better place? (Note
> that I have no idea how to actually do that, but I assume it can be
> done)
Agreed that docs would likely be the better place to start. I can make a
vain attempt at this and see if I can come up with anything interesting.
Jonathan
Attachment
On Tue, Jan 18, 2022 at 5:28 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 1/17/22 11:01 AM, Magnus Hagander wrote:
> > On Sun, Jan 2, 2022 at 11:03 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
> >>
> >> On 11/29/21 4:16 AM, Daniel Gustafsson wrote:
> >>
> >>>> Overall OK with the approach, but would like to see how it renders.
> >>>
> >>> I don't have a local pgweb setup for now, so feel free to pick it up and play
> >>> with it if you have time.
> >>
> >> Fast forward to the future, I went and played around with the suggested
> >> patch, i.e.:
> >>
> >> - <title>PostgreSQL: Documentation: {{page.display_version}}:
> >> {{page.title}}</title>
> >> + <title>{{page.title}} — PostgreSQL {{page.display_version}}
> >> Documentation</title>
> >>
> >> It looks OK...but I question having the chapter/section prefix in the
> >> title, i.e.:
> >>
> >> "7.2 Table Expressions -- PostgreSQL 10 Documentation"
> >>
> >> (yes, I need to update my local copy of the docs).
> >>
> >> I think:
> >>
> >> "Table Expressions -- PostgreSQL 10 Documentation"
> >>
> >> would be better, esp. from the SEO perspective. This would also mean
> >> adjusting our Open Graph tags to account for it from a display
> >> perspective as well. And writing a function to strip out the prefix.
> >
> > You're talking about changing just the <title> here right, and keeping
> > it in the <hx> tags?
>
> Yes, just the title.
Then that works for me. I think it's important to keep the <hx>
heading be the same as it is in the source documents that we work
from, but I'm perfectly OK changing the <title> part.
> >> However, this opens up a few things:
> >>
> >> 1. On the main doc page, it now reads something like "PostgreSQL 13.5
> >> Documentation - PostgreSQL 13 Documentation." That should be simple
> >> enough to adjust though.
> >>
> >> 2. On this page:
> >>
> >> https://www.postgresql.org/docs/10/typeconv-overview.html
> >>
> >> the title would then read "Overview -- PostgreSQL 10 Documentation",
> >> which also seems off. So perhaps the general algorithm becomes:
> >>
> >> "Page Title -- Chapter Name -- PostgreSQL NN Documentation"
> >>
> >> which would make that:
> >>
> >> "Overview -- Type Conversation -- PostgreSQL 10 Documentation"
> >>
> >> So, I think this is a little more work. I would propose this:
> >>
> >> - In the doc loader script, extract the "chapter" name out of the
> >> provided information and store it in DocPage OR dynamically extract it
> >> while rendering a documentation page. I'm thinking the latter for this.
> >>
> >> - Have a "page title" in the documentation available without the
> >> chapter/section prefix
> >>
> >> - Set the page title to be something like "Title w/o Prefix —
> >> Chapter — PostgreSQL NN Documentation", with title/chapter dropped
> >> if they're not present.
> >>
> >> Thoughts?
> >
> > Is this perhaps something that should be implemented in the docs
> > builder step for all HTML rather than do it one way there and then
> > try to change it for the website?
> >
> > I do like the idea in general. But that might be a better place? (Note
> > that I have no idea how to actually do that, but I assume it can be
> > done)
>
> Agreed that docs would likely be the better place to start. I can make a
> vain attempt at this and see if I can come up with anything interesting.
Yeah, unfortunately I don't know too much about that side of things to
be able to help. Maybe Peter can?
--
Magnus Hagander
Me: https://www.hagander.net/
Work: https://www.redpill-linpro.com/
On 2/6/22 7:51 AM, Magnus Hagander wrote:
> On Tue, Jan 18, 2022 at 5:28 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>
>> On 1/17/22 11:01 AM, Magnus Hagander wrote:
>>> On Sun, Jan 2, 2022 at 11:03 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>>>
>>>> On 11/29/21 4:16 AM, Daniel Gustafsson wrote:
>>>>
>>>>>> Overall OK with the approach, but would like to see how it renders.
>>>>>
>>>>> I don't have a local pgweb setup for now, so feel free to pick it up and play
>>>>> with it if you have time.
>>>>
>>>> Fast forward to the future, I went and played around with the suggested
>>>> patch, i.e.:
>>>>
>>>> - <title>PostgreSQL: Documentation: {{page.display_version}}:
>>>> {{page.title}}</title>
>>>> + <title>{{page.title}} — PostgreSQL {{page.display_version}}
>>>> Documentation</title>
>>>>
>>>> It looks OK...but I question having the chapter/section prefix in the
>>>> title, i.e.:
>>>>
>>>> "7.2 Table Expressions -- PostgreSQL 10 Documentation"
>>>>
>>>> (yes, I need to update my local copy of the docs).
>>>>
>>>> I think:
>>>>
>>>> "Table Expressions -- PostgreSQL 10 Documentation"
>>>>
>>>> would be better, esp. from the SEO perspective. This would also mean
>>>> adjusting our Open Graph tags to account for it from a display
>>>> perspective as well. And writing a function to strip out the prefix.
>>>
>>> You're talking about changing just the <title> here right, and keeping
>>> it in the <hx> tags?
>>
>> Yes, just the title.
>
> Then that works for me. I think it's important to keep the <hx>
> heading be the same as it is in the source documents that we work
> from, but I'm perfectly OK changing the <title> part.
>
>
>>>> However, this opens up a few things:
>>>>
>>>> 1. On the main doc page, it now reads something like "PostgreSQL 13.5
>>>> Documentation - PostgreSQL 13 Documentation." That should be simple
>>>> enough to adjust though.
>>>>
>>>> 2. On this page:
>>>>
>>>> https://www.postgresql.org/docs/10/typeconv-overview.html
>>>>
>>>> the title would then read "Overview -- PostgreSQL 10 Documentation",
>>>> which also seems off. So perhaps the general algorithm becomes:
>>>>
>>>> "Page Title -- Chapter Name -- PostgreSQL NN Documentation"
>>>>
>>>> which would make that:
>>>>
>>>> "Overview -- Type Conversation -- PostgreSQL 10 Documentation"
>>>>
>>>> So, I think this is a little more work. I would propose this:
>>>>
>>>> - In the doc loader script, extract the "chapter" name out of the
>>>> provided information and store it in DocPage OR dynamically extract it
>>>> while rendering a documentation page. I'm thinking the latter for this.
>>>>
>>>> - Have a "page title" in the documentation available without the
>>>> chapter/section prefix
>>>>
>>>> - Set the page title to be something like "Title w/o Prefix —
>>>> Chapter — PostgreSQL NN Documentation", with title/chapter dropped
>>>> if they're not present.
>>>>
>>>> Thoughts?
>>>
>>> Is this perhaps something that should be implemented in the docs
>>> builder step for all HTML rather than do it one way there and then
>>> try to change it for the website?
>>>
>>> I do like the idea in general. But that might be a better place? (Note
>>> that I have no idea how to actually do that, but I assume it can be
>>> done)
>>
>> Agreed that docs would likely be the better place to start. I can make a
>> vain attempt at this and see if I can come up with anything interesting.
>
> Yeah, unfortunately I don't know too much about that side of things to
> be able to help. Maybe Peter can?
I have it on my backlog to investigate. Of course, if Peter has any
suggestions I am all ears (or eyes).
Thanks,
Jonathan