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

From: Daniel Vetter <daniel@ffwll.ch>
To: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
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>,
	Daniel Vetter <daniel@ffwll.ch>,
	dri-devel@lists.freedesktop.org
Subject: Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to howto.rst
Date: Tue, 11 Jun 2019 10:37:31 +0200	[thread overview]
Message-ID: <20190611083731.GS21222@phenom.ffwll.local> (raw)
In-Reply-To: <74bec0b5b7c32c8d84adbaf9ff208803475198e5.1560045490.git.mchehab+samsung@kernel.org>

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.

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

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
> 

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