From 82019b661d9f9659e21a33458d47ba6445f0d166 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 17:08:14 +0100 Subject: [PATCH 01/11] First iteration of improved Font.actual docs --- Doc/library/tkinter.font.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index b0f4505e9e3c69..6f31b82ff44314 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -47,7 +47,16 @@ The different font weights and slants are: .. method:: actual(option=None, displayof=None) - Return the attributes of the font. + Returns information about the actual attributes that are obtained when + the font is used on *displayof*; the actual attributes obtained may + differ from those given (and retrieved by :meth:`Font.cget`) due to + platform-dependent limitations, such as the availability of font + families and pointsizes. If *displayof* is omitted, it defaults to the + main window. + + If *option* is specified, value of just that attribute is returned; if + it is omitted, the return value is a dictionary of all the attributes + and their values. See above for a list of the possible attributes. .. method:: cget(option) @@ -93,4 +102,4 @@ The different font weights and slants are: .. function:: nametofont(name) - Return a :class:`Font` representation of a tk named font. \ No newline at end of file + Return a :class:`Font` representation of a tk named font. From a446cd6072b1c10c84889f8234b19c283224f60b Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 17:13:25 +0100 Subject: [PATCH 02/11] Slight clarification on Font.copy's name behaviour --- Doc/library/tkinter.font.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 6f31b82ff44314..4dd99cdbb01830 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -68,7 +68,7 @@ The different font weights and slants are: .. method:: copy() - Return new instance of the current font. + Return new instance of the current font with a different *name*. .. method:: measure(text, displayof=None) From cf263fb49bcfadb311fb2baa5c22fb4a881b4323 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 19:14:25 +0100 Subject: [PATCH 03/11] Added reference to tk man page --- Doc/library/tkinter.font.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 4dd99cdbb01830..ce917a0c97bef4 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -56,7 +56,7 @@ The different font weights and slants are: If *option* is specified, value of just that attribute is returned; if it is omitted, the return value is a dictionary of all the attributes - and their values. See above for a list of the possible attributes. + and their values. See above for a list of the possible attributes. [1]_ .. method:: cget(option) @@ -103,3 +103,9 @@ The different font weights and slants are: .. function:: nametofont(name) Return a :class:`Font` representation of a tk named font. + +References +---------- + +.. [1] Tk 8.6 font man page + https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5 From 63adfdcb7e45e057be93531954623f003793c356 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 19:48:06 +0100 Subject: [PATCH 04/11] Minor rephrasing (and typo fix) --- Doc/library/tkinter.font.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index ce917a0c97bef4..5eb61187c8fc63 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -48,14 +48,14 @@ The different font weights and slants are: .. method:: actual(option=None, displayof=None) Returns information about the actual attributes that are obtained when - the font is used on *displayof*; the actual attributes obtained may - differ from those given (and retrieved by :meth:`Font.cget`) due to - platform-dependent limitations, such as the availability of font - families and pointsizes. If *displayof* is omitted, it defaults to the + the font is used on *displayof*; the values obtained may differ from + those given (and retrieved by :meth:`Font.cget`) due to + platform-dependent limitations (such as the availability of font + families and pointsizes). If *displayof* is omitted, it defaults to the main window. - If *option* is specified, value of just that attribute is returned; if - it is omitted, the return value is a dictionary of all the attributes + If *option* is specified, the value of just that attribute is returned; + if it is omitted, the return value is a dictionary of all the attributes and their values. See above for a list of the possible attributes. [1]_ .. method:: cget(option) From 966592d3e4577079a06bcb1719dc08cb759412a8 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 21:42:59 +0100 Subject: [PATCH 05/11] Initial commit of Tal's suggestions --- Doc/library/tkinter.font.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 5eb61187c8fc63..01ce90ebc68026 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -49,10 +49,12 @@ The different font weights and slants are: Returns information about the actual attributes that are obtained when the font is used on *displayof*; the values obtained may differ from - those given (and retrieved by :meth:`Font.cget`) due to - platform-dependent limitations (such as the availability of font - families and pointsizes). If *displayof* is omitted, it defaults to the - main window. + those given as kwargs or similar method (and retrieved by + :meth:`Font.cget`) due to platform-dependent limitations (such as the + availability of font families and pointsizes). + + *displayof* accepts any tkinter widget and, if omitted, will default to + the main window. If *option* is specified, the value of just that attribute is returned; if it is omitted, the return value is a dictionary of all the attributes From 4a3ea487b8839ac03aa162068001f6c95fa26674 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 21:54:35 +0100 Subject: [PATCH 06/11] Attempt clarification of reason for link --- Doc/library/tkinter.font.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 01ce90ebc68026..9314f213a5fec5 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -109,5 +109,5 @@ The different font weights and slants are: References ---------- -.. [1] Tk 8.6 font man page - https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5 +.. [1] The :meth:`actual` docs are based on those found on the Tk 8.6 font man + page (https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5) From b8ca758dca07bda717f9e251108208fa99dd0de4 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Mon, 28 Sep 2020 21:58:25 +0100 Subject: [PATCH 07/11] Fix :meth: link to method --- Doc/library/tkinter.font.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 9314f213a5fec5..62ee8d6febbe5e 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -109,5 +109,5 @@ The different font weights and slants are: References ---------- -.. [1] The :meth:`actual` docs are based on those found on the Tk 8.6 font man - page (https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5) +.. [1] The :meth:`Font.actual` docs are based heavily on those found on the Tk + 8.6 font man page (https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5) From b30dbcc8d128ef8ff9f440c3d39e5e7491d18785 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Wed, 30 Sep 2020 11:44:04 +0100 Subject: [PATCH 08/11] Major rephrasing of actual docs --- Doc/library/tkinter.font.rst | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 62ee8d6febbe5e..19e6163099afe9 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -47,18 +47,19 @@ The different font weights and slants are: .. method:: actual(option=None, displayof=None) - Returns information about the actual attributes that are obtained when - the font is used on *displayof*; the values obtained may differ from - those given as kwargs or similar method (and retrieved by - :meth:`Font.cget`) due to platform-dependent limitations (such as the - availability of font families and pointsizes). + Returns the actual value for attributes when the given font is used on + *displayof*. Due to some differences between operating systems (such as + pointsizes and the availability of font families), some values returned + by this method may vary from those given as kwargs or similar method + (and retrieved by :meth:`Font.cget`). *displayof* accepts any tkinter widget and, if omitted, will default to the main window. - If *option* is specified, the value of just that attribute is returned; - if it is omitted, the return value is a dictionary of all the attributes - and their values. See above for a list of the possible attributes. [1]_ + If *option* is specified, the value of just that attribute is returned. + If it is omitted or ``None``, the returned value is a dictionary of all + the attributes and their values. See above for a list of acceptable + attributes. .. method:: cget(option) @@ -105,9 +106,3 @@ The different font weights and slants are: .. function:: nametofont(name) Return a :class:`Font` representation of a tk named font. - -References ----------- - -.. [1] The :meth:`Font.actual` docs are based heavily on those found on the Tk - 8.6 font man page (https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5) From f0767f07c703e1511cdd7778e702a782840d05ca Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Wed, 30 Sep 2020 15:02:28 +0100 Subject: [PATCH 09/11] Clarify 'displayof' option --- Doc/library/tkinter.font.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 19e6163099afe9..ae05ee0d2f92a4 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -48,14 +48,15 @@ The different font weights and slants are: .. method:: actual(option=None, displayof=None) Returns the actual value for attributes when the given font is used on - *displayof*. Due to some differences between operating systems (such as + the widget given by *displayof*. *displayof* accepts any tkinter widget + and, if omitted, will default to the main window (in most circumstances, + this will be your ``Tk`` instance). + + Due to some differences between operating systems (such as pointsizes and the availability of font families), some values returned by this method may vary from those given as kwargs or similar method (and retrieved by :meth:`Font.cget`). - *displayof* accepts any tkinter widget and, if omitted, will default to - the main window. - If *option* is specified, the value of just that attribute is returned. If it is omitted or ``None``, the returned value is a dictionary of all the attributes and their values. See above for a list of acceptable From 28879b1226370405103cc769c91ff5a0046fb22a Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Wed, 30 Sep 2020 15:11:13 +0100 Subject: [PATCH 10/11] Rewrap second paragraph --- Doc/library/tkinter.font.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index ae05ee0d2f92a4..ae2e7dabeeb199 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -52,10 +52,10 @@ The different font weights and slants are: and, if omitted, will default to the main window (in most circumstances, this will be your ``Tk`` instance). - Due to some differences between operating systems (such as - pointsizes and the availability of font families), some values returned - by this method may vary from those given as kwargs or similar method - (and retrieved by :meth:`Font.cget`). + Due to some differences between operating systems (such as pointsizes + and the availability of font families), some values returned by this + method may vary from those given as kwargs or similar method (and + retrieved by :meth:`Font.cget`). If *option* is specified, the value of just that attribute is returned. If it is omitted or ``None``, the returned value is a dictionary of all From 2a8eab52cbfc45e9559193deef0689b5bf86ac92 Mon Sep 17 00:00:00 2001 From: "E. Paine" <63801254+E-Paine@users.noreply.github.com> Date: Tue, 15 Dec 2020 20:01:44 +0000 Subject: [PATCH 11/11] Minor rephrasing to avoid saying 'kwargs' --- Doc/library/tkinter.font.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index ae2e7dabeeb199..d0fa4ab8d2f33d 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -54,8 +54,8 @@ The different font weights and slants are: Due to some differences between operating systems (such as pointsizes and the availability of font families), some values returned by this - method may vary from those given as kwargs or similar method (and - retrieved by :meth:`Font.cget`). + method may vary from those given as keyword arguments to either the + constructor or :meth:`Font.config` (and retrieved by :meth:`Font.cget`). If *option* is specified, the value of just that attribute is returned. If it is omitted or ``None``, the returned value is a dictionary of all