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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <5114a435-030a-8c2c-885d-f5e053f9749b@au1.ibm.com>
Date:   Wed, 24 Apr 2019 11:15:45 +1000
From:   Andrew Donnellan <andrew.donnellan@....ibm.com>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        Bjorn Helgaas <bhelgaas@...gle.com>,
        Benjamin Herrenschmidt <benh@...nel.crashing.org>,
        Paul Mackerras <paulus@...ba.org>,
        Michael Ellerman <mpe@...erman.id.au>,
        Frederic Barrat <fbarrat@...ux.ibm.com>,
        "Manoj N. Kumar" <manoj@...ux.ibm.com>,
        "Matthew R. Ochs" <mrochs@...ux.ibm.com>,
        Uma Krishnan <ukrishn@...ux.ibm.com>,
        Russell Currey <ruscur@...sell.cc>,
        Sam Bobroff <sbobroff@...ux.ibm.com>,
        "Oliver O'Halloran" <oohall@...il.com>,
        Qiang Zhao <qiang.zhao@....com>, Li Yang <leoyang.li@....com>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Jiri Slaby <jslaby@...e.com>, linux-pci@...r.kernel.org,
        linuxppc-dev@...ts.ozlabs.org, linux-scsi@...r.kernel.org,
        linux-arm-kernel@...ts.infradead.org
Subject: Re: [PATCH v2 26/79] docs: powerpc: convert docs to ReST and rename
 to *.rst

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@...nel.org>

Acked-by: Andrew Donnellan <andrew.donnellan@....ibm.com>  # 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@....ibm.com  IBM Australia Limited