Re: [HACKERS] Improve setup for documentation building with FOP
On Tue, 2013-10-15 at 23:11 -0400, Peter Eisentraut wrote: Updated patch attached. Committed with some further tweaks. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] Improve setup for documentation building with FOP
On 9/16/13 12:19 PM, Alvaro Herrera wrote: The FOP-based build works fine for me. I gave the output a look. I like that text formatted with fixed-width font wraps at the right margin, instead of continuing beyond it; there are some strange artifacts about it (such as addition of hyphens in some places, say in the middle of a configure option); but I think it's nicer than the output of the other toolchain nevertheless. This willingness to break in the middle of pre formatted elements looks weird in some places; for example table 17.2 SSL Server File Usage; old output puts the option name on first line, file path on second line; new output puts option name on top, file name is split in half. The wrapping and hyphenation is a complex issue. I think we agree that it's generally better to do suboptimal wrapping than to have the content run off the page. Everything between that is, AFAICT, a matter of fine-tuning various parameters and attributes. In the US size PDF, look at page 386; below the gmake install-world there's the bottom-of-page horizontal line, but the paragraph continues below that. Bug? Yeah, no idea how that can happen. Section 17.8 Encryption Options is formatted differently; previous method used indentation for the paragraph after each item, new one uses a table. I like the old method better. This is notoriously bad in the superuser_reserved_connections entry in 18.3.1. Connection Settings, and others. Also, the synopsis in PQconnectStartParams entry in 31.1 Database Connection Control Functions looks a lot worse. This manifests in many places, and while it's an improvement in a minority of them, I think it's a net loss overall. Yep. Fixed by setting an option that turns it back to the old way. I like that the new output has horizontal lines at top and bottom of the text area of the page. In the old method, the page heading (above that line) contains the chapter number and title, while in FOP it only has title (no number). I find that number useful. Also, limiting the space for the title and wrapping if the title is too long seems pointless; see example of this in chapter High Availability, Load Balancing and Replication, where even the word Bal-ancing has been hyphenated. Made a note that fix that later. Formatting of note, tip and such seems a lot better in FOP. For warning, the old method used a surrounding box; the new one just has a Warning title and indented paragraph, just like for note et al. Doesn't look like a problem to me. It'd be nice to have pretty icons for these areas. Could be fine-tuned later. sidebar renders as grey-background box in FOP, white-background in old tool. Not sure about this; it looks like the only place with grey background in the whole manual. We only have one sidebar in the entire SGML source. Hmm, maybe it's there to keep the printers honest. ;-) It would be easy to change this if desired. Example 19.1 Example pg_hba.conf Entries is completely broken (no page break); renders normally in old method. There are other cases of this, including libpq sample programs and ECPG. I can't reproduce that. What version of FOP are you using? I have 1.1. url renders differently: it used to produce a footnote. FOP instead puts the link text inline. Not really sure about this. Changed back to footnote. The table 25.1 High Availability, Load Balancing, and Replication Feature Matrix contains a lot of [bull], which look odd. Presumably an image of a bull head would be better? This is an artifact of the SGML to XML conversion. Already fixed in separate commit. Tables 27-13 and 27-14 are misformatted in both implementations. Surely we can do better than overlaying the contents of cells ... This also needs to be addressed by adjusting the wrapping and hyphenation rules. Or we could manually tweak it by adding some zero width space characters. It would need to be checked how that would affect other output formats, however. The START_REPLICATION stuff in the Frontend/Backend Protocol chapter is completely broken. Maybe wrong markup? Also in StartupMessage. Same issue as with Encryption Options etc. above. Seems author resulted in nothing in the old toolchain, but now it does print the name of the author. There are only two authors mentioned, in NLS and GEQO, though. In the GEQO case it's a bit funny because the author is now mentioned twice. I propose to remove those two author sections. In the GEQO chapter, the information is already present, and in the NLS case, well, I don't care. Speaking of GEQO: the links in its 53.4 Further Reading section don't look well in the FOP. And the bibliography looks completely different. I see. That is customizable, but maybe not the way it looks in the old output. We might need to reassess the entire bibliography at some point anyway. It's not really well-maintained. Oh, the index at the end is not output. Fixed in separate
Re: [HACKERS] Improve setup for documentation building with FOP
Peter Eisentraut wrote: In order to modernize our documentation tool chain, I have made a few tweaks to allow using FOP to build the PDF documentation. I'd like to get some testing on different operating systems and versions thereof in order to learn whether this solution is robust and easily accessible by users and developers, and also whether the resulting documents are correct and free of major rendering problems. I'll add it to the commitfest for that. Reviewers should ideally just have to install the fop package that is hopefully supplied by their operating systems and then run the make targets mentioned in the patch. I'm aware of a few potential pitfalls, but I'd rather not mention them yet in order to get unbiased reports. The FOP-based build works fine for me. I gave the output a look. I like that text formatted with fixed-width font wraps at the right margin, instead of continuing beyond it; there are some strange artifacts about it (such as addition of hyphens in some places, say in the middle of a configure option); but I think it's nicer than the output of the other toolchain nevertheless. This willingness to break in the middle of pre formatted elements looks weird in some places; for example table 17.2 SSL Server File Usage; old output puts the option name on first line, file path on second line; new output puts option name on top, file name is split in half. In the US size PDF, look at page 386; below the gmake install-world there's the bottom-of-page horizontal line, but the paragraph continues below that. Bug? Section 17.8 Encryption Options is formatted differently; previous method used indentation for the paragraph after each item, new one uses a table. I like the old method better. This is notoriously bad in the superuser_reserved_connections entry in 18.3.1. Connection Settings, and others. Also, the synopsis in PQconnectStartParams entry in 31.1 Database Connection Control Functions looks a lot worse. This manifests in many places, and while it's an improvement in a minority of them, I think it's a net loss overall. I like that the new output has horizontal lines at top and bottom of the text area of the page. In the old method, the page heading (above that line) contains the chapter number and title, while in FOP it only has title (no number). I find that number useful. Also, limiting the space for the title and wrapping if the title is too long seems pointless; see example of this in chapter High Availability, Load Balancing and Replication, where even the word Bal-ancing has been hyphenated. Formatting of note, tip and such seems a lot better in FOP. For warning, the old method used a surrounding box; the new one just has a Warning title and indented paragraph, just like for note et al. Doesn't look like a problem to me. It'd be nice to have pretty icons for these areas. Formatting of ref links is nicer: for instance, you get something like which can make those operations much faster (see Section 14.4.7, “Disable WAL Archival and Streaming Replica- tion”). instead of which can make those operations much faster (see Section 14.4.7). Not sure if there are cases in which this can be a problem. [aside: I really wish we didn't paste verbatim psql output in SGML docs ] sidebar renders as grey-background box in FOP, white-background in old tool. Not sure about this; it looks like the only place with grey background in the whole manual. We only have one sidebar in the entire SGML source. Example 19.1 Example pg_hba.conf Entries is completely broken (no page break); renders normally in old method. There are other cases of this, including libpq sample programs and ECPG. url renders differently: it used to produce a footnote. FOP instead puts the link text inline. Not really sure about this. The table 25.1 High Availability, Load Balancing, and Replication Feature Matrix contains a lot of [bull], which look odd. Presumably an image of a bull head would be better? Tables 27-13 and 27-14 are misformatted in both implementations. Surely we can do better than overlaying the contents of cells ... The START_REPLICATION stuff in the Frontend/Backend Protocol chapter is completely broken. Maybe wrong markup? Also in StartupMessage. Seems author resulted in nothing in the old toolchain, but now it does print the name of the author. There are only two authors mentioned, in NLS and GEQO, though. In the GEQO case it's a bit funny because the author is now mentioned twice. Speaking of GEQO: the links in its 53.4 Further Reading section don't look well in the FOP. And the bibliography looks completely different. Oh, the index at the end is not output. -- Álvaro Herrerahttp://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, 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
