Re: [PATCH] Change text direction of documentation pages

On 1/17/22 11:01 AM, Magnus Hagander wrote:
> On Sun, Jan 2, 2022 at 11:03 PM Jonathan S. Katz <jkatz(at)postgresql(dot)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.

>> 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.

Jonathan