public inbox for [email protected]  

help / color / mirror / Atom feed
From: Jonathan S. Katz <[email protected]>
To: Magnus Hagander <[email protected]>
Cc: Daniel Gustafsson <[email protected]>
Cc: Nils <[email protected]>
Cc: [email protected]
Cc: Peter Eisentraut <[email protected]>
Subject: Re: [PATCH] Change text direction of documentation pages
Date: Sun, 6 Feb 2022 10:10:23 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <CABUevEx19rLrChGYSF+Jv1EzWTQC-WB=FcADi1W_r_J1ZvvQNQ@mail.gmail.com>
References: <20211107163140.rnqihhpwrc5vwt2l@nixos>
	<CABUevEw+Trc7vnb=nH-_qQqQVg7qwwNsNrf_RFf6VmrqywwF8A@mail.gmail.com>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<CABUevEx56DATdAqRs9-JJwK6cnfq9LEJm3ZK7SuGV2n-ByH1cw@mail.gmail.com>
	<[email protected]>
	<CABUevEx19rLrChGYSF+Jv1EzWTQC-WB=FcADi1W_r_J1ZvvQNQ@mail.gmail.com>

On 2/6/22 7:51 AM, Magnus Hagander wrote:
> On Tue, Jan 18, 2022 at 5:28 PM Jonathan S. Katz <[email protected]> wrote:
>>
>> On 1/17/22 11:01 AM, Magnus Hagander wrote:
>>> On Sun, Jan 2, 2022 at 11:03 PM Jonathan S. Katz <[email protected]> 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?

I have it on my backlog to investigate. Of course, if Peter has any 
suggestions I am all ears (or eyes).

Thanks,

Jonathan


Attachments:

  [application/pgp-signature] OpenPGP_signature (840B, 2-OpenPGP_signature)
  download

reply
Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
  Subject: Re: [PATCH] Change text direction of documentation pages
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox