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

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: <87tuqzwa0j.fsf@meer.lwn.net>
Date:   Fri, 29 Jan 2021 17:20:28 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Lubomir Rintel <lkundrak@...sk>
Cc:     Maen Suleiman <maen@...vell.com>, Lior Amsalem <alior@...vell.com>,
        Thomas Petazzoni <thomas.petazzoni@...e-electrons.com>,
        Andrew Lunn <andrew@...n.ch>, Nicolas Pitre <nico@...xnic.net>,
        Eric Miao <eric.y.miao@...il.com>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, Lubomir Rintel <lkundrak@...sk>
Subject: Re: [PATCH 1/5] docs: arm: marvell: turn the automatic links into
 labels

Lubomir Rintel <lkundrak@...sk> 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 <lkundrak@...sk>
> ---
>  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