Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to howto.rst

Mauro Carvalho Chehab
2019-06-11T09:02:27Z

Em Tue, 11 Jun 2019 10:37:31 +0200
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Sat, Jun 08, 2019 at 11:27:23PM -0300, Mauro Carvalho Chehab wrote:
> > Sphinx need to know when a paragraph ends. So, do some adjustments
> > at the file for it to be properly parsed.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > that's said, I believe that this file should be moved to the
> > GPU/DRM documentation.
>
> Yes, but there's a bit a twist: This is definitely end-user documentation,
> so maybe should be in admin-guide?
>
> Atm all we have in Documentation/gpu/ is internals for drivers + some
> beginnings of uapi documentation for userspace developers.

On media, we have several different types of documents:

- uAPI - consumed by both userspace and kernelspace developers;
- kAPI - consumed by Kernel hackers;
- driver-specific information. Those are usually messy, as some contain
specific internal details, while others are pure end-user documentation.

there are several cross-references between uAPI and kAPI parts.

I've seem similar patterns on several other driver subsystems.

I agree with Jon's principle that the best is to focus the book per
audience. Yet, trying to rearrange the documentation means a lot of work,
specially on those cases where a single file contain different types of
documentation, like on media driver docs.

> Jon, what's your recommendation here for subsystem specific
> end-user/adming docs?

Jon, please correct me if I' wrong, bu I guess the plan is to place them
somewhere under Documentation/admin-guide/.

If so, perhaps creating a Documentation/admin-guide/drm dir there and
place docs like EDID/HOWTO.txt, svga.txt, etc would work.

Btw, that's one of the reasons[1] why I opted to keep the files where they
are: properly organizing the converted documents call for such kind
of discussions. On my experience, discussing names and directory locations
can generate warm discussions and take a lot of time to reach consensus.

[1] The other one is to avoid/simplify merge conflicts.

>
> Thanks, Daniel
>
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > Documentation/EDID/{HOWTO.txt => howto.rst} | 31 ++++++++++++-------
> > .../admin-guide/kernel-parameters.txt | 2 +-
> > drivers/gpu/drm/Kconfig | 2 +-
> > 3 files changed, 22 insertions(+), 13 deletions(-)
> > rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
> >
> > diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/howto.rst
> > similarity index 83%
> > rename from Documentation/EDID/HOWTO.txt
> > rename to Documentation/EDID/howto.rst
> > index 539871c3b785..725fd49a88ca 100644
> > --- a/Documentation/EDID/HOWTO.txt
> > +++ b/Documentation/EDID/howto.rst
> > @@ -1,3 +1,9 @@
> > +:orphan:
> > +
> > +====
> > +EDID
> > +====
> > +
> > In the good old days when graphics parameters were configured explicitly
> > in a file called xorg.conf, even broken hardware could be managed.
> >
> > @@ -34,16 +40,19 @@ Makefile. Please note that the EDID data structure expects the timing
> > values in a different way as compared to the standard X11 format.
> >
> > X11:
> > -HTimings: hdisp hsyncstart hsyncend htotal
> > -VTimings: vdisp vsyncstart vsyncend vtotal
> > + HTimings:
> > + hdisp hsyncstart hsyncend htotal
> > + VTimings:
> > + vdisp vsyncstart vsyncend vtotal
> >
> > -EDID:
> > -#define XPIX hdisp
> > -#define XBLANK htotal-hdisp
> > -#define XOFFSET hsyncstart-hdisp
> > -#define XPULSE hsyncend-hsyncstart
> > +EDID::
> >
> > -#define YPIX vdisp
> > -#define YBLANK vtotal-vdisp
> > -#define YOFFSET vsyncstart-vdisp
> > -#define YPULSE vsyncend-vsyncstart
> > + #define XPIX hdisp
> > + #define XBLANK htotal-hdisp
> > + #define XOFFSET hsyncstart-hdisp
> > + #define XPULSE hsyncend-hsyncstart
> > +
> > + #define YPIX vdisp
> > + #define YBLANK vtotal-vdisp
> > + #define YOFFSET vsyncstart-vdisp
> > + #define YPULSE vsyncend-vsyncstart
> > diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> > index 3d072ca532bb..3faf37b8b001 100644
> > --- a/Documentation/admin-guide/kernel-parameters.txt
> > +++ b/Documentation/admin-guide/kernel-parameters.txt
> > @@ -930,7 +930,7 @@
> > edid/1680x1050.bin, or edid/1920x1080.bin is given
> > and no file with the same name exists. Details and
> > instructions how to build your own EDID data are
> > - available in Documentation/EDID/HOWTO.txt. An EDID
> > + available in Documentation/EDID/howto.rst. An EDID
> > data set will only be used for a particular connector,
> > if its name and a colon are prepended to the EDID
> > name. Each connector may use a unique EDID data
> > diff --git a/drivers/gpu/drm/Kconfig b/drivers/gpu/drm/Kconfig
> > index 6b34949416b1..c3a6dd284c91 100644
> > --- a/drivers/gpu/drm/Kconfig
> > +++ b/drivers/gpu/drm/Kconfig
> > @@ -141,7 +141,7 @@ config DRM_LOAD_EDID_FIRMWARE
> > monitor are unable to provide appropriate EDID data. Since this
> > feature is provided as a workaround for broken hardware, the
> > default case is N. Details and instructions how to build your own
> > - EDID data are given in Documentation/EDID/HOWTO.txt.
> > + EDID data are given in Documentation/EDID/howto.rst.
> >
> > config DRM_DP_CEC
> > bool "Enable DisplayPort CEC-Tunneling-over-AUX HDMI support"
> > --
> > 2.21.0
> >
>

Thanks,
Mauro