From owner-freebsd-doc@FreeBSD.ORG Fri Aug 2 18:56:14 2013 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id B2E2F349 for ; Fri, 2 Aug 2013 18:56:14 +0000 (UTC) (envelope-from ddwood@highdensity.org) Received: from mail-pd0-f179.google.com (mail-pd0-f179.google.com [209.85.192.179]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 8956D25D3 for ; Fri, 2 Aug 2013 18:56:14 +0000 (UTC) Received: by mail-pd0-f179.google.com with SMTP id v10so969457pde.24 for ; Fri, 02 Aug 2013 11:56:07 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=date:from:to:subject:message-id:mail-followup-to:references :mime-version:content-type:content-disposition:in-reply-to :user-agent:x-gm-message-state; bh=OJMq+MvXm4BgTIrY+f6HQHDF0YJXWYr5etE8uVZdDOk=; b=LB7pkY6eO8wase4yiplzQotpm+iVnLyEOT4w7M5FrQS+HdoEaEu6s3H14zmjmrgY63 9p2mJ85UVh4ZZApq2u3ClxpXXZK+I90bWk5A7ZwM3AHMIpGPMsDPnvLyWz5ipywSln8Y YVJExu9Er0cV0OBUZULJWU4YU4C39pnCrM0QM33EFQmh9EERP34Wm+LT1L8atUdp8cKY w+K6wbCp9oqciRY6PrZesPbq38S3oreqVwcysWB33Pxcymcm06ni3s8RGlN14rdyCN4s vWb28p87qAdoCjZUOPlHD/MKYuGcgRpRDyXqRthhMtMoLQ1WwoEmrQSpipeHnbOuCmKd US3Q== X-Received: by 10.68.233.134 with SMTP id tw6mr9492796pbc.9.1375469766947; Fri, 02 Aug 2013 11:56:06 -0700 (PDT) Received: from yavin.local (ip72-201-96-33.ph.ph.cox.net. [72.201.96.33]) by mx.google.com with ESMTPSA id e7sm10220810pbc.11.2013.08.02.11.56.05 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Fri, 02 Aug 2013 11:56:06 -0700 (PDT) Date: Fri, 2 Aug 2013 11:55:50 -0700 From: Derek Wood To: freebsd-doc@freebsd.org, gabor@freebsd.org Subject: Re: [CALL FOR REVIEW] Upgrading to DocBook 5.0 Message-ID: <20130802185523.GA15477@yavin.local> Mail-Followup-To: freebsd-doc@freebsd.org, gabor@freebsd.org References: <51FB990F.6030505@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <51FB990F.6030505@FreeBSD.org> User-Agent: Mutt/1.5.21 (2010-09-15) X-Gm-Message-State: ALoCoQmiq87YN4y6MavRRg/fIxX06An/gBFQJ3ivrVuod8ZYeG1qrzYjj4xV7rCLvs2M+2JfEHBm X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 02 Aug 2013 18:56:14 -0000 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