From owner-freebsd-doc@FreeBSD.ORG Sat Feb 8 16:47:12 2014 Return-Path: Delivered-To: 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 ESMTPS id A21FDF46; Sat, 8 Feb 2014 16:47:12 +0000 (UTC) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 51A731B22; Sat, 8 Feb 2014 16:47:11 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id s18GlAAd036307; Sat, 8 Feb 2014 09:47:10 -0700 (MST) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id s18GlAX8036304; Sat, 8 Feb 2014 09:47:10 -0700 (MST) (envelope-from wblock@wonkity.com) Date: Sat, 8 Feb 2014 09:47:09 -0700 (MST) From: Warren Block To: Tom Rhodes Subject: Re: [WIP]: Splitting up the porters handbook In-Reply-To: <20140208105726.3e1b52d8.trhodes@FreeBSD.org> Message-ID: References: <20140208105726.3e1b52d8.trhodes@FreeBSD.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Sat, 08 Feb 2014 09:47:10 -0700 (MST) Cc: port-mngr@FreeBSD.org, doc@FreeBSD.org, doceng@FreeBSD.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 08 Feb 2014 16:47:12 -0000 On Sat, 8 Feb 2014, Tom Rhodes wrote: > Hi, > > So - today I spent a few moments (and a few for loops) splitting > up the porters-handbook into several sections. Here is the WIP > patch: > > http://people.freebsd.org/~trhodes/NEW-PH.diff > > Please note it DOES NOT BUILD just yet. Before I actually go > through the trouble of finishing this, is there going to be > a lot of push back? Can I continue and commit (a version that > builds of course) and then the team can work together to polish > off the rough edges with me or should I just not bother? Thanks, > > I'm going to not work on this anymore today while I wait for > feedback - if it's generally positive, I'll try to finish it > up tonight/tomorrow morning and start the commits. Cheers, Can't speak for others, but I agree. It's something that has needed to be done for a while now. Based on experience from the Handbook, I suggest fixing the titles in the sections that will become chapters, then using those actual titles for the chapter directory names. With the Handbook, the names don't match and it is difficult to find sections for editing. So: The title of "Making a New Port Yourself" becomes "Making a New Port" (or "Creating a New Port"), and then the chapter directory is making-a-new-port, or creating-a-new-port. The length of these is not as critical as making them consistent with the title. "Testing Your Port" becomes "Testing the Port". "Upgrading an Individual Port" becomes "Upgrading a Port". "Ports Security" becomes just "Security". The chapter entries in SRCS should be in the order they appear in the book.