Em Mon, 24 Oct 2016 17:17:27 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> Am 24.10.2016 um 13:00 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>
> > Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
> > on an user's manual book.
> >
> > As we'll be numbering the user's manual, remove the manual
> > numbering from SecurityBugs.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
> > ---
> > README => Documentation/admin-guide/README.rst | 1 -
> > .../{bad_memory.txt => admin-guide/bad-memory.rst} | 1 -
> > .../basic-profiling.rst} | 1 -
> > .../binfmt-misc.rst} | 0
> > .../braille-console.rst} | 0
> > .../{BUG-HUNTING => admin-guide/bug-hunting.rst} | 0
> > Documentation/admin-guide/conf.py | 10 +++++++
> > .../{devices.txt => admin-guide/devices.rst} | 1 -
> > .../dynamic-debug-howto.rst} | 0
> > Documentation/admin-guide/index.rst | 34 ++++++++++++++++++++++
> > Documentation/{init.txt => admin-guide/init.rst} | 0
> > .../{initrd.txt => admin-guide/initrd.rst} | 0
> > Documentation/{java.txt => admin-guide/java.rst} | 1 -
> > .../kernel-parameters.rst} | 0
> > Documentation/{md.txt => admin-guide/md.rst} | 0
> > Documentation/{mono.txt => admin-guide/mono.rst} | 0
> > .../oops-tracing.rst} | 0
> > .../{parport.txt => admin-guide/parport.rst} | 0
> > .../{ramoops.txt => admin-guide/ramoops.rst} | 0
> > .../admin-guide/reporting-bugs.rst | 0
> > .../security-bugs.rst} | 12 ++++----
> > .../serial-console.rst} | 0
> > .../sysfs-rules.rst} | 0
> > Documentation/{sysrq.txt => admin-guide/sysrq.rst} | 0
> > .../{unicode.txt => admin-guide/unicode.rst} | 0
> > .../vga-softcursor.rst} | 0
> > Documentation/conf.py | 2 ++
> > Documentation/index.rst | 1 +
> > 28 files changed, 53 insertions(+), 11 deletions(-)
> > rename README => Documentation/admin-guide/README.rst (99%)
> diff --git a/README b/Documentation/admin-guide/README.rst
> similarity index 99%
> rename from README
> rename to Documentation/admin-guide/README.rst
> index 3335b3b2973a..05aad8543340 100644
> --- a/README
> +++ b/Documentation/admin-guide/README.rst
> @@ -408,4 +408,3 @@ If something goes wrong
>
> gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly)
> disregards the starting offset for which the kernel is compiled.
> -
>
> I don't know if we should really move root's README into the
> Documentation folder.
Why not? IMHO, what's there is clearly provides the most relevant
content for an User's/Admin Guide:
https://mchehab.fedorapeople.org/kernel_docs/admin-guide/README.html
E.g:
1.1. What is Linux?
1.2. On what hardware does it run?
1.3. Documentation
1.4. Installing the kernel source
1.5. Software requirements
1.6. Build directory for the kernel
1.7. Configuring the kernel
1.8. Compiling the kernel
1.9. If something goes wrong
So, what I'm proposing on this series is to move its contents to the
User's manual, and replace it to a much shorter version that points
to the new location of the file, and points to the Kernel's documentation
(see patch 36/37)[1].
[1] I opted to put the new content on a separate file because the
git diff -M will show better the renames.
> Do we really need this README in the sphinx-build?
I believe so. IMHO, the fundamental documentation for an Admin's Guide
is there.
> It might be better to route the reader from root's README to
> a file which describes, how to build the full documentation,
> what might be related to our discussion in [1].
We could add a pointer to it too and to other documents. The point is:
IMHO, the current content of README is actually an User's guide. It
should be replaced by something that will point to the right places
(like Documentation/00-INDEX, but, pointing instead to the documentation
books, and not to each individual file at documentation).
> Hope there comes the day we can link sphinx content on kernel.org.
> I opened a ticket (CC to linux-doc [2]) but get not yet any reply.
>
> [1] https://www.mail-archive.com/linux-doc@xxxxxxxxxxxxxxx/msg07091.html
> [2] https://www.mail-archive.com/linux-doc@xxxxxxxxxxxxxxx/msg06961.html
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
