MIME-Version: 1.0
References: <20211107163140.rnqihhpwrc5vwt2l@nixos>
 <CABUevEw+Trc7vnb=nH-_qQqQVg7qwwNsNrf_RFf6VmrqywwF8A@mail.gmail.com>
 <53D92024-85B0-4226-82A4-3A27CFA7880B@yesql.se>
 <31a6c019-83ef-2d12-b9c7-3829ee7977bf@postgresql.org>
 <B8D230AC-898D-411A-B26E-7FBCDE1A896C@yesql.se>
 <835f0d02-cc23-d333-fb16-ef370ca2e68b@postgresql.org>
In-Reply-To: <835f0d02-cc23-d333-fb16-ef370ca2e68b@postgresql.org>
From: Magnus Hagander <magnus@hagander.net>
Date: Mon, 17 Jan 2022 17:01:56 +0100
Message-ID: 
 <CABUevEx56DATdAqRs9-JJwK6cnfq9LEJm3ZK7SuGV2n-ByH1cw@mail.gmail.com>
Subject: Re: [PATCH] Change text direction of documentation pages
To: "Jonathan S. Katz" <jkatz@postgresql.org>
Cc: Daniel Gustafsson <daniel@yesql.se>, Nils <nils@nilsand.re>,
 pgsql-www@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Archived-At: 
 <https://www.postgresql.org/message-id/CABUevEx56DATdAqRs9-JJwK6cnfq9LEJm3ZK7SuGV2n-ByH1cw%40mail.gmail.com>
Precedence: bulk

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}} &mdash; 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 &mdash;
> Chapter &mdash; 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/