Re: [PATCH v2 26/79] docs: powerpc: convert docs to ReST and rename to *.rst

[Andrew Donnellan]

On 22/4/19 11:27 pm, Mauro Carvalho Chehab wrote:
> Convert docs to ReST and add them to the arch-specific
> book.
>
> The conversion here was trivial, as almost every file there
> was already using an elegant format close to ReST standard.
>
> The changes were mostly to mark literal blocks and add a few
> missing section title identifiers.
>
> One note with regards to "--": on Sphinx, this can't be used
> to identify a list, as it will format it badly. This can be
> used, however, to identify a long hyphen - and "---" is an
> even longer one.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>

Acked-by: Andrew Donnellan <andrew.donnellan@xxxxxxxxxxx>  # cxl

Minor possible improvement below, otherwise compiled output looks very nice.

> diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
> similarity index 95%
> rename from Documentation/powerpc/cxl.txt
> rename to Documentation/powerpc/cxl.rst
> index c5e8d5098ed3..99e704afb09d 100644
> --- a/Documentation/powerpc/cxl.txt
> +++ b/Documentation/powerpc/cxl.rst
> @@ -1,3 +1,4 @@
> +====================================
>   Coherent Accelerator Interface (CXL)
>   ====================================
>   
> @@ -21,6 +22,8 @@ Introduction
>   Hardware overview
>   =================
>   
> +    ::
> +
>            POWER8/9             FPGA
>          +----------+        +---------+
>          |          |        |         |
> @@ -59,14 +62,16 @@ Hardware overview
>       the fault. The context to which this fault is serviced is based on
>       who owns that acceleration function.
>   
> -    POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
> -    POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
> +    - POWER8 <------> PSL Version 8 is compliant to the CAIA Version 1.0.
> +    - POWER9 <------> PSL Version 9 is compliant to the CAIA Version 2.0.
> +

This could probably be changed to "POWER8 and PSL Version 8 are 
compliant" or something like that to avoid the ASCII art arrows turning 
into dashes. Happy to pick this up myself if I ever get around to 
revising the rest of the documentation.


--
Andrew Donnellan              OzLabs, ADL Canberra
andrew.donnellan@xxxxxxxxxxx  IBM Australia Limited