Re: Another modest proposal for docs formatting: catalog descriptions

[Alvaro Herrera]

On 2020-May-06, Jonathan S. Katz wrote:

> I know that 9.6 uses a different subset of the styles, and I recall the
> text being blue during the original conversion. For example, the "table"
> in the 9.6 docs has a class of "CALSTABLE" whereas in master, it is
> "table" (and we operate off of it as "table.table" when doing lookups,
> to ensure anything else with class "table" is unaffected).
> 
> There's also not as much control over some of the older documentation as
> there are less classes we can bind the CSS too.
> 
> The latest changes should only affect master (devel) and beyond.

... oh, okay.  I guess I was reporting that the font on the new version
seems to have got smaller.  Looking at other pages, it appears that the
font is indeed a lot smaller in all tables, including those Tom has been
editing.  So maybe this is desirable for some reason.  I'll have to keep
my magnifying glass handy, I suppose.

Anyway, it seems  or whatever tag has been used in some
of these new tables makes the font be larger.  Another screenshot is
attached to show this.  Is this likewise desired?  It also shows that
the main text body is sized similar to the  tagged text,
not the table contents text.  (The browser is Brave, a Chromium
derivative.)

-- 
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/6/20 5:18 PM, Alvaro Herrera wrote:
> Hello
> 
> I think the recent changes to CSS might have broken things in the XSLT
> build; apparently the SGML tooling did things differently.  Compare the
> screenshot of tables 67.2 and 67.3 ... 9.6 on the left, master on the
> right.  Is the latter formatting correct/desirable?

I know that 9.6 uses a different subset of the styles, and I recall the
text being blue during the original conversion. For example, the "table"
in the 9.6 docs has a class of "CALSTABLE" whereas in master, it is
"table" (and we operate off of it as "table.table" when doing lookups,
to ensure anything else with class "table" is unaffected).

There's also not as much control over some of the older documentation as
there are less classes we can bind the CSS too.

The latest changes should only affect master (devel) and beyond.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: JSON function docs page broken in HEAD

[Thom Brown]

On Wed, 6 May 2020 at 18:10, Tom Lane  wrote:
>
> Thom Brown  writes:
> > I noticed that the tables on JSON functions and operators page in
> > devel aren't rendering correctly.
>
> What do you think isn't correct?  We're in process of changing the
> design for function/operator tables, so it's certainly *different*
> from the way it's looked in the past, but I don't immediately see
> anything there that's not per the new design.

My mistake.  It looked like there may have been missing table cell
tags causing fields to collapse, but I can see the new layout is
designed for long examples.

Apologies for the noise.
-- 
Thom

Re: JSON function docs page broken in HEAD

[Tom Lane]

Thom Brown  writes:
> I noticed that the tables on JSON functions and operators page in
> devel aren't rendering correctly.

What do you think isn't correct?  We're in process of changing the
design for function/operator tables, so it's certainly *different*
from the way it's looked in the past, but I don't immediately see
anything there that's not per the new design.

regards, tom lane

JSON function docs page broken in HEAD

[Thom Brown]

Hi,

I noticed that the tables on JSON functions and operators page in
devel aren't rendering correctly.

https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-JSON-PROCESSING

-- 
Thom

Re: Direct links to edit documentation

[Magnus Hagander]

On Tue, May 5, 2020 at 4:49 PM Bruce Momjian  wrote:

> On Mon, May  4, 2020 at 07:06:55PM +0200, Magnus Hagander wrote:
> > I see how that can be pretty useful for something that's as simple as
> asciidoc.
> > But I wonder how useful it would be for our docbook documentation.
> >
> > There'd be no preview (which there i sin the elastic), and we know how
> > difficult it can be to get the tags right without running test builds
> even for
> > those that are used to working in the system.
> >
> > Though if what we're considering are basically drive-by typo fixes and
> such,
> > those would probably work in a scenario like that, since you're unlikely
> to
> > need a preview or break a build.
> >
> > Another complication would be that we don't have a 1-1 mapping between
> source
> > files and output URLs. So you'd have to find some way to track it back
> to the
> > exactly right portion of the source file. This would probably be
> possible if we
> > were to do it as a feature on our own site (and not just a
> > source-edit-on-github-style), but it would probably ont be a trivial
> piece of
> > work. Question is if the benefit would outweigh the cost, compared to
> just
> > receiving comments and "manually patching them in".
>
> All I can say is that most emails we get about the docs using the form
> are just complaints, and we have to write some suggested text and get
> approaval from the reporter that the text is clear.  We don't  get many
> acutal _suggestions_.
>

Agreed. I think the argument made is that if we had direct editing, maybe
we'd get more actual suggestions vs just reports/complaints.

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: Documentation - chapter 52, system catalogs

[Jürgen Purtz]

On 06.05.20 00:01, Tom Lane wrote:

I don't deny that we have a problem here: in the website rendering,
that text tends to be pushed down out of sight by the chapter's
sub-table-of-contents.  But that issue exists for every chapter
that's got more than a couple of sections.  We shouldn't hack
around it for just these two chapters.  Chapter 9 and Appendix F
are additional examples where this is a fairly urgent issue.

Generic solutions are always better than individual ones.

I wonder if we should just drop the sub-table-of-contents material.
(I'm assuming DocBook can be coerced to do that; but since the PDF
output has no such material, it seems like it ought to be possible.)
If we drop TOCs, we loose the automatically created links. As a 
substitute we would need tables like in example 51.1. So it's again an 
individual solution.

Or ... is there a way to postpone it to the bottom of the page,
ie just before the first , instead of having it in front
of the chapter preface?

The same issue exists for the sub-sub-tables-of-contents for s,
though it's less bad because few of those have grown enormous lists
of 's.


Swapping TOC and content may work in such cases, but for me it seems to 
be a hard work with xslt.


A real generic solution would be an adaption of the HTML output to the 
PDF output: two columns with a collapsible menu containing all TOC 
information in the left one ('outline' in PDF) and nothing than content 
in the right one. But this is a huge change of the look-and-feel as well 
as for all technical stuff: HTML, CSS, bootstrap, Javascript, Ajax(?), ... .


--

Jürgen Purtz