IPC8 Documentation SIG Report

This is preliminary! It will be updated in a couple of days.

The Documentation SIG meeting at IPC8 was well attended and lively; we pretty much packed the room (estimates vary considerably, and I'm not good at that), even though we were competing with the internationalization session led by Andy Robinson. I think just about everyone there had something interesting to say.

The most important accomplishment of the session was a list of specific issues which need to be addressed by the SIG; there was not time to prioritize these items, so I've assigned priorities by ordering them here. These can be further discussed on the SIG mailing list as needed. I've augmented the descriptions of these to be meaningful for people who weren't able to attend. The ordering does not necessarily reflect technical dependencies between items; some items may depend on the existence of items listed farther down the list.

1. Identification & description of target audiences.

2. Content requirements need to be developed. (I promised a draft of this within one week; due date is 3 Feb 2000, it will be posted to the mailing list.)

3. Embedded documentation syntax specification needs to be written and given the Doc-SIG "stamp of approval" to be passed on for Guido's blessing. This should be substantially based on the Structured Text proposal developed on the Doc-SIG in late 1996 and early 1997.

4. For out-of-line documents, we need to decide on SGML or XML and define the DTD. The initial draft of this is in my lap; it will be posted to the SIG when available.

5. Minimum list of output formats is needed to guide development of tools.

6. Develop authoring guidelines for programmers, dealing with both content and syntax.

7. Support for documentation access:
   • Tools are needed for interactive access (from the interpreter prompt, IDLE, PythonWin, command line, etc.).

   • Develop an API to support runtime access to documentation at a higher level than SAX/DOM. This would be used to develop help facilities for IDEs, the interactive interpreter, and

   • Linkage / inclusion of material must be defined to allow reference to / inclusion of source-embedded materials from / within out-of-line documents. Paul Dubois pointed out that he'd like to be able to write manuals which incorporate, via both linking and information-set inclusion. (Note: by inclusion, we're talking about "information-set" inclusion, which is different from transclusion, as discussed by Ted Nelson.)

8. Tools for content extraction from source code (Python, C/C++, Java), to augment docstring content.

9. Allowance for non-textual content needs to be made (diagrams, images, math). What needs to be supported regarding degradation in constrained display environments?

10. Content-creation and validation tools need to be designed & implemented. While tools are available to validate SGML and XML against DTDs, additional validation can be performed within the domain of Python documentation, most importantly in the module reference subset.

11. Someone should consult with publishers regarding their requirements, presumably to allow Python documentation to be incorporated in whole or in part into published books (paper or electronic).

12. Should multiple docstrings within a scope be accumulated? If so, determine the method of exposure to reflection and modify the byte-code compiler appropriately. Docstrings should be stored with line number information. (This information is currently available from the parse tree; does it need to be available for reflection as well?)