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 06:02:15 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To:     Daniel Vetter <daniel@ffwll.ch>
Cc:     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: <20190611060215.232af2bb@coco.lan>
In-Reply-To: <20190611083731.GS21222@phenom.ffwll.local>
References: <cover.1560045490.git.mchehab+samsung@kernel.org>
        <74bec0b5b7c32c8d84adbaf9ff208803475198e5.1560045490.git.mchehab+samsung@kernel.org>
        <20190611083731.GS21222@phenom.ffwll.local>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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