Em Mon, 2 Mar 2020 15:18:51 -0600
Frank Rowand <frowand.list@xxxxxxxxx> escreveu:
> On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> > - Add a SPDX header;
> > - Adjust document title;
> > - Use footnoote markups;
> > - Some whitespace fixes and new line breaks;
> > - Mark literal blocks as such;
> > - Add it to devicetree/index.rst.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> > ---
> > Documentation/devicetree/index.rst | 1 +
> > Documentation/devicetree/of_unittest.txt | 2 +-
> > .../{usage-model.txt => usage-model.rst} | 35 +++++++++++--------
> > include/linux/mfd/core.h | 2 +-
> > 4 files changed, 23 insertions(+), 17 deletions(-)
> > rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)
> >
> > diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> > index a11efe26f205..7a6aad7d384a 100644
> > --- a/Documentation/devicetree/index.rst
> > +++ b/Documentation/devicetree/index.rst
> > @@ -7,4 +7,5 @@ Open Firmware and Device Tree
> > .. toctree::
> > :maxdepth: 1
> >
> > + usage-model
> > writing-schema
> > diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt
> > index 3e4e7d48ae93..9fdd2de9b770 100644
> > --- a/Documentation/devicetree/of_unittest.txt
> > +++ b/Documentation/devicetree/of_unittest.txt
> > @@ -11,7 +11,7 @@ architecture.
> >
> > It is recommended to read the following documents before moving ahead.
> >
> > -[1] Documentation/devicetree/usage-model.txt
> > +[1] Documentation/devicetree/usage-model.rst
> > [2] http://www.devicetree.org/Device_Tree_Usage
> >
> > OF Selftest has been designed to test the interface (include/linux/of.h)
> > diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst
> > similarity index 97%
> > rename from Documentation/devicetree/usage-model.txt
> > rename to Documentation/devicetree/usage-model.rst
> > index 33a8aaac02a8..326d7af10c5b 100644
> > --- a/Documentation/devicetree/usage-model.txt
> > +++ b/Documentation/devicetree/usage-model.rst
> > @@ -1,14 +1,18 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=========================
> > Linux and the Device Tree
> > --------------------------
> > +=========================
> > +
> > The Linux usage model for device tree data
> >
> > -Author: Grant Likely <grant.likely@xxxxxxxxxxxx>
> > +:Author: Grant Likely <grant.likely@xxxxxxxxxxxx>
> >
> > This article describes how Linux uses the device tree. An overview of
> > the device tree data format can be found on the device tree usage page
> > -at devicetree.org[1].
> > +at devicetree.org\ [1]_.
> >
> > -[1] http://devicetree.org/Device_Tree_Usage
> > +.. [1] http://devicetree.org/Device_Tree_Usage
>
> I don't know the proper ReST syntax for footnotes, but on the html page
> you kindly provided in 00/12, '.. [1]' is shown as '1(1,2)'.
>
> -Frank
The syntax is simple: just add an underline at the end, when referencing
it, like [1]_. The definitions should start with "..", like ".. [1] something".
Sphinx will automatically generate the reverse reference(s) at the html output.
Yet, sometimes (like the above), it needs to be escaped by a "\ ", as ReST would
recognize "foo[1]_" as something else.
Ps.: it also accepts an "auto-numbered" references like [#]_, but such syntax
require some care, in order to avoid wrong cross-references.
Regards,
Mauro
