[RFC PATCH] docs/system: add a gentle prompt for the complexity to come

[RFC PATCH] docs/system: add a gentle prompt for the complexity to come

[Alex Bennée]

We all know the QEMU command line can become a fiendishly complex
beast. Lets gently prepare our user for the horrors to come by
referencing where other example command lines can be found in the
manual.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/system/quickstart.rst | 8 ++++++++
 docs/system/targets.rst    | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/docs/system/quickstart.rst b/docs/system/quickstart.rst
index 3a3acab5e7..3498c5a29f 100644
--- a/docs/system/quickstart.rst
+++ b/docs/system/quickstart.rst
@@ -11,3 +11,11 @@ Download and uncompress a PC hard disk image with Linux installed (e.g.
    |qemu_system| linux.img
 
 Linux should boot and give you a prompt.
+
+Users should be aware the above example elides a lot of the complexity
+of setting up a VM with x86_64 specific defaults and an assumption the
+first non switch argument is a PC compatible disk image with a boot
+sector. For non-x86 system where we emulate a broad range of machine
+types the command lines are generally more explicit in defining the
+machine and boot behaviour. You will find more example command lines
+in the :ref:`system-targets-ref` section of the manual.
diff --git a/docs/system/targets.rst b/docs/system/targets.rst
index 560783644d..145cc64551 100644
--- a/docs/system/targets.rst
+++ b/docs/system/targets.rst
@@ -1,3 +1,5 @@
+.. _system-targets-ref:
+
 QEMU System Emulator Targets
 ============================
 
-- 
2.20.1

Re: [RFC PATCH] docs/system: add a gentle prompt for the complexity to come

[Thomas Huth]

On 01/03/2021 12.27, Alex Bennée wrote:
> We all know the QEMU command line can become a fiendishly complex
> beast. Lets gently prepare our user for the horrors to come by
> referencing where other example command lines can be found in the
> manual.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   docs/system/quickstart.rst | 8 ++++++++
>   docs/system/targets.rst    | 2 ++
>   2 files changed, 10 insertions(+)
> 
> diff --git a/docs/system/quickstart.rst b/docs/system/quickstart.rst
> index 3a3acab5e7..3498c5a29f 100644
> --- a/docs/system/quickstart.rst
> +++ b/docs/system/quickstart.rst
> @@ -11,3 +11,11 @@ Download and uncompress a PC hard disk image with Linux installed (e.g.
>      |qemu_system| linux.img
>   
>   Linux should boot and give you a prompt.
> +
> +Users should be aware the above example elides a lot of the complexity
> +of setting up a VM with x86_64 specific defaults and an assumption the

s/an assumption/assumes/ ?
(I'm not a native speaker, but to me it sounds like a verb is missing here)

> +first non switch argument is a PC compatible disk image with a boot
> +sector. For non-x86 system where we emulate a broad range of machine
> +types the command lines are generally more explicit in defining the
> +machine and boot behaviour. You will find more example command lines
> +in the :ref:`system-targets-ref` section of the manual.
> diff --git a/docs/system/targets.rst b/docs/system/targets.rst
> index 560783644d..145cc64551 100644
> --- a/docs/system/targets.rst
> +++ b/docs/system/targets.rst
> @@ -1,3 +1,5 @@
> +.. _system-targets-ref:
> +
>   QEMU System Emulator Targets
>   ============================

With the first sentence fixed:
Reviewed-by: Thomas Huth <thuth@redhat.com>

Re: [RFC PATCH] docs/system: add a gentle prompt for the complexity to come

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 548 bytes --]

On Mon, Mar 01, 2021 at 11:27:41AM +0000, Alex Bennée wrote:
> We all know the QEMU command line can become a fiendishly complex
> beast. Lets gently prepare our user for the horrors to come by
> referencing where other example command lines can be found in the
> manual.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/system/quickstart.rst | 8 ++++++++
>  docs/system/targets.rst    | 2 ++
>  2 files changed, 10 insertions(+)

Aside from Thomas' comment:

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [RFC PATCH] docs/system: add a gentle prompt for the complexity to come

[John Snow]

On 3/1/21 6:27 AM, Alex Bennée wrote:
> We all know the QEMU command line can become a fiendishly complex
> beast. Lets gently prepare our user for the horrors to come by
> referencing where other example command lines can be found in the
> manual.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   docs/system/quickstart.rst | 8 ++++++++
>   docs/system/targets.rst    | 2 ++
>   2 files changed, 10 insertions(+)
> 
> diff --git a/docs/system/quickstart.rst b/docs/system/quickstart.rst
> index 3a3acab5e7..3498c5a29f 100644
> --- a/docs/system/quickstart.rst
> +++ b/docs/system/quickstart.rst
> @@ -11,3 +11,11 @@ Download and uncompress a PC hard disk image with Linux installed (e.g.
>      |qemu_system| linux.img
>   
>   Linux should boot and give you a prompt.
> +
> +Users should be aware the above example elides a lot of the complexity
> +of setting up a VM with x86_64 specific defaults and an assumption the
"and assumes the ...", like Thomas says.

> +first non switch argument is a PC compatible disk image with a boot
> +sector. For non-x86 system where we emulate a broad range of machine

Either "For a non-x86 system ..." or "For non-x86 systems ..."

> +types the command lines are generally more explicit in defining the

You need a comma between "machine types" and "the".

> +machine and boot behaviour. You will find more example command lines
> +in the :ref:`system-targets-ref` section of the manual.

Reviewed-by: John Snow <jsnow@redhat.com>