Em Tue, 11 Jun 2019 10:37:31 +0200 Daniel Vetter <daniel@xxxxxxxx> 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@xxxxxxxxxx> > > --- > > 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