[PATCH] docs: arm64: Fix indentation and doc formatting

[PATCH] docs: arm64: Fix indentation and doc formatting

[Adam Zerella]

Sphinx generates the following warnings for the arm64 doc
pages:

Documentation/arm64/memory.rst:158: WARNING: Unexpected indentation.
Documentation/arm64/memory.rst:162: WARNING: Unexpected indentation.

These indentations warnings can be resolved by utilising code
hightlighting instead.

Signed-off-by: Adam Zerella <adam.zerella@gmail.com>
---
 Documentation/arm64/memory.rst | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
index b040909e45f8..f7db6a3898c5 100644
--- a/Documentation/arm64/memory.rst
+++ b/Documentation/arm64/memory.rst
@@ -154,11 +154,16 @@ return virtual addresses to userspace from a 48-bit range.
 
 Software can "opt-in" to receiving VAs from a 52-bit space by
 specifying an mmap hint parameter that is larger than 48-bit.
-For example:
-    maybe_high_address = mmap(~0UL, size, prot, flags,...);
+
+.. code-block:: c
+
+   maybe_high_address = mmap(~0UL, size, prot, flags,...);
 
 It is also possible to build a debug kernel that returns addresses
 from a 52-bit space by enabling the following kernel config options:
+
+.. code-block:: sh
+
    CONFIG_EXPERT=y && CONFIG_ARM64_FORCE_52BIT=y
 
 Note that this option is only intended for debugging applications
-- 
2.20.1

Re: [PATCH] docs: arm64: Fix indentation and doc formatting

[Will Deacon]

On Sat, Sep 28, 2019 at 10:58:19PM +1000, Adam Zerella wrote:
> Sphinx generates the following warnings for the arm64 doc
> pages:
> 
> Documentation/arm64/memory.rst:158: WARNING: Unexpected indentation.
> Documentation/arm64/memory.rst:162: WARNING: Unexpected indentation.
> 
> These indentations warnings can be resolved by utilising code
> hightlighting instead.
> 
> Signed-off-by: Adam Zerella <adam.zerella@gmail.com>
> ---
>  Documentation/arm64/memory.rst | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
> index b040909e45f8..f7db6a3898c5 100644
> --- a/Documentation/arm64/memory.rst
> +++ b/Documentation/arm64/memory.rst
> @@ -154,11 +154,16 @@ return virtual addresses to userspace from a 48-bit range.
>  
>  Software can "opt-in" to receiving VAs from a 52-bit space by
>  specifying an mmap hint parameter that is larger than 48-bit.
> -For example:
> -    maybe_high_address = mmap(~0UL, size, prot, flags,...);
> +
> +.. code-block:: c
> +
> +   maybe_high_address = mmap(~0UL, size, prot, flags,...);

Why did you drop the "For example:" prefix?

Will

Re: [PATCH] docs: arm64: Fix indentation and doc formatting

[Adam Zerella]

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

On Mon, Sep 30, 2019 at 01:28:23PM +0100, Will Deacon wrote:
> On Sat, Sep 28, 2019 at 10:58:19PM +1000, Adam Zerella wrote:
> > Sphinx generates the following warnings for the arm64 doc
> > pages:
> > 
> > Documentation/arm64/memory.rst:158: WARNING: Unexpected indentation.
> > Documentation/arm64/memory.rst:162: WARNING: Unexpected indentation.
> > 
> > These indentations warnings can be resolved by utilising code
> > hightlighting instead.
> > 
> > Signed-off-by: Adam Zerella <adam.zerella@gmail.com>
> > ---
> >  Documentation/arm64/memory.rst | 9 +++++++--
> >  1 file changed, 7 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
> > index b040909e45f8..f7db6a3898c5 100644
> > --- a/Documentation/arm64/memory.rst
> > +++ b/Documentation/arm64/memory.rst
> > @@ -154,11 +154,16 @@ return virtual addresses to userspace from a 48-bit range.
> >  
> >  Software can "opt-in" to receiving VAs from a 52-bit space by
> >  specifying an mmap hint parameter that is larger than 48-bit.
> > -For example:
> > -    maybe_high_address = mmap(~0UL, size, prot, flags,...);
> > +
> > +.. code-block:: c
> > +
> > +   maybe_high_address = mmap(~0UL, size, prot, flags,...);
> 
> Why did you drop the "For example:" prefix?
> 

No reason, I initially thought it would be a bit cleaner but since it is
a code example not an _actual_ snippet it makes more sense to keep it.

I've attached a v2 patch.

> Will

[-- Attachment #2: PATCH-v2-docs-arm64-Fix-indentation-and-doc-formatti.patch --]
[-- Type: text/plain, Size: 1367 bytes --]

Sphinx generates the following warnings for the arm64 doc
pages:

Documentation/arm64/memory.rst:158: WARNING: Unexpected indentation.
Documentation/arm64/memory.rst:162: WARNING: Unexpected indentation.

These indentations warnings can be resolved by utilising code
hightlighting instead.

Signed-off-by: Adam Zerella <adam.zerella@gmail.com>
---

v2: Adding back the 'For example' text before the code example.
---
 Documentation/arm64/memory.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
index b040909e45f8..02e02175e6f5 100644
--- a/Documentation/arm64/memory.rst
+++ b/Documentation/arm64/memory.rst
@@ -154,11 +154,18 @@ return virtual addresses to userspace from a 48-bit range.
 
 Software can "opt-in" to receiving VAs from a 52-bit space by
 specifying an mmap hint parameter that is larger than 48-bit.
+
 For example:
-    maybe_high_address = mmap(~0UL, size, prot, flags,...);
+
+.. code-block:: c
+
+   maybe_high_address = mmap(~0UL, size, prot, flags,...);
 
 It is also possible to build a debug kernel that returns addresses
 from a 52-bit space by enabling the following kernel config options:
+
+.. code-block:: sh
+
    CONFIG_EXPERT=y && CONFIG_ARM64_FORCE_52BIT=y
 
 Note that this option is only intended for debugging applications
-- 
2.21.0