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 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 > > --- > > 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 wy 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
Re: [PATCH 1/5] docs: arm: marvell: turn the automatic links into labels
Lubomir Rintel 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 > --- > 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
[PATCH 1/5] docs: arm: marvell: turn the automatic links into labels
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 --- 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 + Kirkwood family --- Flavors: - 88F6282 a.k.a Armada 300 -- Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf +- Product Brief : `armada_310.pdf`_ - 88F6283 a.k.a Armada 310 -- Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf +- Product Brief : `armada_310.pdf`_ - 88F6190 -- Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf -- Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf -- Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf +- Product Brief : `88F6190-003_WEB.pdf`_ +- Hardware Spec : `HW_88F619x_OpenSource.pdf`_ +- Functional Spec: `FS_88F6180_9x_6281_OpenSource.pdf`_ - 88F6192 -- Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf -- Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf -- Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf +- Product Brief : `88F6192-003_ver1.pdf`_ +- Hardware Spec : `HW_88F619x_OpenSource.pdf`_ +- Functional Spec: `FS_88F6180_9x_6281_OpenSource.pdf`_ - 88F6182 - 88F6180 -- Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf -- Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf -- Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf +- Product Brief : `88F6180-003_ver1.pdf`_ +- Hardware Spec : `HW_88F6180_OpenSource.pdf`_ +- Functional Spec: `FS_88F6180_9x_6281_OpenSource.pdf`_ - 88F6281 -- Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf -- Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf -- Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf +- Product Brief : `88F6281-004_ver1.pdf`_ +- Hardware Spec : `HW_88F6281_OpenSource.pdf`_ +- Functional Spec: `FS_88F6180_9x_6281_OpenSource.pdf`_ Homepage: http://www.marvell.com/embedded-processors/kirkwood/ Core: @@ -72,20 +77,35 @@ Kirkwood
