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>
 <CABUevEx56DATdAqRs9-JJwK6cnfq9LEJm3ZK7SuGV2n-ByH1cw@mail.gmail.com>
 <721b1b7d-873f-509b-7300-297cc65123bd@postgresql.org>
In-Reply-To: <721b1b7d-873f-509b-7300-297cc65123bd@postgresql.org>
From: Magnus Hagander <magnus@hagander.net>
Date: Sun, 6 Feb 2022 13:51:09 +0100
Message-ID: 
 <CABUevEx19rLrChGYSF+Jv1EzWTQC-WB=FcADi1W_r_J1ZvvQNQ@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,
	Peter Eisentraut <peter@eisentraut.org>
Content-Type: text/plain; charset="UTF-8"
Archived-At: 
 <https://www.postgresql.org/message-id/CABUevEx19rLrChGYSF%2BJv1EzWTQC-WB%3DFcADi1W_r_J1ZvvQNQ%40mail.gmail.com>
Precedence: bulk

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}} &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?
>
> 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 &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)
>
> 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/