Re: [Qemu-devel] [PATCH v2 1/4] docs: convert README, CODING_STYLE and HACKING to RST syntax

[Alex Bennée]

Daniel P. Berrangé <address@hidden> writes:

> Signed-off-by: Daniel P. Berrangé <address@hidden>

Reviewed-by: Alex Bennée <address@hidden>

> ---
>  CODING_STYLE => CODING_STYLE.rst | 121 +++++++++++++++++++-----------
>  HACKING => HACKING.rst           | 123 +++++++++++++++++++++----------
>  README => README.rst             |  47 +++++++-----
>  3 files changed, 190 insertions(+), 101 deletions(-)
>  rename CODING_STYLE => CODING_STYLE.rst (72%)
>  rename HACKING => HACKING.rst (79%)
>  rename README => README.rst (84%)
>
> diff --git a/CODING_STYLE b/CODING_STYLE.rst
> similarity index 72%
> rename from CODING_STYLE
> rename to CODING_STYLE.rst
> index cb8edcbb36..713357cb80 100644
> --- a/CODING_STYLE
> +++ b/CODING_STYLE.rst
> @@ -1,10 +1,14 @@
> +=================
>  QEMU Coding Style
>  =================
>
> +.. contents:: Table of Contents
> +
>  Please use the script checkpatch.pl in the scripts directory to check
>  patches before submitting.
>
> -1. Whitespace
> +Whitespace
> +==========
>
>  Of course, the most important aspect in any coding style is whitespace.
>  Crusty old coders who have trouble spotting the glasses on their noses
> @@ -16,26 +20,27 @@ QEMU indents are four spaces.  Tabs are never used, 
> except in Makefiles
>  where they have been irreversibly coded into the syntax.
>  Spaces of course are superior to tabs because:
>
> - - You have just one way to specify whitespace, not two.  Ambiguity breeds
> -   mistakes.
> - - The confusion surrounding 'use tabs to indent, spaces to justify' is gone.
> - - Tab indents push your code to the right, making your screen seriously
> -   unbalanced.
> - - Tabs will be rendered incorrectly on editors who are misconfigured not
> -   to use tab stops of eight positions.
> - - Tabs are rendered badly in patches, causing off-by-one errors in almost
> -   every line.
> - - It is the QEMU coding style.
> +* You have just one way to specify whitespace, not two.  Ambiguity breeds
> +  mistakes.
> +* The confusion surrounding 'use tabs to indent, spaces to justify' is gone.
> +* Tab indents push your code to the right, making your screen seriously
> +  unbalanced.
> +* Tabs will be rendered incorrectly on editors who are misconfigured not
> +  to use tab stops of eight positions.
> +* Tabs are rendered badly in patches, causing off-by-one errors in almost
> +  every line.
> +* It is the QEMU coding style.
>
>  Do not leave whitespace dangling off the ends of lines.
>
> -1.1 Multiline Indent
> +Multiline Indent
> +----------------
>
>  There are several places where indent is necessary:
>
> - - if/else
> - - while/for
> - - function definition & call
> +* if/else
> +* while/for
> +* function definition & call
>
>  When breaking up a long line to fit within line width, we need a proper 
> indent
>  for the following lines.
> @@ -45,6 +50,8 @@ opening parenthesis of the first.
>
>  For example:
>
> +.. code-block:: c
> +
>      if (a == 1 &&
>          b == 2) {
>
> @@ -53,12 +60,13 @@ For example:
>
>  In case of function, there are several variants:
>
> -    * 4 spaces indent from the beginning
> -    * align the secondary lines just after the opening parenthesis of the
> -      first
> +* 4 spaces indent from the beginning
> +* align the secondary lines just after the opening parenthesis of the first
>
>  For example:
>
> +.. code-block:: c
> +
>      do_something(x, y,
>          z);
>
> @@ -68,7 +76,8 @@ For example:
>      do_something(x, do_another(y,
>                                 z));
>
> -2. Line width
> +Line width
> +==========
>
>  Lines should be 80 characters; try not to make them longer.
>
> @@ -77,16 +86,18 @@ that use long function or symbol names.  Even in that 
> case, do not make
>  lines much longer than 80 characters.
>
>  Rationale:
> - - Some people like to tile their 24" screens with a 6x4 matrix of 80x24
> -   xterms and use vi in all of them.  The best way to punish them is to
> -   let them keep doing it.
> - - Code and especially patches is much more readable if limited to a sane
> -   line length.  Eighty is traditional.
> - - The four-space indentation makes the most common excuse ("But look
> -   at all that white space on the left!") moot.
> - - It is the QEMU coding style.
>
> -3. Naming
> +* Some people like to tile their 24" screens with a 6x4 matrix of 80x24
> +  xterms and use vi in all of them.  The best way to punish them is to
> +  let them keep doing it.
> +* Code and especially patches is much more readable if limited to a sane
> +  line length.  Eighty is traditional.
> +* The four-space indentation makes the most common excuse ("But look
> +  at all that white space on the left!") moot.
> +* It is the QEMU coding style.
> +
> +Naming
> +======
>
>  Variables are lower_case_with_underscores; easy to type and read.  Structured
>  type names are in CamelCase; harder to type but standing out.  Enum type
> @@ -95,10 +106,11 @@ names are lower_case_with_underscores_ending_with_a_t, 
> like the POSIX
>  uint64_t and family.  Note that this last convention contradicts POSIX
>  and is therefore likely to be changed.
>
> -When wrapping standard library functions, use the prefix qemu_ to alert
> +When wrapping standard library functions, use the prefix ``qemu_`` to alert
>  readers that they are seeing a wrapped version; otherwise avoid this prefix.
>
> -4. Block structure
> +Block structure
> +===============
>
>  Every indented statement is braced; even if the block contains just one
>  statement.  The opening brace is on the line that contains the control
> @@ -106,6 +118,8 @@ flow statement that introduces the new block; the closing 
> brace is on the
>  same line as the else keyword, or on a line by itself if there is no else
>  keyword.  Example:
>
> +.. code-block:: c
> +
>      if (a == 5) {
>          printf("a was 5.\n");
>      } else if (a == 6) {
> @@ -121,6 +135,8 @@ statement.
>  An exception is the opening brace for a function; for reasons of tradition
>  and clarity it comes on a line by itself:
>
> +.. code-block:: c
> +
>      void a_function(void)
>      {
>          do_something();
> @@ -130,7 +146,8 @@ Rationale: a consistent (except for functions...) bracing 
> style reduces
>  ambiguity and avoids needless churn when lines are added or removed.
>  Furthermore, it is the QEMU coding style.
>
> -5. Declarations
> +Declarations
> +============
>
>  Mixed declarations (interleaving statements and declarations within
>  blocks) are generally not allowed; declarations should be at the beginning
> @@ -142,11 +159,14 @@ be placed at the top of the block even if there are 
> statements above.
>  On the other hand, however, it's often best to move that #ifdef/#ifndef
>  block to a separate function altogether.
>
> -6. Conditional statements
> +Conditional statements
> +======================
>
>  When comparing a variable for (in)equality with a constant, list the
>  constant on the right, as in:
>
> +.. code-block:: c
> +
>      if (a == 1) {
>          /* Reads like: "If a equals 1" */
>          do_something();
> @@ -156,19 +176,24 @@ Rationale: Yoda conditions (as in 'if (1 == a)') are 
> awkward to read.
>  Besides, good compilers already warn users when '==' is mis-typed as '=',
>  even when the constant is on the right.
>
> -7. Comment style
> +Comment style
> +=============
>
> -We use traditional C-style /* */ comments and avoid // comments.
> +We use traditional C-style /``*`` ``*``/ comments and avoid // comments.
>
>  Rationale: The // form is valid in C99, so this is purely a matter of
>  consistency of style. The checkpatch script will warn you about this.
>
>  Multiline comment blocks should have a row of stars on the left,
> -and the initial /* and terminating */ both on their own lines:
> +and the initial /``*`` and terminating ``*``/ both on their own lines:
> +
> +.. code-block:: c
> +
>      /*
>       * like
>       * this
>       */
> +
>  This is the same format required by the Linux kernel coding style.
>
>  (Some of the existing comments in the codebase use the GNU Coding
> @@ -180,24 +205,32 @@ comment anyway.)
>  Rationale: Consistency, and ease of visually picking out a multiline
>  comment from the surrounding code.
>
> -8. trace-events style
> +trace-events style
> +==================
>
> -8.1 0x prefix
> +0x prefix
> +---------
>
>  In trace-events files, use a '0x' prefix to specify hex numbers, as in:
>
> -some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64
> +.. code-block::
> +
> +    some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64
>
>  An exception is made for groups of numbers that are hexadecimal by
>  convention and separated by the symbols '.', '/', ':', or ' ' (such as
>  PCI bus id):
>
> -another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x"
> +.. code-block::
> +
> +    another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x"
>
>  However, you can use '0x' for such groups if you want. Anyway, be sure that
>  it is obvious that numbers are in hex, ex.:
>
> -data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x 
> %02x"
> +.. code-block::
> +
> +    data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x 
> %02x"
>
>  Rationale: hex numbers are hard to read in logs when there is no 0x prefix,
>  especially when (occasionally) the representation doesn't contain any letters
> @@ -205,12 +238,14 @@ and especially in one line with other decimal numbers. 
> Number groups are allowed
>  to not use '0x' because for some things notations like %x.%x.%x are used not
>  only in Qemu. Also dumping raw data bytes with '0x' is less readable.
>
> -8.2 '#' printf flag
> +'#' printf flag
> +---------------
>
>  Do not use printf flag '#', like '%#x'.
>
>  Rationale: there are two ways to add a '0x' prefix to printed number: 
> '0x%...'
>  and '%#...'. For consistency the only one way should be used. Arguments for
>  '0x%' are:
> - - it is more popular
> - - '%#' omits the 0x for the value 0 which makes output inconsistent
> +
> +* it is more popular
> +* '%#' omits the 0x for the value 0 which makes output inconsistent
> diff --git a/HACKING b/HACKING.rst
> similarity index 79%
> rename from HACKING
> rename to HACKING.rst
> index 097d482603..668fc420c3 100644
> --- a/HACKING
> +++ b/HACKING.rst
> @@ -1,19 +1,32 @@
> -1. Preprocessor
> +============
> +QEMU Hacking
> +============
>
> -1.1. Variadic macros
> +.. contents:: Table of Contents
> +
> +Preprocessor
> +============
> +
> +Variadic macros
> +---------------
>
>  For variadic macros, stick with this C99-like syntax:
>
> -#define DPRINTF(fmt, ...)                                       \
> -    do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0)
> +.. code-block:: c
>
> -1.2. Include directives
> +    #define DPRINTF(fmt, ...)                                       \
> +        do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0)
> +
> +Include directives
> +------------------
>
>  Order include directives as follows:
>
> -#include "qemu/osdep.h"  /* Always first... */
> -#include <...>           /* then system headers... */
> -#include "..."           /* and finally QEMU headers. */
> +.. code-block:: c
> +
> +    #include "qemu/osdep.h"  /* Always first... */
> +    #include <...>           /* then system headers... */
> +    #include "..."           /* and finally QEMU headers. */
>
>  The "qemu/osdep.h" header contains preprocessor macros that affect the 
> behavior
>  of core system headers like <stdint.h>.  It must be the first include so that
> @@ -23,12 +36,14 @@ that QEMU depends on.
>  Do not include "qemu/osdep.h" from header files since the .c file will have
>  already included it.
>
> -2. C types
> +C types
> +=======
>
>  It should be common sense to use the right type, but we have collected
>  a few useful guidelines here.
>
> -2.1. Scalars
> +Scalars
> +-------
>
>  If you're using "int" or "long", odds are good that there's a better type.
>  If a variable is counting something, it should be declared with an
> @@ -68,8 +83,8 @@ it may be 32 or 64 bits depending on which target is being 
> built. It should
>  therefore be used only in target-specific code, and in some
>  performance-critical built-per-target core code such as the TLB code.
>  There is also a signed version, target_long.
> -abi_ulong is for the *-user targets, and represents a type the size of
> -'void *' in that target's ABI. (This may not be the same as the size of a
> +abi_ulong is for the ``*``-user targets, and represents a type the size of
> +'void ``*``' in that target's ABI. (This may not be the same as the size of a
>  full CPU virtual address in the case of target ABIs which use 32 bit pointers
>  on 64 bit CPUs, like sparc32plus.) Definitions of structures that must match
>  the target's ABI must use this type for anything that on the target is 
> defined
> @@ -89,7 +104,8 @@ Finally, while using descriptive types is important, be 
> careful not to
>  go overboard.  If whatever you're doing causes warnings, or requires
>  casts, then reconsider or ask for help.
>
> -2.2. Pointers
> +Pointers
> +--------
>
>  Ensure that all of your pointers are "const-correct".
>  Unless a pointer is used to modify the pointed-to storage,
> @@ -99,7 +115,8 @@ importantly, if we're diligent about this, when you see a 
> non-const
>  pointer, you're guaranteed that it is used to modify the storage
>  it points to, or it is aliased to another pointer that is.
>
> -2.3. Typedefs
> +Typedefs
> +--------
>
>  Typedefs are used to eliminate the redundant 'struct' keyword, since type
>  names have a different style than other identifiers ("CamelCase" versus
> @@ -114,11 +131,14 @@ definitions instead of typedefs in headers and function 
> prototypes; this
>  avoids problems with duplicated typedefs and reduces the need to include
>  headers from other headers.
>
> -2.4. Reserved namespaces in C and POSIX
> +Reserved namespaces in C and POSIX
> +----------------------------------
> +
>  Underscore capital, double underscore, and underscore 't' suffixes should be
>  avoided.
>
> -3. Low level memory management
> +Low level memory management
> +===========================
>
>  Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign
>  APIs is not allowed in the QEMU codebase. Instead of these routines,
> @@ -130,36 +150,51 @@ Please note that g_malloc will exit on allocation 
> failure, so there
>  is no need to test for failure (as you would have to with malloc).
>  Calling g_malloc with a zero size is valid and will return NULL.
>
> -Prefer g_new(T, n) instead of g_malloc(sizeof(T) * n) for the following
> +Prefer g_new(T, n) instead of g_malloc(sizeof(T) ``*`` n) for the following
>  reasons:
>
> -  a. It catches multiplication overflowing size_t;
> -  b. It returns T * instead of void *, letting compiler catch more type
> -     errors.
> +* It catches multiplication overflowing size_t;
> +* It returns T ``*`` instead of void ``*``, letting compiler catch more type 
> errors.
> +
> +Declarations like
> +
> +.. code-block:: c
> +
> +    T *v = g_malloc(sizeof(*v))
>
> -Declarations like T *v = g_malloc(sizeof(*v)) are acceptable, though.
> +are acceptable, though.
>
>  Memory allocated by qemu_memalign or qemu_blockalign must be freed with
>  qemu_vfree, since breaking this will cause problems on Win32.
>
> -4. String manipulation
> +String manipulation
> +===================
>
>  Do not use the strncpy function.  As mentioned in the man page, it does *not*
>  guarantee a NULL-terminated buffer, which makes it extremely dangerous to 
> use.
>  It also zeros trailing destination bytes out to the specified length.  
> Instead,
>  use this similar function when possible, but note its different signature:
> -void pstrcpy(char *dest, int dest_buf_size, const char *src)
> +
> +.. code-block:: c
> +
> +    void pstrcpy(char *dest, int dest_buf_size, const char *src)
>
>  Don't use strcat because it can't check for buffer overflows, but:
> -char *pstrcat(char *buf, int buf_size, const char *s)
> +
> +.. code-block:: c
> +
> +    char *pstrcat(char *buf, int buf_size, const char *s)
>
>  The same limitation exists with sprintf and vsprintf, so use snprintf and
>  vsnprintf.
>
>  QEMU provides other useful string functions:
> -int strstart(const char *str, const char *val, const char **ptr)
> -int stristart(const char *str, const char *val, const char **ptr)
> -int qemu_strnlen(const char *s, int max_len)
> +
> +.. code-block:: c
> +
> +    int strstart(const char *str, const char *val, const char **ptr)
> +    int stristart(const char *str, const char *val, const char **ptr)
> +    int qemu_strnlen(const char *s, int max_len)
>
>  There are also replacement character processing macros for isxyz and toxyz,
>  so instead of e.g. isalnum you should use qemu_isalnum.
> @@ -167,7 +202,8 @@ so instead of e.g. isalnum you should use qemu_isalnum.
>  Because of the memory management rules, you must use g_strdup/g_strndup
>  instead of plain strdup/strndup.
>
> -5. Printf-style functions
> +Printf-style functions
> +======================
>
>  Whenever you add a new printf-style function, i.e., one with a format
>  string argument and following "..." in its prototype, be sure to use
> @@ -177,12 +213,14 @@ This makes it so gcc's -Wformat and -Wformat-security 
> options can do
>  their jobs and cross-check format strings with the number and types
>  of arguments.
>
> -6. C standard, implementation defined and undefined behaviors
> +C standard, implementation defined and undefined behaviors
> +==========================================================
>
>  C code in QEMU should be written to the C99 language specification. A copy
>  of the final version of the C99 standard with corrigenda TC1, TC2, and TC3
>  included, formatted as a draft, can be downloaded from:
> - http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf
> +
> +    `<http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf>`_
>
>  The C language specification defines regions of undefined behavior and
>  implementation defined behavior (to give compiler authors enough leeway to
> @@ -193,17 +231,20 @@ argument...) However there are a few areas where we 
> allow ourselves to
>  assume certain behaviors because in practice all the platforms we care about
>  behave in the same way and writing strictly conformant code would be
>  painful. These are:
> - * you may assume that integers are 2s complement representation
> - * you may assume that right shift of a signed integer duplicates
> -   the sign bit (ie it is an arithmetic shift, not a logical shift)
> +
> +* you may assume that integers are 2s complement representation
> +* you may assume that right shift of a signed integer duplicates
> +  the sign bit (ie it is an arithmetic shift, not a logical shift)
>
>  In addition, QEMU assumes that the compiler does not use the latitude
>  given in C99 and C11 to treat aspects of signed '<<' as undefined, as
>  documented in the GNU Compiler Collection manual starting at version 4.0.
>
> -7. Error handling and reporting
> +Error handling and reporting
> +============================
>
> -7.1 Reporting errors to the human user
> +Reporting errors to the human user
> +----------------------------------
>
>  Do not use printf(), fprintf() or monitor_printf().  Instead, use
>  error_report() or error_vreport() from error-report.h.  This ensures the
> @@ -214,10 +255,11 @@ Use error_printf() & friends to print additional 
> information.
>
>  error_report() prints the current location.  In certain common cases
>  like command line parsing, the current location is tracked
> -automatically.  To manipulate it manually, use the loc_*() from
> +automatically.  To manipulate it manually, use the loc_``*``() from
>  error-report.h.
>
> -7.2 Propagating errors
> +Propagating errors
> +------------------
>
>  An error can't always be reported to the user right where it's detected,
>  but often needs to be propagated up the call chain to a place that can
> @@ -233,16 +275,17 @@ error, non-negative / -errno, non-null / null, or Error 
> objects.
>  Example: when a function returns a non-null pointer on success, and it
>  can fail only in one way (as far as the caller is concerned), returning
>  null on failure is just fine, and certainly simpler and a lot easier on
> -the eyes than propagating an Error object through an Error ** parameter.
> +the eyes than propagating an Error object through an Error ``*````*`` 
> parameter.
>
>  Example: when a function's callers need to report details on failure
> -only the function really knows, use Error **, and set suitable errors.
> +only the function really knows, use Error ``*````*``, and set suitable 
> errors.
>
>  Do not report an error to the user when you're also returning an error
>  for somebody else to handle.  Leave the reporting to the place that
>  consumes the error returned.
>
> -7.3 Handling errors
> +Handling errors
> +---------------
>
>  Calling exit() is fine when handling configuration errors during
>  startup.  It's problematic during normal operation.  In particular,
> diff --git a/README b/README.rst
> similarity index 84%
> rename from README
> rename to README.rst
> index 441c33eb2f..9ff2877416 100644
> --- a/README
> +++ b/README.rst
> @@ -1,5 +1,6 @@
> -         QEMU README
> -         ===========
> +===========
> +QEMU README
> +===========
>
>  QEMU is a generic and open source machine & userspace emulator and
>  virtualizer.
> @@ -37,6 +38,9 @@ QEMU is multi-platform software intended to be buildable on 
> all modern
>  Linux platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety
>  of other UNIX targets. The simple steps to build QEMU are:
>
> +
> +.. code-block:: shell
> +
>    mkdir build
>    cd build
>    ../configure
> @@ -44,9 +48,9 @@ of other UNIX targets. The simple steps to build QEMU are:
>
>  Additional information can also be found online via the QEMU website:
>
> -  https://qemu.org/Hosts/Linux
> -  https://qemu.org/Hosts/Mac
> -  https://qemu.org/Hosts/W32
> +* `<https://qemu.org/Hosts/Linux>`_
> +* `<https://qemu.org/Hosts/Mac>`_
> +* `<https://qemu.org/Hosts/W32>`_
>
>
>  Submitting patches
> @@ -54,24 +58,29 @@ Submitting patches
>
>  The QEMU source code is maintained under the GIT version control system.
>
> +.. code-block:: shell
> +
>     git clone https://git.qemu.org/git/qemu.git
>
>  When submitting patches, one common approach is to use 'git
>  format-patch' and/or 'git send-email' to format & send the mail to the
>  address@hidden mailing list. All patches submitted must contain
>  a 'Signed-off-by' line from the author. Patches should follow the
> -guidelines set out in the HACKING and CODING_STYLE files.
> +guidelines set out in the HACKING.rst and CODING_STYLE.rst files.
>
>  Additional information on submitting patches can be found online via
>  the QEMU website
>
> -  https://qemu.org/Contribute/SubmitAPatch
> -  https://qemu.org/Contribute/TrivialPatches
> +* `<https://qemu.org/Contribute/SubmitAPatch>`_
> +* `<https://qemu.org/Contribute/TrivialPatches>`_
>
>  The QEMU website is also maintained under source control.
>
> +.. code-block:: shell
> +
>    git clone https://git.qemu.org/git/qemu-web.git
> -  https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/
> +
> +* `<https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/>`_
>
>  A 'git-publish' utility was created to make above process less
>  cumbersome, and is highly recommended for making regular contributions,
> @@ -82,10 +91,12 @@ manually for once.
>
>  For installation instructions, please go to
>
> -  https://github.com/stefanha/git-publish
> +*  `<https://github.com/stefanha/git-publish>`_
>
>  The workflow with 'git-publish' is:
>
> +.. code-block:: shell
> +
>    $ git checkout master -b my-feature
>    $ # work on new commits, add your 'Signed-off-by' lines to each
>    $ git publish
> @@ -95,6 +106,8 @@ back to it in the future.
>
>  Sending v2:
>
> +.. code-block:: shell
> +
>    $ git checkout my-feature # same topic branch
>    $ # making changes to the commits (using 'git rebase', for example)
>    $ git publish
> @@ -109,7 +122,7 @@ The QEMU project uses Launchpad as its primary upstream 
> bug tracker. Bugs
>  found when running code built from QEMU git or upstream released sources
>  should be reported via:
>
> -  https://bugs.launchpad.net/qemu/
> +* `<https://bugs.launchpad.net/qemu/>`_
>
>  If using QEMU via an operating system vendor pre-built binary package, it
>  is preferable to report bugs to the vendor's own bug tracker first. If
> @@ -118,7 +131,7 @@ reported via launchpad.
>
>  For additional information on bug reporting consult:
>
> -  https://qemu.org/Contribute/ReportABug
> +* `<https://qemu.org/Contribute/ReportABug>`_
>
>
>  Contact
> @@ -127,13 +140,11 @@ Contact
>  The QEMU community can be contacted in a number of ways, with the two
>  main methods being email and IRC
>
> - - address@hidden
> -   https://lists.nongnu.org/mailman/listinfo/qemu-devel
> - - #qemu on irc.oftc.net
> +* `<mailto:address@hidden>`_
> +* `<https://lists.nongnu.org/mailman/listinfo/qemu-devel>`_
> +* #qemu on irc.oftc.net
>
>  Information on additional methods of contacting the community can be
>  found online via the QEMU website:
>
> -  https://qemu.org/Contribute/StartHere
> -
> --- End
> +* `<https://qemu.org/Contribute/StartHere>`_


--
Alex Bennée