[PATCH] doc: devicetree: Lets avoid short reference link names
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@bp.renesas.com Signed-off-by: Sumit Garg sumit.garg@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-rebasi... -.. _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-rebasi... +.. _DT schema project page: https://github.com/devicetree-org/dt-schema/tree/main
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@bp.renesas.com Signed-off-by: Sumit Garg sumit.garg@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-rebasi... -.. _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-rebasi... +.. _DT schema project page: https://github.com/devicetree-org/dt-schema/tree/main
Reviewed-by: Paul Barker paul.barker.ct@bp.renesas.com
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@bp.renesas.com Signed-off-by: Sumit Garg sumit.garg@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-rebasi... -.. _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-rebasi... +.. _DT schema project page: https://github.com/devicetree-org/dt-schema/tree/main
Reviewed-by: Paul Barker paul.barker.ct@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.
participants (2)
-
Paul Barker -
Sumit Garg