From owner-svn-src-all@freebsd.org Wed Mar 1 16:30:00 2017 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id EFE96CE4E40; Wed, 1 Mar 2017 16:30:00 +0000 (UTC) (envelope-from freebsd-rwg@pdx.rh.CN85.dnsmgr.net) Received: from pdx.rh.CN85.dnsmgr.net (br1.CN84in.dnsmgr.net [69.59.192.140]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id C3A68ECA; Wed, 1 Mar 2017 16:30:00 +0000 (UTC) (envelope-from freebsd-rwg@pdx.rh.CN85.dnsmgr.net) Received: from pdx.rh.CN85.dnsmgr.net (localhost [127.0.0.1]) by pdx.rh.CN85.dnsmgr.net (8.13.3/8.13.3) with ESMTP id v21GTwKX057153; Wed, 1 Mar 2017 08:29:58 -0800 (PST) (envelope-from freebsd-rwg@pdx.rh.CN85.dnsmgr.net) Received: (from freebsd-rwg@localhost) by pdx.rh.CN85.dnsmgr.net (8.13.3/8.13.3/Submit) id v21GTwdA057152; Wed, 1 Mar 2017 08:29:58 -0800 (PST) (envelope-from freebsd-rwg) From: "Rodney W. Grimes" Message-Id: <201703011629.v21GTwdA057152@pdx.rh.CN85.dnsmgr.net> Subject: Re: svn commit: r314473 - head In-Reply-To: To: Warner Losh Date: Wed, 1 Mar 2017 08:29:57 -0800 (PST) CC: "svn-src-head@freebsd.org" , "svn-src-all@freebsd.org" , src-committers , Warner Losh X-Mailer: ELM [version 2.4ME+ PL121h (25)] MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 01 Mar 2017 16:30:01 -0000 > On Wed, Mar 1, 2017 at 9:04 AM, Rodney W. Grimes > wrote: > >> On Tue, Feb 28, 2017 at 10:45 PM, Rodney W. Grimes > >> wrote: > >> >> Author: imp > >> >> Date: Wed Mar 1 05:05:05 2017 > >> >> New Revision: 314473 > >> >> URL: https://svnweb.freebsd.org/changeset/base/314473 > >> >> > >> >> Log: > >> >> Create README.md file for viewing on github. > >> >> > >> >> This is a lightly edited README using github's MARKDOWN. > >> >> > >> >> Submitted by: Johan > >> >> Pull Request: https://github.com/freebsd/freebsd/pull/56 > >> >> > >> >> Added: > >> >> head/README.md (contents, props changed) > >> >> > >> >> Added: head/README.md > >> >> ============================================================================== > >> >> --- /dev/null 00:00:00 1970 (empty, because file is newly added) > >> >> +++ head/README.md Wed Mar 1 05:05:05 2017 (r314473) > >> >> @@ -0,0 +1,86 @@ > >> >> +FreeBSD Source: > >> >> +--------------- > >> >> +This is the top level of the FreeBSD source directory. This file > >> >> +was last revised on: > >> >> +$FreeBSD$ > >> >> + > >> >> +For copyright information, please see the file COPYRIGHT in this > >> >> +directory (additional copyright information also exists for some > >> >> +sources in this tree - please see the specific source directories for > >> >> +more information). > >> >> + > >> >> +The Makefile in this directory supports a number of targets for > >> >> +building components (or all) of the FreeBSD source tree. See build(7) > >> >> +and http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html > >> >> +for more information, including setting make(1) variables. > >> >> + > >> >> +The `buildkernel` and `installkernel` targets build and install > >> >> +the kernel and the modules (see below). Please see the top of > >> >> +the Makefile in this directory for more information on the > >> >> +standard build targets and compile-time flags. > >> >> + > >> >> +Building a kernel is a somewhat more involved process. See build(7), config(8), > >> >> +and http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html > >> >> +for more information. > >> >> + > >> >> +Note: If you want to build and install the kernel with the > >> >> +`buildkernel` and `installkernel` targets, you might need to build > >> >> +world before. More information is available in the handbook. > >> >> + > >> >> +The kernel configuration files reside in the `sys//conf` > >> >> +sub-directory. GENERIC is the default configuration used in release builds. > >> >> +NOTES contains entries and documentation for all possible > >> >> +devices, not just those commonly used. > >> >> + > >> >> + > >> >> +Source Roadmap: > >> >> +--------------- > >> > > >> > Is there someway this can be a pointer to the usr/src part of > >> > hier(7) and have hier(7) updated to reflect current reality? > >> > > >> > Also lots and lots of trailing white space... > >> > > >> > This should be a pointer to hier(7) > >> > >> It's a verbatim copy of README converted to markdown. Maybe README > >> should be fixed and this regenerated. > > > > Yes, but then couldnt this be a pointer to readme? We have this > > documented now in 3 places that are gona just get further out > > of sync. Or at least add a note to README that says you need > > to update README.md if you touch this file. > > README changes about once every other year. Not worth the churn. And exactly what makes it a bad idea to have the same infromation stored in 2, now 3 different places. With no pointers to the duplicated data for a human to follow it almost makes it certain that things well diverge. > >> The trailing whitespace is part > >> of the conversion and not a mistake. > > > > I have learned this now and responded else where. It appears > > that there are ways to do this in markdown without using > > trailing double spaces as a syntax item. > > > >> If you want to update README and hier(7) and have README.md generated > >> from that automatically, be my guest. None of that was in the > >> submission, and the submission was useful as it was. > > > > I agree that the submission is useful, as the README.md file, > > just would like to see some polish put on it so it doesnt > > suffer the same bitrot that hier(7) has. > > I can't see what polish we could put here that would prevent that. If > heir(7) is so horrible, fix it. Looking at it now shows just a tiny > bit of rot in /usr/include and maybe /usr/share/doc. There are 21 directors in /usr/src, 20 of them documented in README, 18 of them documented in hier(7). I'll rectifiy this if and when I get my commit bit. -- Rod Grimes rgrimes@freebsd.org