[Docstring-checkins] CVS: dps/spec pep-0258.txt,1.1.1.1,1.2

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/docstring/dps/spec
In directory usw-pr-cvs1:/tmp/cvs-serv18949/dps/spec

Modified Files:
	pep-0258.txt 
Log Message:
clarifications due to Tony Ibbs; added names to system warnings

Index: pep-0258.txt
===================================================================
RCS file: /cvsroot/docstring/dps/spec/pep-0258.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** pep-0258.txt	2001/07/22 22:36:26	1.1.1.1
--- pep-0258.txt	2001/08/04 15:43:33	1.2
***************
*** 45,51 ****
         in the following places within Python modules:

!        a) At the beginning of a module, class definition, or function
!           definition, after any comments.  This is the standard for
!           Python __doc__ attributes.

         b) Immediately following a simple assignment at the top level
--- 45,51 ----
         in the following places within Python modules:

!        a) At the beginning of a module, function definition, class
!           definition, or method definition, after any comments.  This
!           is the standard for Python __doc__ attributes.

         b) Immediately following a simple assignment at the top level
***************
*** 66,70 ****
         string literal expressions (2b and 2c above), meaning importing
         the module will lose these docstrings.  Of course, standard
!        Python parsing tools such as the 'parser' library module should
         be used.

--- 66,70 ----
         string literal expressions (2b and 2c above), meaning importing
         the module will lose these docstrings.  Of course, standard
!        Python parsing tools such as the 'parser' library module may
         be used.

***************
*** 167,172 ****

      Issue: This breaks 'from __future__ import' statements in Python
!     2.1 for multiple module docstrings.  Resolution?

      1. Should we search for docstrings after a __future__ statement?
         Very ugly.
--- 167,183 ----

      Issue: This breaks 'from __future__ import' statements in Python
!     2.1 for multiple module docstrings.  The Python Reference Manual
!     specifies:
! 
!         A future statement must appear near the top of the module. The
!         only lines that can appear before a future statement are:
! 
!         * the module docstring (if any), 
!         * comments, 
!         * blank lines, and 
!         * other future statements. 

+     Resolution?
+ 
      1. Should we search for docstrings after a __future__ statement?
         Very ugly.
***************
*** 296,304 ****
      ===========================

!     A single intermediate data structure is used internally by the
!     docstring processing system.  This data structure is a DOM tree
!     (or equivalent) whose schema is documented in an XML DTD
!     (eXtensible Markup Language Document Type Definition), which comes
!     in three parts:

      - the Python Plaintext Document Interface DTD, ppdi.dtd [6],
--- 307,317 ----
      ===========================

!     A single intermediate data structure is used by the docstring
!     processing system, in the interfaces between parsers, the DPS
!     itself, and formatters.  It is not required that this data
!     structure be used internally by any of the componentes.  This data
!     structure is similar to a DOM tree whose schema is documented in
!     an XML DTD (eXtensible Markup Language Document Type Definition),
!     which comes in three parts:

      - the Python Plaintext Document Interface DTD, ppdi.dtd [6],
***************
*** 326,332 ****
      File/directory naming & structure conventions.  In-memory data
      structure should follow filesystem naming; file/directory ==
!     leaf/node.  Use a directory hierarchy rather than long file names
!     (long file names were one of the reasons pythondoc couldn't run on
!     MacOS).

      Error Handling
--- 339,347 ----
      File/directory naming & structure conventions.  In-memory data
      structure should follow filesystem naming; file/directory ==
!     leaf/node.  Use a directory hierarchy rather than long file names.
!     (The files generated by pythondoc used compound file names, like
!     'packagename.modulename.classname.html', which were often too long
!     for the 38-character MacOS file name length limit.  This is one of
!     the reasons pythondoc couldn't run on MacOS).

      Error Handling
***************
*** 334,354 ****

      When the parser encounters an error in markup, it inserts a system
!     warning (DTD element 'system_warning'). There are four levels of
      system warnings:

!     - Level-0: A minor issue that can be ignored. There is no effect
!       on the processing. Typically level-0 system warnings are not
!       reported.

!     - Level-1: An issue that should be addressed. If ignored, there
!       may be minor problems with the output.

!     - Level-2: An issue that should be addressed. If ignored, there
!       may be significant problems with the output.

!     - Level-3: A major issue that must be addressed. Typically level-3
!       system warnings are turned into exceptions which halt
!       processing. If ignored, the output will have significant
!       problems.

--- 349,369 ----

      When the parser encounters an error in markup, it inserts a system
!     warning (DTD element 'system_warning').  There are four levels of
      system warnings:

!     - Level-0, "information": A minor issue that can be ignored.
!       There is no effect on the processing. Typically level-0 system
!       warnings are not reported.

!     - Level-1, "warning": An issue that should be addressed.  If
!       ignored, there may be unpredictable problems with the output.

!     - Level-2, "error": An error that should be addressed.  If
!       ignored, the output will contain errors.

!     - Level-3, "severe": A severe error that must be addressed.
!       Typically level-3 system warnings are turned into exceptions
!       which halt processing.  If ignored, the output will contain
!       severe errors.

***************
*** 368,376 ****
      [5] http://lcweb.loc.gov/standards/iso639-2/englangn.html

!     [6] http://docstring.sf.net/spec/ppdi.dtd

!     [7] http://docstring.sf.net/spec/gpdi.dtd

!     [8] http://docstring.sf.net/spec/soextblx.dtd

      [9] http://www.python.org/sigs/doc-sig/
--- 383,391 ----
      [5] http://lcweb.loc.gov/standards/iso639-2/englangn.html

!     [6] http://docstring.sourceforge.net/spec/ppdi.dtd

!     [7] http://docstring.sourceforge.net/spec/gpdi.dtd

!     [8] http://docstring.sourceforge.net/spec/soextblx.dtd

      [9] http://www.python.org/sigs/doc-sig/
***************
*** 380,384 ****

      A SourceForge project has been set up for this work at
!     http://docstring.sf.net.

--- 395,399 ----

      A SourceForge project has been set up for this work at
!     http://docstring.sourceforge.net.