On Tue, Jun 11, 2019 at 06:02:15AM -0300, Mauro Carvalho Chehab wrote:
> 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.
Yeah atm we're doing a bad job of keeping the kapi and uapi parts
separate. But the plan at least is to move all the gpu related uapi stuff
into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that
out of the gpu folder ...
> > 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.
Oh definitely not asking for moving them at the same time, just wondering
how this should be solved properly.
-Daniel
>
> >
> > 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
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/dri-devel
