Re: Adding visual clues that accesskey exists
On Fri, Jan 20, 2023 at 6:07 AM Peter Eisentraut < peter.eisentr...@enterprisedb.com> wrote: > On 18.01.23 22:49, Corey Huinker wrote: > > Attached is a patch to add the nav- tags to the header (could just as > > easily have done the footer) for up/down/left/right and the javascript > > to find those ids and simulate a click. I've tested this on > > chrome (where accesskeys work with alt+ ) and firefox (where > > accesskeys don't seem to work at all) and it works as expected in both > > places. The javascript itself is rather naive, but serves as a starting > > point for discussion. > > This breaks the use of the arrow keys for scrolling. That doesn't seem > good. > Fair enough. Most desktops overload the shift/cmd/alt combinations of arrow keys, so there's not a lot of room to find an alternative.
Re: Adding visual clues that accesskey exists
>
> I agree that hot key discoverability could be better, but I don't think
> this is an issue in the PostgreSQL documentation; it's something the
> browser should handle. The job of the HTML markup is to declare the key
> -- then it's up to the browser how to present it. Otherwise, every
> single web page in the world (well, those with hot keys) would have to
> repeat this analysis, which seems on the wrong level to me.
>
I agree that that's a thing that browsers *should* be doing, but presently
none are (as far as I know), and the history of web development has many
examples of websites having to write crutches for deficient browsers so
that their users can have a decent experience, with the definition of
decent experience shifting over time.
Attached is a patch to add the nav- tags to the header (could just as
easily have done the footer) for up/down/left/right and the javascript to
find those ids and simulate a click. I've tested this on chrome (where
accesskeys work with alt+ ) and firefox (where accesskeys don't seem to
work at all) and it works as expected in both places. The javascript itself
is rather naive, but serves as a starting point for discussion.
In researching accesskey, I've noticed that the accesskey="t" stylesheet
section doesn't get rendered in our html anywhere. Was "t" = "table of
contents"? Seems like something we could delete until we need it again.
From c9a3d11cb8402c08b256adbc7b9ea1a3d3e7ff93 Mon Sep 17 00:00:00 2001
From: coreyhuinker
Date: Wed, 18 Jan 2023 16:00:10 -0500
Subject: [PATCH v1] Add javascript to enable up/next/previous navigation via
arrow keys
---
doc/src/sgml/stylesheet-speedup-xhtml.xsl | 6 ++
doc/src/sgml/stylesheet.xsl | 8
2 files changed, 10 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/stylesheet-speedup-xhtml.xsl b/doc/src/sgml/stylesheet-speedup-xhtml.xsl
index da0f2b5a97..d7e63ab38f 100644
--- a/doc/src/sgml/stylesheet-speedup-xhtml.xsl
+++ b/doc/src/sgml/stylesheet-speedup-xhtml.xsl
@@ -339,6 +339,12 @@
+
+document.addEventListener("keydown", function(event) { event.preventDefault();
+ if (event.key == "ArrowLeft") { document.getElementById('nav-prev').click(); }
+ else if (event.key == "ArrowRight") { document.getElementById('nav-next').click(); }
+ else if (event.key == "ArrowUp") { document.getElementById('nav-up').click(); } });
+
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index b6141303ab..6fe3c51e18 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -72,7 +72,7 @@ Customization of header
-
+
@@ -91,7 +91,7 @@ Customization of header
-
+
@@ -120,7 +120,7 @@ Customization of header
-
+
@@ -143,7 +143,7 @@ Customization of header
-
+
--
2.39.0
Adding visual clues that accesskey exists
Today I discovered that we already have accesskey support for navigation of our documentation. And it's been there since at least 2007, according to the mailing list archives. I discovered this accidentally, because I was researching something and just instinctively hit the right arrow in the vain hope that it was somehow linked to the "Next" link. Doing a view source on the page, I found the access keys: h = home, u = up, n = next, p = previous. That's great, and easy to remember for English speakers, everyone else less so. Accesskeys are primarily discovered via screen readers, so this isn't a huge problem, but having something language independent would be a nice touch. As far as I know, accesskeys cannot be the arrow keys. Accesskeys seem to have universal support (at least: Chrome, Edge, Firefox, Safari, Opera) now according to https://www.w3schools.com/tags/att_global_accesskey.asp but, as the page says, they are not recommended largely because desktops and browsers tend to reuse these keys. I would like to make this feature more discoverable and useful. Some ideas, in increasing order of complexity, are: 1. Add static hints to each link, so "Next" becomes "Next [n]". Fairly simple, but visually clumsy, and it might not actually clue the user that they need to hit ALT+n, not just "n". This chrome extension is an example of how it might look https://chrome.google.com/webstore/detail/display-access-keys/gpicedcgegaokienkdbbcagodgacpbpd?hl=en . The extension itself seems stale if not completely abandoned, but the screenshot gives a good visual representation. 2. Add the hint to the hovertext of the link. So, for example on https://www.postgresql.org/docs/current/libpq-exec.html the Hovertext for the "Next" link would become: "34.4 Asynchronous Command Processing [ALT+n]". This would lead to more accidental discovery, but wouldn't alter the existing static page appearance. 3. Add hotkey that launches an overlay which displays all available keyboard shortcuts. A common example of this is typing '?' in gmail or any other google web app. 4. Actually implement arrow keys with javascript, but leave the accesskeys as-is. I'm not a front-end programmer of any great skill, but it should be easy to capture the keydown event, filter for ArrowUp/ArrowLeft/ArrowRight, and then either search the DOM for the anchor with the corresponding accesskey, or rely on element ids (example: "nav-left", "nav-up", "nav-right") to find the anchor and invoke a .click() on it. Currently the navigation anchors do not have IDs, but adding them for this purpose might close us off from a future use. Thoughts?
Re: Additional Chapter for Tutorial
> > I plan to extend over time the part 'Tutorial' by an additional chapter > with an overview about key design decisions and basic features. The > typical audience should consist of persons with limited pre-knowledge in > database systems and some interest in PostgreSQL. In the attachment you > find a patch for the first sub-chapter. Subsequent sub-chapters should > be: MVCC, transactions, VACUUM, backup, replication, ... - mostly with > the focus on the PostgreSQL implementation and not on generic topics > like b-trees. > +1
Re: Getting our tables to render better in PDF output
On Mon, Apr 13, 2020 at 12:28 PM Tom Lane wrote: > Corey Huinker writes: > > I was thinking that there were references that included parameters, but > I'm > > not finding any with actual parameter values, so at most we'd lose the > "()" > > of a reference. > > We could possibly stick the parens into the indexterm text. Arguably > that's an improvement on its own merits, since it'd become clearer which > index entries are function names. If you don't want that, another idea is > to put xreflabel options that include the parens into the indexterm tags. > Or we can just standardize on not having parens, but personally I like > them. Without parens, for clarity you really have to write "function > foo" which is redundant-looking in the XML and hence > easy to get wrong. > That makes sense to me. There may be some hope for the font via the xrefstyle attribute, but I'm not educated well enough on docbook to know for sure. > > Assuming we want to make the anchors visible, we need a way for people to > > discover the anchors we've made, and my thought there is that we make the > > first definition a non-xref link to the indexterm just above it. Any > > thoughts on what the best way to do that is? > > I'm not really buying into that as a requirement. For one thing, the > anchor name will be 100% predictable. > The anchor name is deterministic (or I intend it to be) but the existence of the link is not predictable. So while having no visible link is fine for internal links which we create, I'm envisioning a not-very-experienced reader wanting to help an even-less-experienced person. If they find the date_part function, and they see that the word "date_part" is itself clickable, they'll probably click it once, see that it's a link, and send the less-experienced person the anchored link instead of the broader page link. They're very unlikely to try to forge their own anchor link in the hopes that it already exists. One thing that I noticed while playing with this last night is that > even though or links will take you right to the exact > table entry, the index entries generated from the indexterms only > point to the page. That seems pretty sad, why isn't it better? > As you've described it it does seem very odd, but maybe I'm just misunderstanding.
Re: Getting our tables to render better in PDF output
> > > I did a quick check by adding id tags to all 700-or-so s in > func.sgml (don't get excited, it was a perl one-liner that just added > random id strings). I did, actually, get excited for a second. > The runtime difference for building the HTML docs > seems to be under 1%, and negligible for PDF output. So it looks like > we don't have to worry about scalability of tagging all the functions. > Ok, so that's the function anchors. So some references to functions are just the name, and xrefs will work fine for those. I was thinking that there were references that included parameters, but I'm not finding any with actual parameter values, so at most we'd lose the "()" of a reference. Assuming we want to make the anchors visible, we need a way for people to discover the anchors we've made, and my thought there is that we make the first definition a non-xref link to the indexterm just above it. Any thoughts on what the best way to do that is?
Re: Getting our tables to render better in PDF output
On Sun, Apr 12, 2020 at 8:38 PM Tom Lane wrote: > Corey Huinker writes: > > On Sat, Apr 11, 2020 at 6:41 PM Tom Lane wrote: > >> Is that going to be a problem for the docs toolchain? If > >> the anchors are attached to individual function names rather than > >> sections or paragraphs, do they actually work well as link references? > >> (I'm particularly wondering how an would render.) > > > So I can't speak to any scalability issues for adding a bunch of refs, > but > > I did try this out for justify_days() (diff attached) and here's what I > > found: > > * justify_days > >This made a link, in the same font as any other link ref. > > * > >This made a link that looks exactly like the previous one, with the > text > > "justify_days", so if we're fine with the font change, we could use that > > * > linkend="function-justify-days">justify_days > >This made the link we want in the function font. > > Hm. Attaching the link ID to an is an interesting hack. > it worked for glossterms, I figured an indexterm is just another 'term. > My inclination is to standardize on using for references and > just accept the lack of a special font. It's not worth the notational > pain to use both and , especially not in HTML output > where links will probably get rendered specially anyway. We > previously made the same tradeoff with respect to GUC variables, > and I've not seen many complaints. (I experimented with putting > into the indexterm text, but that did not help.) > > I'd be a bit inclined to shorten the ID prefix to "func-", just > in the interests of carpal tunnel avoidance. > xref it is. I'll take a shot and scripting the necessary changes.
Re: Getting our tables to render better in PDF output
On Sat, Apr 11, 2020 at 6:41 PM Tom Lane wrote:
> Corey Huinker writes:
> > If it's ok to work on doc patches during the feature freeze, and if we're
> > already tweaking function documentation, would it be possible to add in
> > anchor ids to function definitions so that we could reference specific
> > functions (or rather the family of functions that share a name like this:
> >
> https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART
> > or similar. I tried it out just now, and the anchoring works, but there's
> > no obvious place to acquire the anchored link, so presumably we'd
> > anchor-ize the function name itself.
>
> Don't have a strong opinion about that, but it'd sure be a lot of new
> anchors.
True, but it'd would be a lot better than pointing a person to a page that
has 20+ functions defined on it.
> Is that going to be a problem for the docs toolchain? If
> the anchors are attached to individual function names rather than
> sections or paragraphs, do they actually work well as link references?
> (I'm particularly wondering how an would render.)
>
So I can't speak to any scalability issues for adding a bunch of refs, but
I did try this out for justify_days() (diff attached) and here's what I
found:
* justify_days
This made a link, in the same font as any other link ref.
*
This made a link that looks exactly like the previous one, with the text
"justify_days", so if we're fine with the font change, we could use that
* justify_days
This made the link we want in the function font.
The docbook spec doesn't allow an xref inside a function tag, and no tags
at all can be inside an xref.
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index c2e42f31c0..0b33d32a1b 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2766,7 +2766,9 @@ SELECT EXTRACT(days from '80 hours'::interval);
0
- Functions justify_days and
+ Functions and
+ Functions justify_days and
+ Functions justify_days and
justify_hours are available for adjusting days
and hours that overflow their normal ranges.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 12d75b476f..fd8ba334f8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -7079,7 +7079,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
-
+
justify_days
justify_days(interval)
Re: Getting our tables to render better in PDF output
On Sat, Apr 11, 2020 at 4:51 PM Tom Lane wrote: > I set this idea aside during the final v13 commitfest, but I figure that > it's fine to work on documentation improvements during feature freeze, > so I'm going to try to push it forward over the next few weeks. If it's ok to work on doc patches during the feature freeze, and if we're already tweaking function documentation, would it be possible to add in anchor ids to function definitions so that we could reference specific functions (or rather the family of functions that share a name like this: https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART or similar. I tried it out just now, and the anchoring works, but there's no obvious place to acquire the anchored link, so presumably we'd anchor-ize the function name itself.
Re: Keyword BYTEA missing from Documentation Appendix C
I'm working on a glossary patch with an actual technical writer, so it may belong on that new page. On Fri, Feb 7, 2020 at 10:15 AM Tom Lane wrote: > PG Doc comments form writes: > > https://www.postgresql.org/docs/12/sql-keywords-appendix.html > > BYTEA missing from Keyword list. > > Is this intentional? > > It's not a keyword, just a name that happens to be predefined. > > regards, tom lane > > >
