[PATCH] doc: devicetree: Lets avoid short reference link names

[Paul Barker]

On 02/03/2024 07:39, Paul Barker wrote:
> On 01/03/2024 13:24, Sumit Garg wrote:
>> Short reference link names like "dtspec", "dtrepo", "dttweaks" etc.
>> interrupt the flow of the document text. Lets avoid them and instead
>> expand in place for better readability.
>>
>> Suggested-by: Paul Barker <paul.barker.ct at bp.renesas.com>
>> Signed-off-by: Sumit Garg <sumit.garg at linaro.org>
>> ---
>>  doc/develop/devicetree/control.rst | 24 ++++++++++++------------
>>  1 file changed, 12 insertions(+), 12 deletions(-)
>>
>> diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst
>> index c94d84192b71..4cc1457d4ea8 100644
>> --- a/doc/develop/devicetree/control.rst
>> +++ b/doc/develop/devicetree/control.rst
>> @@ -36,10 +36,10 @@ What is a Flattened Devicetree?
>>  -------------------------------
>>  
>>  An fdt can be specified in source format as a text file. To read about
>> -the fdt syntax, take a look at the specification (dtspec_).
>> +the fdt syntax, take a look at `the devicetree specification`_.
>>  
>> -There is also a mailing list (dtlist_) for the compiler and associated
>> -tools.
>> +There is also a `devicetree compiler mailing list`_ for the compiler and
>> +associated tools.
>>  
>>  In case you are wondering, OF stands for Open Firmware. This follows the
>>  convention used in Linux.
>> @@ -89,7 +89,7 @@ Failing that, you could write one from scratch yourself!
>>  Resyncing with devicetree-rebasing
>>  ----------------------------------
>>  
>> -The devicetee-rebasing repository (dtrepo_) maintains a fork cum mirror copy of
>> +The `devicetree-rebasing repository`_ maintains a fork cum mirror copy of
>>  devicetree files along with the bindings synced at every Linux kernel major
>>  release or intermediate release candidates. The U-Boot maintainers regularly
>>  sync the `dts/upstream/` subtree from the devicetree-rebasing repo whenever
>> @@ -118,7 +118,7 @@ as `arch/<arch>/dts/<name>.dts`. To select that add `# CONFIG_OF_UPSTREAM is not
>>  set` and set `DEFAULT_DEVICE_TREE=<name>` when prompted by Kconfig.
>>  
>>  This should include your CPU or SoC's devicetree file. On top of that any U-Boot
>> -specific tweaks (see: dttweaks_) can be made for your board.
>> +specific tweaks (see: :ref:`dttweaks`) can be made for your board.
>>  
>>  If `OF_EMBED` is selected by Kconfig, then it will be picked up and built into
>>  the U-Boot image (including u-boot.bin). This is suitable for debugging
>> @@ -243,7 +243,7 @@ Dependencies
>>  
>>  The DT schema project must be installed in order to validate the DT schema
>>  binding documents and validate DTS files using the DT schema. For installation
>> -instructions, refer to the DT schema project page (dtschema_).
>> +instructions, refer to the `DT schema project page`_.
>>  
>>  Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
>>  installed. Ensure they are in your PATH (~/.local/bin by default).
>> @@ -333,10 +333,10 @@ used it before Linux (e.g. snow). The two projects developed in parallel
>>  and there are still some differences in the bindings for certain boards.
>>  While there has been discussion of having a separate repository for devicetree
>>  files, in practice the Linux kernel Git repository has become the place where
>> -these are stored, with U-Boot taking copies via devicetree-rebasing repo
>> -(see: dtrepo_) and adding tweaks with u-boot.dtsi files.
>> +these are stored, with U-Boot taking copies via
>> +`devicetree-rebasing repository`_ and adding tweaks with u-boot.dtsi files.
>>  
>> -.. _dtspec: https://www.devicetree.org/specifications/
>> -.. _dtlist: https://www.spinics.net/lists/devicetree-compiler/
>> -.. _dtrepo: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git
>> -.. _dtschema: https://github.com/devicetree-org/dt-schema/tree/main
>> +.. _the devicetree specification: https://www.devicetree.org/specifications/
>> +.. _devicetree compiler mailing list: https://www.spinics.net/lists/devicetree-compiler/
>> +.. _devicetree-rebasing repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git
>> +.. _DT schema project page: https://github.com/devicetree-org/dt-schema/tree/main
> 
> Reviewed-by: Paul Barker <paul.barker.ct at bp.renesas.com>
> 

There are no comments from anyone else, but this hasn't hit the next
branch yet so I'm sending a gentle ping.

-- 
Paul Barker
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_0x27F4B3459F002257.asc
Type: application/pgp-keys
Size: 3520 bytes
Desc: OpenPGP public key
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20240318/450f68e7/attachment.key>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_signature.asc
Type: application/pgp-signature
Size: 236 bytes
Desc: OpenPGP digital signature
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20240318/450f68e7/attachment.sig>