Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Tue, 11 Jun 2019 11:40:10 +0200
From:   Daniel Vetter <daniel@ffwll.ch>
To:     Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc:     Daniel Vetter <daniel@ffwll.ch>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@infradead.org>,
        linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
        Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
        Maxime Ripard <maxime.ripard@bootlin.com>,
        Sean Paul <sean@poorly.run>, David Airlie <airlied@linux.ie>,
        dri-devel@lists.freedesktop.org
Subject: Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to
 howto.rst
Message-ID: <20190611094010.GZ21222@phenom.ffwll.local>
Mail-Followup-To: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@infradead.org>,
        linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
        Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
        Maxime Ripard <maxime.ripard@bootlin.com>,
        Sean Paul <sean@poorly.run>, David Airlie <airlied@linux.ie>,
        dri-devel@lists.freedesktop.org
References: <cover.1560045490.git.mchehab+samsung@kernel.org>
 <74bec0b5b7c32c8d84adbaf9ff208803475198e5.1560045490.git.mchehab+samsung@kernel.org>
 <20190611083731.GS21222@phenom.ffwll.local>
 <20190611060215.232af2bb@coco.lan>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190611060215.232af2bb@coco.lan>
User-Agent: Mutt/1.10.1 (2018-07-13)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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@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.

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@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

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch