classification
Title: doc: termios and ioctl reference links
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: angad, berker.peksag, docs@python, eric.araujo, georg.brandl, orsenthil, python-dev, techtonik
Priority: normal Keywords: easy, patch

Created on 2010-04-24 16:09 by techtonik, last changed 2016-06-03 06:52 by orsenthil. This issue is now closed.

Files
File name Uploaded Description Edit
____.reference-termios-specification-for-flags.diff techtonik, 2010-04-24 16:09 review
8519.reference-termios-specification-for-flags.diff techtonik, 2010-04-24 16:42 review
posix_specification_links_fcntl_ioctl_termios.patch angad, 2015-07-04 07:55 review
Messages (14)
msg104094 - (view) Author: anatoly techtonik (techtonik) Date: 2010-04-24 16:09
The patch adds link to reference with various flags for termios functions and fcntl.ioctl call.
msg104095 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-04-24 16:14
Note that there can be any whitespace in reST markup, e.g. you can put a newline betweeen “`thing” and “<link>`_”, thus avoiding too long lines. I think you can put a newline in a “<link>” too, they will be removed.

Regards
msg104096 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-04-24 16:29
The POSIX reference is OK; I'm hesitant to put a Linux-specific reference in though.  Also, ioctls are not limited to tty operations.  IMO a :manpage:`ioctl(2)` would suffice.
msg104098 - (view) Author: anatoly techtonik (techtonik) Date: 2010-04-24 16:42
Éric, thanks, attached reStructured patch.

Georg, ioctl(2) is useless, because it doesn't contain the information people need in addition to Python manual, i.e. various examples (like how to get console size) and constants (like TIOCGWINSZ) that are hard to find otherwise.
msg104100 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-04-24 16:57
ioctl(2) usually has "see also" entries that list the available ioctls, such as ioctl_list on linux.

If you want to link to examples like getting console size, the manpage isn't very helpful either, since you have to figure out how exactly to call ioctl.  Linking to a pertinent recipe e.g. in the Cookbook, or including the example right there makes much more sense.
msg104106 - (view) Author: anatoly techtonik (techtonik) Date: 2010-04-24 17:22
I do not mind if you include a better link with ioctl constants explained or have ideas for examples. I hope you agree the ioctl(2) man page contains much less useful information than http://www.kernel.org/doc/man-pages/online/pages/man4/tty_ioctl.4.html

But I see your point that ioctl is not used solely for tty. Perhaps there could be two links. Removing tty_ioctl constants reference is not an option for me, because the whole stuff is complicated and for me it was very hard to find these console functions for Linux. There is no other way to work with Linux console from Python.
msg222940 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-13 15:25
My understanding is that we can't use the patches as the originator has never signed the CLA.  Am I correct or does this only apply to code, or what?
msg223076 - (view) Author: Guido van Rossum (Guido.van.Rossum) Date: 2014-07-15 02:03
In this case I think there is no legal issue. All you have to do is take the link from the patch and come up with a fresh patch of your own.

(However I think Georg's objection against a Linux-specific link stands. You can probably find a POSIX link that would be acceptable.)
msg246242 - (view) Author: Angad Singh (angad) * Date: 2015-07-04 07:55
Created a patch for this. Added POSIX links for fcntl, ioctl and termios. Let me know if I am missing anything.
msg258647 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-01-20 06:39
I followed the previous discussions and reviewed the patch. With respect to the patch, I see few drawbacks in providing links to references like this:

`fcntl <http://pubs.opengroup.org/onlinepubs/009695399/basedefs/fcntl.h.html>`_
`ioctl <http://pubs.opengroup.org/onlinepubs/009695399/functions/ioctl.html>`_
`the POSIX specification +<http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/termios.h.html>`_

these URLs can quickly become outdated and it will be an unnecessary detail for us to maintain.

Instead, I suggest we have references like :manpage:`fcntl(2)`, :manpage:`ioctl(2)` and :manpage:`termios(2)`, a supported directive by sphinx, so that users can quickly search for those and land up on relevant and latest documentation.
msg266863 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-02 02:03
+1 for using the manpage directives.
msg267061 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-03 06:50
New changeset f53a0566a290 by Senthil Kumaran in branch '3.5':
issue8519 - Reference termios and ioctl manual pages in the library documentation.
https://hg.python.org/cpython/rev/f53a0566a290

New changeset 8db146bec24b by Senthil Kumaran in branch 'default':
[merge from 3.5] - issue8519 - Reference termios and ioctl manual pages in the library documentation.
https://hg.python.org/cpython/rev/8db146bec24b
msg267062 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-03 06:51
New changeset 55886a6aed4b by Senthil Kumaran in branch '2.7':
[backport to 2.7] - issue8519 - Reference termios and ioctl manual pages in the library documentation.
https://hg.python.org/cpython/rev/55886a6aed4b
msg267063 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-06-03 06:52
Thanks Angad and Anatoly for the patches discussions.
Thank you Berker for review.

Made the changes in all active versions of python. Let this issue reset in peace.
History
Date User Action Args
2016-06-03 06:52:37orsenthilsetstatus: open -> closed
resolution: fixed
messages: + msg267063

stage: needs patch -> resolved
2016-06-03 06:51:29python-devsetmessages: + msg267062
2016-06-03 06:50:17python-devsetnosy: + python-dev
messages: + msg267061
2016-06-02 02:03:14berker.peksagsettype: enhancement
versions: + Python 3.5, Python 3.6
keywords: + easy
nosy: + berker.peksag

messages: + msg266863
stage: needs patch
2016-01-20 16:26:49gvanrossumsetnosy: - Guido.van.Rossum
2016-01-20 11:26:44BreamoreBoysetnosy: - BreamoreBoy
2016-01-20 06:39:00orsenthilsetnosy: + orsenthil
messages: + msg258647
2015-07-04 07:55:30angadsetfiles: + posix_specification_links_fcntl_ioctl_termios.patch
nosy: + angad
messages: + msg246242

2014-07-15 02:03:21Guido.van.Rossumsetnosy: + Guido.van.Rossum
messages: + msg223076
2014-07-13 15:25:14BreamoreBoysetnosy: + BreamoreBoy
messages: + msg222940
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2010-06-07 00:39:43brian.curtinsettitle: [patch] doc: termios and ioctl reference links -> doc: termios and ioctl reference links
2010-06-05 16:04:10techtoniksetnosy: + docs@python
2010-04-24 17:22:20techtoniksetmessages: + msg104106
2010-04-24 16:57:16georg.brandlsetmessages: + msg104100
2010-04-24 16:42:37techtoniksetfiles: + 8519.reference-termios-specification-for-flags.diff

messages: + msg104098
2010-04-24 16:29:57georg.brandlsetmessages: + msg104096
2010-04-24 16:14:28eric.araujosetnosy: + eric.araujo
messages: + msg104095
2010-04-24 16:09:49techtonikcreate