svn commit: r314473 - head

[Warner Losh]

On Wed, Mar 1, 2017 at 9:04 AM, Rodney W. Grimes
<freebsd-rwg at pdx.rh.cn85.dnsmgr.net> wrote:
>> On Tue, Feb 28, 2017 at 10:45 PM, Rodney W. Grimes
>> <freebsd-rwg at pdx.rh.cn85.dnsmgr.net> 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 <johan2422 at gmail.com>
>> >>   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/<arch>/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.

>> 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.

Warner