| Message ID | 20240301132454.3492762-1-sumit.garg@linaro.org |
|---|---|
| State | Accepted |
| Commit | 7046bfe79e0ac34636fe8ada5f356a947f07740a |
| Headers | show |
| Series | doc: devicetree: Lets avoid short reference link names | expand |
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-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@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-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@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.
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
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(-)