Docs point to FAQ Section 3, but FAQs are not numbered

[stutzbach]

BPO	9728
Nosy	@terryjreedy, @tjguk, @merwok, @briancurtin

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2010-09-14.16:11:07.027>
created_at = <Date 2010-09-01.01:49:07.494>
labels = ['docs']
title = 'Docs point to FAQ Section 3, but FAQs are not numbered'
updated_at = <Date 2010-09-14.21:22:05.192>
user = 'https://bugs.python.org/stutzbach'

bugs.python.org fields:

activity = <Date 2010-09-14.21:22:05.192>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-09-14.16:11:07.027>
closer = 'stutzbach'
components = ['Documentation']
creation = <Date 2010-09-01.01:49:07.494>
creator = 'stutzbach'
dependencies = []
files = []
hgrepos = []
issue_num = 9728
keywords = []
message_count = 8.0
messages = ['115285', '115493', '116136', '116404', '116405', '116406', '116407', '116420']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'tim.golden', 'stutzbach', 'eric.araujo', 'brian.curtin', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue9728'
versions = ['Python 3.1', 'Python 2.7', 'Python 3.2']

[stutzbach]

In Doc/extending/windows.rst, there's the following text:

------------------------------------------------------------------------
If your module creates a new type, you may have trouble with this line::

   PyVarObject_HEAD_INIT(&PyType_Type, 0)

Change it to::

   PyVarObject_HEAD_INIT(NULL, 0)

and add the following to the module initialization function::

MyObject_Type.ob_type = &PyType_Type;

Refer to section 3 of the Python FAQ <http://www.python.org/doc/faq>_ for
details on why you must do this.
------------------------------------------------------------------------

If I assume that Section 3 means, the third link on the FAQ page, I can't find the FAQ that's being alluded to here. There's a comment in Include/pyport.h that I believe to be related:

        /* Under Cygwin, auto-import functions to prevent compilation */
        /* failures similar to http://python.org/doc/FAQ.html#3.24 */

However, that link no longer goes to a particular question and I can't tell which question it once referred to.

I ran into this because I'm trying to understand the cause of the issue which I suspect is related to Issue bpo-6672.

[terryjreedy]

As I remember, the FAQ was once that, *the* (giant) FAQ, with numbered sections. When broken into pieces, the order may have been re-arranged.

Given that the broken reference is in extending/windows, I would look in both the Extending and Windows FAQs. However, I found neither 'PyType_Type' nor 'PyVarObject_HEAD_INIT' nor 'initialization' in either.

Besides removing the dead reference, you could either look through the revision history of the file or ask on pydev if you need the info.

The split-up FAQs first appear in a release doc set in Python 2.6.4, documentation released on 25 October 2009. I do not know if the earlier, unitary FAQ is in the repository or not.

[merwok]

I tried to find the old FAQ in the Debian package for 2.5 but failed. It looks like this require a fair bit of version control exploration.

[stutzbach]

Where does/did the FAQ live in the version control tree?

[stutzbach]

It looks like the FAQ used be generated using Tools/faqwiz/faqwiz.py (which no longer exists). According to that file:

-----------------------------------------------------------------------
This is a CGI program that maintains a user-editable FAQ. It uses RCS
to keep track of changes to individual FAQ entries. It is fully
configurable; everything you might want to change when using this
program to maintain some other FAQ than the Python FAQ is contained in
the configuration module, faqconf.py.
-----------------------------------------------------------------------

In other words, while the FAQ was under version control, it wasn't the regular repository.

I'll ask on python-dev is anyone has a copy.

[stutzbach]

Nevermind... archive.org has it. :-)

[stutzbach]

Fixed in r84810, r84811, and 84812.

For anyone curious, the old FAQ entry is here:
http://web.archive.org/web/20010203161100/http://www.python.org/doc/FAQ.html#3.24

[merwok]

Thanks for the investigation!