Date: Fri, 2 Aug 2013 11:55:50 -0700 From: Derek Wood <ddwood@highdensity.org> To: freebsd-doc@freebsd.org, gabor@freebsd.org Subject: Re: [CALL FOR REVIEW] Upgrading to DocBook 5.0 Message-ID: <20130802185523.GA15477@yavin.local> In-Reply-To: <51FB990F.6030505@FreeBSD.org> References: <51FB990F.6030505@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
The FOP output looks real nice. A few things though: 1. It appears that the links to svn revisions do not work. The FAQ book has an example of this in the question "Does ZFS support TRIM for Solid State Drives" (pg. 51). 2. Author attributions (chapter 3 heading in the handbook, pg. 13) unnecessarily take up an extra line for the email address. 3. Text within "literal" tags are truncated to line endings via hyphenation. FAQ book question 4.4.1 has probably the worst type of example for this, where "allscreens_flags=" is transformed into "allscreen-s_flags=". It is worth noting that if you actually copy and paste the text, some pdf readers will intelligently remove the hyphen (foxit does, evince does not). 4. Boxes produced via "example" tags can get split between pages (see pg. 64, 65 in FAQ). I think "warning" and "note" boxes are not affected: pg 44/45 in FAQ have a "warning" box and and empty space on the previous page. 5. Justification is producing an unnecessary amount of hyphenation. A good example of the number of hyphenations used is on page 35, where 4 out of 7 line breaks require hyphenating the word at the break; and an example of the bad type of hyphenations is on 1.1 (page 1) of the FAQ where "enhancements" is broken into "en-hancements". I am not really sure how it is possible to tweak this (This is entirely subjective, but I believe I'd prefer a requirement of 4 or more characters preceeding the hyphen), but from a small case study (fedora's installation guide [1] and debian's new maintainers' guide [2]), they have a greater amount of text per line (debian: 116, fedora: 106, freebsd: 84), which I assume gives more leeway for the formatter to reduce hyphenation. [1] http://docs.fedoraproject.org/en-US/Fedora/18/pdf/Installation_Guide/Fedora-18-Installation_Guide-en-US.pdf [2] http://www.debian.org/doc/manuals/maint-guide/maint-guide.en.pdf
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130802185523.GA15477>