Re: Duplicating website's formatting in local doc builds
On 2/14/20 8:56 PM, Peter Geoghegan wrote: > On Fri, Feb 14, 2020 at 5:51 PM Tom Lane wrote: >> Hm, I wouldn't go into that much detail; it'd likely soon be out of >> date anyway. I had in mind something more like "If the STYLE=website >> option is used, the generated HTML files will include references to >> stylesheets hosted at www.postgresql.org, so that viewing them will >> require network access." > > But everything else looks good, right? > > I would like to commit this patch shortly. Language updates attached...mostly kept Tom's suggestions. Thanks, Jonathan diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index c99198f5e5..64ebdb3257 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -276,6 +276,13 @@ checking for fop... fop doc/src/sgml$ make STYLE=website html + + +If the STYLE=website optoin is used, the generated HTML +files include references to stylesheets hosted on https://www.postgresql.org/docs/current/;>postgresql.org and +require network access to view. + diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl index 9edce52a10..d9961089c6 100644 --- a/doc/src/sgml/stylesheet-html-common.xsl +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -18,6 +18,14 @@ pgsql-docs@lists.postgresql.org 2 + + + docContent + container-fluid col-10 + diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl index 4ff6e8ed24..bc5a904e0b 100644 --- a/doc/src/sgml/stylesheet.xsl +++ b/doc/src/sgml/stylesheet.xsl @@ -23,11 +23,15 @@ stylesheet.css - https://www.postgresql.org/media/css/docs.css + + https://www.postgresql.org/media/css/fontawesome.css + https://www.postgresql.org/media/css/bootstrap.min.css + https://www.postgresql.org/media/css/main.css + https://www.postgresql.org/media/css/normalize.css + - signature.asc Description: OpenPGP digital signature
Re: Duplicating website's formatting in local doc builds
On Fri, Feb 14, 2020 at 5:51 PM Tom Lane wrote: > Hm, I wouldn't go into that much detail; it'd likely soon be out of > date anyway. I had in mind something more like "If the STYLE=website > option is used, the generated HTML files will include references to > stylesheets hosted at www.postgresql.org, so that viewing them will > require network access." But everything else looks good, right? I would like to commit this patch shortly. -- Peter Geoghegan
Re: Duplicating website's formatting in local doc builds
On 2/14/20 6:06 PM, Tom Lane wrote: > "Jonathan S. Katz" writes: >> To load the webfont, the "main.css" file uses a CSS "@import" >> instruction, which has a limitation that it can only be used as the top >> of the file. As main.css is not the first file in the "docs.csS" >> sandwich, it does not load. >> Buried in some version of the DocBook[1] documentation were in >> instructions on how to load in multiple stylesheets via >> >> which I followed in our XSLT, which lead to that portion of the diff. > > It looks to me like the main text font now matches, but the font used for > text doesn't quite -- see the attached, and note for example the > capital T's in CREATE TYPE. (Local build with this patch on the left, > website on the right.) Still, it's enormously closer than before. Hmm, I'm not getting that. They're both identical for me, at least in Chrome... ...but I hopped over into Safari, and I saw a difference between the local file in Chrome, and what .org looks like in Safari. I dove into this a bit. For this view, we are just using the default "monospace" font that is referenced by a particular browser. It seems like there was a change in Safari 12 where you can no longer override the default monospace font. It appears to be using "SF Mono." In Chrome, it appears that it is using Courier. A potential solution is that we drop the use of "monospace" in relying on the OS default and just pick a font. I would say that this is outside the scope of the patch that's being proposed, but certainly something to look into on the pgweb side given we're creating an inconsistent cross-browser experience. > >> Not included is one of Tom's original questions, which is should we just >> make using the website styles the default? As it stands, this would >> require network connectivity to preview the look for a page. If we want >> to ensure consistent views across the board, then I would say we import >> the stylesheets, knowing that "main.css" is volatile. > > The point about network access seems to me to be sufficient reason not > to make it the default. I'd actually say that we ought to annotate > section J.3.1 to point out that "make STYLE=website" will result in > that. However, I'm not quite clear on whether that means external > access during viewing, or during build, or both? The note should say. It would only be during viewing -- the build just puts the URL into the HTML file. But don't take my word for it, please see the attached patch ;) Jonathan diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index c99198f5e5..17f2bf42ac 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -276,6 +276,43 @@ checking for fop... fop doc/src/sgml$ make STYLE=website html + + +Viewing the documentation built using the https://www.postgresql.org/docs/current/;>postgresql.org +stylesheet requires Internet connectivity, as the HTML pages contain +references to remotely hosted stylesheets, including: + + + + https://www.postgresql.org/media/css/fontawesome.css;> +https://www.postgresql.org/media/css/fontawesome.css + + + + + + https://www.postgresql.org/media/css/bootstrap.min.css;> +https://www.postgresql.org/media/css/bootstrap.min.css + + + + + + https://www.postgresql.org/media/css/main.css;> +https://www.postgresql.org/media/css/main.css + + + + + + https://www.postgresql.org/media/css/normalize.css;> +https://www.postgresql.org/media/css/normalize.css + + + + + diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl index 9edce52a10..d9961089c6 100644 --- a/doc/src/sgml/stylesheet-html-common.xsl +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -18,6 +18,14 @@ pgsql-docs@lists.postgresql.org 2 + + + docContent + container-fluid col-10 + diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl index 4ff6e8ed24..bc5a904e0b 100644 --- a/doc/src/sgml/stylesheet.xsl +++ b/doc/src/sgml/stylesheet.xsl @@ -23,11 +23,15 @@ stylesheet.css - https://www.postgresql.org/media/css/docs.css + + https://www.postgresql.org/media/css/fontawesome.css + https://www.postgresql.org/media/css/bootstrap.min.css + https://www.postgresql.org/media/css/main.css + https://www.postgresql.org/media/css/normalize.css + - signature.asc Description: OpenPGP digital signature
Re: Getting our tables to render better in PDF output
Alvaro Herrera writes:
> On 2020-Feb-13, Alexander Lakhin wrote:
>> Third (minor) issue is with translation - when I will see some break in
>> the English source, e.g. "split_part('abc~@~def~@~ghi', '~@~',
>> 2)", should I leave the break in the same place, or it's better to move
>> it because adjacent text has different length and the table columns have
>> different width?
> If the English version is warning-clean, then it should be possible to
> keep the zwsps in the same location in the translation, and then tweak
> the translation according to any new warnings that appear there.
> My guess is that the majority of zwsps are going to want to stay in the
> same place.
So far as I've seen, the majority of places where we'll still need to
insert break opportunities are in examples and example results, which
don't seem like they'd be subject to translation. I'm really not eager to
turn loose an automatic-zwsp-inserter for a problem that might be mostly
hypothetical once we have a more forgiving table layout in place.
regards, tom lane
Re: Getting our tables to render better in PDF output
On 2020-Feb-13, Alexander Lakhin wrote:
> Yes, I was starting with manual insertions into the translation,
> but later I reduced such insertions just to several dozens. (For
> example, we still have "3.14159265358979323846" in the translation.)
> The main issue of the manual approach was that I needed to recheck that
> zwsp placement on updates, and I can't see where it's desired until I
> generate pdf. Fortunately, fop prints warning like that:
> [WARN] FOUserAgent - The contents of fo:block line 2 exceed the
> available area in the inline-progression direction by 22725 millipoints.
> (See position 127769:983)
> It's not very user-friendly, but still useful when we have a pair or two
> of them.
It seems to me that a productive way forward would be to fix the layout
to make these warning disappear. Then it will be relatively easy to find
where to fix, if new ones appear.
Now I suppose you're complaining about the "position 127769:983" part of
the error message which tells you with zero clarity where the problem
is. Maybe what we need is to figure out what the numbers mean, and how
to use them; for example if they are byte offsets into the file, then it
should be possible to tell your editor to go to that byte in the
complete XML file.
> Second issue is that the placement can depend on the page size and in
> fact most of that zwsps are not needed for html or other formats
> (moreover, some formats can require different placements (if we're not
> just implementing some common rules)).
I suppose A4 page size is going to show slightly different warnings than
Letter page size in the PDF output. Perhaps we can say that we only
care about warnings in one of them, for these purposes.
Having to touch 500+ places does not sound very appetizing, for sure.
> Third (minor) issue is with translation - when I will see some break in
> the English source, e.g. "split_part('abc~@~def~@~ghi', '~@~',
> 2)", should I leave the break in the same place, or it's better to move
> it because adjacent text has different length and the table columns have
> different width?
If the English version is warning-clean, then it should be possible to
keep the zwsps in the same location in the translation, and then tweak
the translation according to any new warnings that appear there.
My guess is that the majority of zwsps are going to want to stay in the
same place.
> Maybe some of the rules can be implemented explicitly in the DocBook
> source, just to reduce tons of zwsp in the generated output, or the
> "fo:table-cell/fo:block//text()" condition can be improved to filter
> some (text-only?) tables out, but I think that the idea of our specific
> line breaking rules could work.
Maybe we can mark-up specific table cells/columns as being subject to
the special line breaking rules.
--
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: documenting divergence from the SQL spec
On 2020-Feb-14, Dave Cramer wrote: > The wiki seems to be the dumping ground for everything that doesn't fit > into the documentation. > The problem with this is that if you don't know it is documented there it > is very difficult to find. Would it help to have some sort of index? The simplest I can think of is to add for each Nonstandard Clauses section, with something like Nonstandard Clauses in SELECT so that in the index you'd get a list of all commands that have Nonstandard Clauses subsections. Perhaps something more sophisticated can be built by using dedicated XML tags in an ad-hoc namespace. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Clarification on interactions between query parameters and partial indexes
PG Doc comments form writes: > In section "11.8 Partial Indexes" it states the following: > "Matching takes place at query planning time, not at run time. As a result, > parameterized query clauses do not work with a partial index. For example a > prepared query with a parameter might specify “x < ?” which will never imply > “x < 2” for all possible values of the parameter." > We decided to run some tests to verify this statement, as we use both > partial indexes and parameterized queries on some very large tables (100mil+ > rows). However, we are not able to replicate the stated behavior. It seems > like the query planner is able to make use of the partial index for both > parameterized and manually interpolated values. > Have we misunderstood what the documentation is trying to say or has this > limitation been fixed? The statement is true as far as it goes: "x < $1" will never be considered to imply "x < 2". However, there's a lot of context that's going unstated there. In some code paths, higher-level code such as the plan cache may try substituting the concrete value of a parameter as a constant, to see if it can get a better (but less general) plan that way. I think that's probably what happened in your experiment, but you didn't provide enough details to be sure. regards, tom lane
Re: documenting divergence from the SQL spec
Dave Cramer writes: > We have a section in the main docs for conformance > https://www.postgresql.org/docs/12/features.html > And then this https://wiki.postgresql.org/wiki/PostgreSQL_vs_SQL_Standard for > divergence. > I'd like to see the divergence section put into the main docs so that it is > easier to find. The individual statement reference pages already have sections for standards divergences. Admittedly, that framework doesn't help for discrepancies that can't be tied to a statement type ... but I don't think we should throw in duplicative material of this sort. It's tough enough to keep one instance of the info up-to-date. So I'd want to see some structure for this that respects that existing set of information. regards, tom lane
documenting divergence from the SQL spec
We have a section in the main docs for conformance https://www.postgresql.org/docs/12/features.html And then this https://wiki.postgresql.org/wiki/PostgreSQL_vs_SQL_Standard for divergence. I'd like to see the divergence section put into the main docs so that it is easier to find. Thoughts ? Dave Cramer www.postgres.rocks
Clarification on interactions between query parameters and partial indexes
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/indexes-partial.html Description: In section "11.8 Partial Indexes" it states the following: "Matching takes place at query planning time, not at run time. As a result, parameterized query clauses do not work with a partial index. For example a prepared query with a parameter might specify “x < ?” which will never imply “x < 2” for all possible values of the parameter." We decided to run some tests to verify this statement, as we use both partial indexes and parameterized queries on some very large tables (100mil+ rows). However, we are not able to replicate the stated behavior. It seems like the query planner is able to make use of the partial index for both parameterized and manually interpolated values. Have we misunderstood what the documentation is trying to say or has this limitation been fixed? PostgreSQL 10.1 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.4.7 20120313 (Red Hat 4.4.7-18), 64-bit PHP 7.2 PDO::prepare
