switching documentation build to XSLT
Some work has been going on recently to be able to update our
documentation build tool chain. After discussion on pgsql-docs, the
people involved agree that it is time to move forward.
We are now proposing that we change the way the HTML documentation is
built from jade/openjade+docbook-dsssl to xsltproc+docbook-xsl.
If you can build the man pages now (make man, also included in make
world), then you don't need any new tools. The new HTML build will be
using the same tools. Otherwise, follow the documentation to set up
those tools and make that work.
The actual patch to make this change is attached. For the build
process, nothing changes, e.g., 'make' or 'make html' will still have
the same purposes.
For the time being, you will still be able to build the documentation
the old way with 'make oldhtml', but this is mainly so that we can
compare the output and work out any formatting kinks. Before this
patch, you can also build the documentation the new way using 'make
xslthtml', but that will go away.
I will submit a separate patch to the web site team to update the CSS
style sheets for the web site to match the new output.
There are more steps to be done after this, to move over the other
output formats (PDF), adjust the configure script, the documentation,
work out any remaining formatting problems, etc., so now is a good time
to get this rolling so that we have a good chance of reaching a steady
state before the end of the development cycle.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
0001-Build-HTML-documentation-using-XSLT-stylesheets-by-d.patchtext/x-patch; name=0001-Build-HTML-documentation-using-XSLT-stylesheets-by-d.patchDownload+23-36
On 11/10/16 5:49 AM, Peter Eisentraut wrote:
We are now proposing that we change the way the HTML documentation is
built from jade/openjade+docbook-dsssl to xsltproc+docbook-xsl.
The actual patch to make this change is attached. For the build
process, nothing changes, e.g., 'make' or 'make html' will still have
the same purposes.
This has been committed.
If you find any changes in the output that bother you, let pgsql-docs know.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
If you find any changes in the output that bother you, let pgsql-docs know.
I notice that whereas <xref> used to generate text like
Section 4.1.2.7
now you get
Section 4.1.2.7, “Constants of Other Types”
This is probably an improvement in most places, but there may be some
places where the text now reads awkwardly and we need to rephrase or
re-punctuate to make it non-confusing. Keep an eye out for that ...
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
If you find any changes in the output that bother you, let pgsql-docs know.
The table of contents for Appendix F has gotten more verbose, in a way
that doesn't seem like an improvement; compare
https://www.postgresql.org/docs/9.6/static/contrib.html
https://www.postgresql.org/docs/devel/static/contrib.html
On the other hand, the table of contents disappeared entirely in
dblink, which is definitely not an improvement:
https://www.postgresql.org/docs/9.6/static/dblink.html
https://www.postgresql.org/docs/devel/static/dblink.html
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Hello,
Attached patches fix the issues.
I wrote about these differences before -- see issues 12 and 20 in
http://oc.postgrespro.ru/index.php/s/Gj2PGZ9IHUbDC5t/download
(See
/messages/by-id/4ffd72d6-8ab6-37c6-d7d5-dfed8967c0fc@gmail.com)
If you find that some other differences are not improvements too, I can
prepare corresponding patches.
Best regards,
Alexander
21.11.2016 22:36, Tom Lane пишет:
Show quoted text
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
If you find any changes in the output that bother you, let pgsql-docs know.
The table of contents for Appendix F has gotten more verbose, in a way
that doesn't seem like an improvement; comparehttps://www.postgresql.org/docs/9.6/static/contrib.html
https://www.postgresql.org/docs/devel/static/contrib.htmlOn the other hand, the table of contents disappeared entirely in
dblink, which is definitely not an improvement:https://www.postgresql.org/docs/9.6/static/dblink.html
https://www.postgresql.org/docs/devel/static/dblink.htmlregards, tom lane
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
If you find any changes in the output that bother you, let pgsql-docs know.
I noticed that <remark> sections now appear in the output, which they did
not use to: compare
https://www.postgresql.org/docs/9.6/static/dml.html
https://www.postgresql.org/docs/devel/static/dml.html
If we don't want to consider that bad, somebody needs to run around and
change all such sections into comments, because we have not historically
expected them to get printed.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
I wrote:
I notice that whereas <xref> used to generate text like
Section 4.1.2.7
now you get
Section 4.1.2.7, “Constants of Other Types”
I also find that for some reason, the results are not formatted
consistently. Section cross-references are printed with quotes
as shown above, but chapter cross-references have no quotes and
instead the chapter title is italicized. See for example the
various cross-references for GiST about halfway down this page:
https://www.postgresql.org/docs/devel/static/indexes-types.html
TBH though, the more examples of this I look at, the less convinced
I am that it's an improvement at all. We have an awful lot of
parenthetical cross-references like "(see Section 1.2.3)", which
previously were easy to ignore while reading, but with long section
titles attached to them they quite interrupt the sentence flow.
I can kind of see the point when printing on dead trees, but in
any format where the reference is a hyperlink, I think I'd vote
for dropping the title and going back to the old output.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
If you find any changes in the output that bother you, let pgsql-docs know.
So, while I'm complaining, have a look at the Note near the bottom
of
https://www.postgresql.org/docs/devel/static/datatype-numeric.html
and compare to its appearance in
https://www.postgresql.org/docs/9.6/static/datatype-numeric.html
Now, to my taste, our past markup of note/tip/etc is already
overemphasizing them. They're inset with narrower margins and
put on a different-color background, which makes it hard to avoid
the impression that they're the most important thing on the page
and you should barely bother to read anything else. In almost no
case is that actually warranted; certainly not for stuff with
markup less than <warning>. (Personally I'd argue that <note> means
it's *less* important than the surrounding text, not more so.)
But putting them in bold type with a separated heading is just over
the top. What are we going to do for text that's actually critical
... make it bright red and blinking?
Just to add confusion, the note on the previous page is set
in normal type:
https://www.postgresql.org/docs/devel/static/datatype.html
which I don't understand since the sgml source is about the same.
But this one is still different from the way it was rendered by
the old toolchain.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Hello,
The attached patch fixes this.
Best regards,
Alexander
22.11.2016 21:47, Tom Lane пишет:
Show quoted text
I wrote:
I notice that whereas <xref> used to generate text like
Section 4.1.2.7
now you get
Section 4.1.2.7, “Constants of Other Types”I also find that for some reason, the results are not formatted
consistently. Section cross-references are printed with quotes
as shown above, but chapter cross-references have no quotes and
instead the chapter title is italicized. See for example the
various cross-references for GiST about halfway down this page:https://www.postgresql.org/docs/devel/static/indexes-types.html
TBH though, the more examples of this I look at, the less convinced
I am that it's an improvement at all. We have an awful lot of
parenthetical cross-references like "(see Section 1.2.3)", which
previously were easy to ignore while reading, but with long section
titles attached to them they quite interrupt the sentence flow.I can kind of see the point when printing on dead trees, but in
any format where the reference is a hyperlink, I think I'd vote
for dropping the title and going back to the old output.regards, tom lane
Attachments:
xref-without-number-and-title.patchtext/x-patch; name=xref-without-number-and-title.patchDownload+1-0
Hello,
It seems that there is some post-processing after `make html` that adds
class = "c1" or class = "c2" to html.
(It makes <div class="note c2"> or <div class="note c1">)
And docs.css on the website contains the rule:
.emphasis,
.c2 {
font-weight: bold;
}
So I think, the issue is related to publishing on the website.
Best regards,
Alexander
23.11.2016 05:39, Tom Lane writes:
Just to add confusion, the note on the previous page is set
in normal type:https://www.postgresql.org/docs/devel/static/datatype.html
which I don't understand since the sgml source is about the same.
But this one is still different from the way it was rendered by
the old toolchain.regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs