Skip to content

gh-86017: Improve font actual docs #22434

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: main
Choose a base branch
from

Conversation

E-Paine
Copy link
Contributor

@E-Paine E-Paine commented Sep 28, 2020

Given that Serhiy does not see the reason for a equal method and Tal was unaware of the actual method, I instead propose a major improvement to the actual docs. The docs are currently very brief and do not offer any explanation on what the kwargs are for. I have completely removed the existing doc and instead added a modified version of the tk man's description.

With it being so heavy based on the man page, I assume we need to give credit but would appreciate if someone could double check I have done so correctly.

EDIT:
I do not intend to add a news entry as I deem this a fairly trivial change, though obviously cannot add the skip-news tag myself (so will just ignore the bedevere/news failure).

https://bugs.python.org/issue41851

@E-Paine
Copy link
Contributor Author

E-Paine commented Sep 28, 2020

Thanks Tal for adding the label!

Copy link
Contributor

@taleinat taleinat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are excellent improvements to the docs!

I have a few suggestions.


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]_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This says "above" but the reference is to a separate page. Is "above" referencing the constructor's docs? If so, let's add a link to it.

Copy link
Contributor Author

@E-Paine E-Paine Sep 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "above" is referring to "additional keyword options". The link is to give reasonable credit to the man page as the entirety of the actual docs is just a modified version of the content found there (though I'm open to a more clear way of showing this).

@@ -59,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*.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice!

Comment on lines 110 to 111
https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be very useful to many who wouldn't know where to find this otherwise!

@taleinat taleinat added the needs backport to 3.9 only security fixes label Sep 28, 2020
@taleinat
Copy link
Contributor

Note that Docs/library/tkinter.font.rst only exists since 3.9.

@E-Paine E-Paine requested a review from taleinat September 29, 2020 15:51
@taleinat
Copy link
Contributor

taleinat commented Sep 29, 2020

The Tk docs are released under a permissive license that allows free use, but require attribution. See full quote of the license below. (source: the license.terms file in the tk-8.6.10.tar.gz source archive, which includes the documentation in the doc/ directory.)

Would you be able to re-word that part in your own words, so we can avoid having to include the full attribution notice?

This software is copyrighted by the Regents of the University of
California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState
Corporation, Apple Inc. and other parties. The following terms apply to
all files associated with the software unless explicitly disclaimed in
individual files.

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors
and need not follow the licensing terms described here, provided that
the new terms are clearly indicated on the first page of each file where
they apply.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.

GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights"
in the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the
Government shall have only "Restricted Rights" as defined in Clause
252.227-7013 (b) (3) of DFARs. Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.

@E-Paine
Copy link
Contributor Author

E-Paine commented Sep 29, 2020

Oh... I'll work on it!

@taleinat
Copy link
Contributor

Thanks for the rewrite, @E-Paine, looking good!

Perhaps let's separate the last sentence about displayof into a new paragraph, and mention what type of object it is: Is it a string? What does it reference? Can we give an example?

@E-Paine
Copy link
Contributor Author

E-Paine commented Sep 30, 2020

@taleinat did you mean to repeat what you said earlier in the review about separating the last sentence into its own paragraph? I believe this is already resolved but can look at it again if you want.

@taleinat
Copy link
Contributor

taleinat commented Sep 30, 2020

@taleinat did you mean to repeat what you said earlier in the review about separating the last sentence into its own paragraph? I believe this is already resolved but can look at it again if you want.

Yes, it was intentional. I should have mentioned that I was repeating it.

The current text still doesn't explain what "displayof" refers to and what type(s) it supports.

@E-Paine
Copy link
Contributor Author

E-Paine commented Sep 30, 2020

@taleinat I am not quite sure I understand. I had already said it accepted any tkinter widget but have attempted to clarify in the latest commit.

@serhiy-storchaka serhiy-storchaka added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes and removed needs backport to 3.9 only security fixes labels May 20, 2022
@terryjreedy
Copy link
Member

terryjreedy commented Nov 3, 2022

Unless someone beats me, I intend to review, fix the merge conflict (easy context change), and likely merge. I opened a draft issue on IDLE Issues under Configure to not forget forever: "Use font.actual to compare user font to defaults".

@hugovk hugovk removed the needs backport to 3.10 only security fixes label Apr 8, 2023
@erlend-aasland erlend-aasland changed the title bpo-41851: Improve font actual docs gh-86017: Improve font actual docs Jan 5, 2024
@erlend-aasland erlend-aasland added the needs backport to 3.12 only security fixes label Jan 5, 2024
@hugovk hugovk removed the needs backport to 3.11 only security fixes label Apr 11, 2024
@serhiy-storchaka serhiy-storchaka added the needs backport to 3.13 bugs and security fixes label May 9, 2024
@hugovk hugovk removed the needs backport to 3.12 only security fixes label Apr 10, 2025
@python-cla-bot
Copy link

python-cla-bot bot commented Apr 18, 2025

All commit authors signed the Contributor License Agreement.

CLA signed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting review docs Documentation in the Doc dir needs backport to 3.13 bugs and security fixes skip news
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.

10 participants