LinuxLists.cc - [PATCH 0/5] docs: arm: Improvements to Marvell SoC documentation

2021-01-29 18:43:15

Subject: [PATCH 0/5] docs: arm: Improvements to Marvell SoC documentation

Hi,

please consider applying the patches chained to this message.

The objective is to deal with the a large amount of dead links to
material that often comes handy in marvel.rst; and improve some details
along the way.

Thank you
Lubo

2021-01-29 18:43:50

by Lubomir Rintel

[permalink] [raw]

Subject: [PATCH 1/5] docs: arm: marvell: turn the automatic links into labels

2021-01-29 18:45:43

by Lubomir Rintel

[permalink] [raw]

Subject: [PATCH 4/5] docs: arm: marvell: clarify some unimportant Armada 6x0 details

MMP2 is used in XO-1.75 and MMP3 is now supported in mainline.

Signed-off-by: Lubomir Rintel <[email protected]>
---
Documentation/arm/marvel.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/arm/marvel.rst b/Documentation/arm/marvel.rst
index 0c291d1091f1d..43f2fe407796e 100644
--- a/Documentation/arm/marvel.rst
+++ b/Documentation/arm/marvel.rst
@@ -392,11 +392,11 @@ MMP/MMP2/MMP3 family (communication processor)
- Product Brief : `Marvell_PXA910_Platform-001_PB_final.pdf`_
- Application processor with Communication processor
- Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk)
- - PXA688, a.k.a. MMP2, a.k.a Armada 610
+ - PXA688, a.k.a. MMP2, a.k.a Armada 610 (OLPC XO-1.75)
- Product Brief : `armada610_pb.pdf`_
- Application processor only
- Core: ARMv7 compatible Sheeva PJ4 88sv581x core
- - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream)
+ - PXA2128, a.k.a. MMP3, a.k.a Armada 620 (OLPC XO-4)
- Product Brief : `Marvell-ARMADA-PXA2128-SoC-PB.pdf`_
- Application processor only
- Core: Dual-core ARMv7 compatible Sheeva PJ4C core
--
2.29.2

2021-01-30 00:24:47

by Jonathan Corbet

[permalink] [raw]

Subject: Re: [PATCH 1/5] docs: arm: marvell: turn the automatic links into labels

Lubomir Rintel <[email protected]> writes:

> Lines ending with obscenely long URLs at the end don't look good.
>
> Even if these links are not that long at this point, they will be when
> replaced with an archive link in a subsequent patch -- let's prepare for
> that.
>
> Signed-off-by: Lubomir Rintel <[email protected]>
> ---
> Documentation/arm/marvel.rst | 209 ++++++++++++++++++++++++-----------
> 1 file changed, 143 insertions(+), 66 deletions(-)
>
> diff --git a/Documentation/arm/marvel.rst b/Documentation/arm/marvel.rst
> index 16ab2eb085b86..716551f9b60a1 100644
> --- a/Documentation/arm/marvel.rst
> +++ b/Documentation/arm/marvel.rst
> @@ -18,12 +18,12 @@ Orion family
> - 88F5181L
> - 88F5182
>
> - - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf
> - - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf
> - - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf
> + - Datasheet: `MV88F5182-datasheet.pdf`_
> + - Programmer's User Guide: `MV88F5182-opensource-manual.pdf`_
> + - User Manual: `MV88F5182-usermanual.pdf`_
> - 88F5281
>
> - - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf
> + - Datasheet: `marvel_88f5281_data_sheet.pdf`_
> - 88F6183
> Core:
> Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible
> @@ -32,37 +32,42 @@ Orion family
> Linux kernel plat directory:
> arch/arm/plat-orion
>
> +.. _MV88F5182-datasheet.pdf: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf
> +.. _MV88F5182-opensource-manual.pdf: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf
> +.. _MV88F5182-usermanual.pdf: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf
> +.. _marvel_88f5281_data_sheet.pdf: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf

So I see what you're trying to do, but this has the effect of prettying
up the processed docs at the expense of making the plain-text version
harder to read. Somebody who wants to find one of these datasheets from
the plain-text version has to skip further down in the file, hoping that
they pick out the right one among a set of long, similar URLs.
Honestly, I think we may be better off leaving them as they are.
Failing that, the right thing to do is to keep the lines defining the
URL labels right next to where they are referenced.

See what I'm getting at?

Thanks,

jon

2021-01-30 14:09:52

by Lubomir Rintel

[permalink] [raw]

Subject: Re: [PATCH 1/5] docs: arm: marvell: turn the automatic links into labels

On Fri, Jan 29, 2021 at 05:20:28PM -0700, Jonathan Corbet wrote:
> Lubomir Rintel <[email protected]> writes:
>
> > Lines ending with obscenely long URLs at the end don't look good.
> >
> > Even if these links are not that long at this point, they will be when
> > replaced with an archive link in a subsequent patch -- let's prepare for
> > that.
> >
> > Signed-off-by: Lubomir Rintel <[email protected]>
> > ---
> > Documentation/arm/marvel.rst | 209 ++++++++++++++++++++++++-----------
> > 1 file changed, 143 insertions(+), 66 deletions(-)
> >
> > diff --git a/Documentation/arm/marvel.rst b/Documentation/arm/marvel.rst
> > index 16ab2eb085b86..716551f9b60a1 100644
> > --- a/Documentation/arm/marvel.rst
> > +++ b/Documentation/arm/marvel.rst
> > @@ -18,12 +18,12 @@ Orion family
> > - 88F5181L
> > - 88F5182
> >
> > - - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf
> > - - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf
> > - - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf
> > + - Datasheet: `MV88F5182-datasheet.pdf`_
> > + - Programmer's User Guide: `MV88F5182-opensource-manual.pdf`_
> > + - User Manual: `MV88F5182-usermanual.pdf`_
> > - 88F5281
> >
> > - - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf
> > + - Datasheet: `marvel_88f5281_data_sheet.pdf`_
> > - 88F6183
> > Core:
> > Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible
> > @@ -32,37 +32,42 @@ Orion family
> > Linux kernel plat directory:
> > arch/arm/plat-orion
> >
> > +.. _MV88F5182-datasheet.pdf: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf
> > +.. _MV88F5182-opensource-manual.pdf: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf
> > +.. _MV88F5182-usermanual.pdf: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf
> > +.. _marvel_88f5281_data_sheet.pdf: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf
>
> So I see what you're trying to do, but this has the effect of prettying
> up the processed docs at the expense of making the plain-text version
> harder to read. Somebody who wants to find one of these datasheets from
> the plain-text version has to skip further down in the file, hoping that
> they pick out the right one among a set of long, similar URLs.
> Honestly, I think we may be better off leaving them as they are.
> Failing that, the right thing to do is to keep the lines defining the
> URL labels right next to where they are referenced.
>
> See what I'm getting at?

Yes. I've been considering the same, but concluded it's a still a better
idea to move the full URLs below because

1.) at this point the links are broken anyway and the basename is the
only valuable part of the URL when looking for an actual document;
and the basename stays in place
2.) the archive.org links that replace them in another patch are waaaay too
long even for very large displays

However, even though I think this is perhaps marginally better, either
way works for me. Thus, unless you change your mind about it, I'll follow
up with a v2 that drops this patch and replaces the links in place.

Thank you
Lubo

>
> Thanks,
>
> jon