README: revise the top level readme texts
PATCH 1/2 README: revise the top level readme texts
This improves the top level README situation a little: Instead of starting with historical information like "This file was moved to..." we add a short introductory description and point the reader to the documention in a direct way, avoiding phrases like "Please notice that there are...".
--- README | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-)
README +18 -8
@@ -1,17 +1,27 @@ Linux kernel ============ -This file was moved to Documentation/admin-guide/README.rst +Linux is a computer operating system kernel first released by Linus Torvalds +in September of 1991. It runs on a wide variety of hardware architectures and +has all expected features like multitasking, memory management, multistack +networking and so on. -Please notice that there are several guides for kernel developers and users. -These guides can be rendered in a number of formats, like HTML and PDF. +Device drivers are an integral part too, supporting the use of countless +devices. Documentation/process/howto.rst describes how to include a new one. -In order to build the documentation, use ``make htmldocs`` or -``make pdfdocs``. +Documentation +------------- -There are various text files in the Documentation/ subdirectory, -several of them using the Restructured Text markup notation. -See Documentation/00-INDEX for a list of what is contained in each file. +Linux is documented in the Documentation/ subdirectory. Several of the text +files use the Restructured Text markup notation. + +Documentation/admin-guide/README.rst may be what you are looking for and +Documentation/00-INDEX has a list of what is contained in each file. + +The included guides for kernel developers and users can be rendered in a number +of formats, like HTML and PDF. + +In order to build the documentation, use ``make htmldocs`` or ``make pdfdocs``. Please read the Documentation/process/changes.rst file, as it contains the requirements for building and running the kernel, and information about
Signature · 1 line
2.11.0
PATCH 2/2 Documentation: admin-guide: remove redundant first paragraph of README.rst
"These are the release notes for Linux version 4." is what the header above says. There's no real need to say that again.
"Read them carefully," Why would we advise people to read one file carefully but other file not?
"they tell you what this is all about, explain how to install the kernel, and what to do if something goes wrong." That's just the chapters below. With rendered docs, the reader doesn't even have to scroll down to have this sentense's information :)
Therefore let's remove the first paragraph, including the "What is Linux?" subheader, and start with telling what Linux is. This won't come as a surprise to the reader.
--- Documentation/admin-guide/README.rst | 7 ------- 1 file changed, 7 deletions(-)
Documentation/admin-guide/README.rst +0 -7
@@ -1,13 +1,6 @@ Linux kernel release 4.x <http://kernel.org/> ============================================= -These are the release notes for Linux version 4. Read them carefully, -as they tell you what this is all about, explain how to install the -kernel, and what to do if something goes wrong. - -What is Linux? --------------- - Linux is a clone of the operating system Unix, written from scratch by Linus Torvalds with assistance from a loosely-knit team of hackers across the Net. It aims towards POSIX and Single UNIX Specification compliance.
Signature · 1 line
2.11.0