[Docstring-checkins] CVS: dps/spec dps-notes.txt,1.35,1.36

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

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

Modified Files:
	dps-notes.txt 
Log Message:
fixed whitespace & updated

Index: dps-notes.txt
===================================================================
RCS file: /cvsroot/docstring/dps/spec/dps-notes.txt,v
retrieving revision 1.35
retrieving revision 1.36
diff -C2 -d -r1.35 -r1.36
*** dps-notes.txt	13 Apr 2002 17:09:21 -0000	1.35
--- dps-notes.txt	18 Apr 2002 02:54:58 -0000	1.36
***************
*** 18,22 ****
          [Tibs:] Eventually we need to have direct documentation in
          there on how it all hangs together - the DTD is not enough
!         (indeed, is it still meant to be correct? [Yes, it is.]).

  - Rework PEP 257, separating style from spec from tools, wrt DPS?  See
--- 18,22 ----
          [Tibs:] Eventually we need to have direct documentation in
          there on how it all hangs together - the DTD is not enough
!         (indeed, is it still meant to be correct?  [Yes, it is.]).

  - Rework PEP 257, separating style from spec from tools, wrt DPS?  See
***************
*** 35,49 ****
  - Get cracking on the DPS itself!

! - Add layout component to framework? Or part of the formatter?

! - Add validation? See http://pytrex.sourceforge.net, RELAX NG.

! - Write modules for common transforms. See `Unimplemented Transforms`_
!   below.

  - Ask Python-dev for opinions (GvR for a pronouncement) on special
    variables (__author__, __version__, etc.): convenience vs. namespace
!   pollution. Ask opinions on whether or not the DPS should recognize &
!   use them.

  - Once doctree.txt is fleshed out, how about breaking (most of) it up
--- 35,49 ----
  - Get cracking on the DPS itself!

! - Add layout component to framework?  Or part of the formatter?

! - Add validation?  See http://pytrex.sourceforge.net, RELAX NG.

! - Write modules for common transforms.  See `Unimplemented
!   Transforms`_ below.

  - Ask Python-dev for opinions (GvR for a pronouncement) on special
    variables (__author__, __version__, etc.): convenience vs. namespace
!   pollution.  Ask opinions on whether or not the DPS should recognize
!   & use them.

  - Once doctree.txt is fleshed out, how about breaking (most of) it up
***************
*** 60,74 ****
    - Remove complex import code.
    - Rename gpdi.dtd to docutils.dtd.
!   - Rename writers/html.py to html4_css1.py. With aliases?

  - Provide a mechanism to pass options to Readers, Writers, and Parsers
!   through dps.core.publish/Publisher? Or create custom
    Reader/Writer/Parser objects first, and pass *them* to
    publish/Publisher?

  - In reader.get_reader_class (& parser & writer too), should we be
!   importing 'standalone' or 'dps.readers.standalone'? (This would
    avoid importing top-level modules if the module name is not in
!   dps/readers. Potential nastiness.)

  - Perhaps store a name->id mapping file?  This could be stored
--- 60,74 ----
    - Remove complex import code.
    - Rename gpdi.dtd to docutils.dtd.
!   - Rename writers/html.py to html4_css1.py.  With aliases?

  - Provide a mechanism to pass options to Readers, Writers, and Parsers
!   through dps.core.publish/Publisher?  Or create custom
    Reader/Writer/Parser objects first, and pass *them* to
    publish/Publisher?

  - In reader.get_reader_class (& parser & writer too), should we be
!   importing 'standalone' or 'dps.readers.standalone'?  (This would
    avoid importing top-level modules if the module name is not in
!   dps/readers.  Potential nastiness.)

  - Perhaps store a name->id mapping file?  This could be stored
***************
*** 82,86 ****
  - Considerations for an HTML Writer [#]_:

!   - Boolean attributes. ``<element boolean>`` is good, ``<element
      boolean="boolean">`` is bad.  Use a special value in attribute
      mappings, such as ``None``?
--- 82,86 ----
  - Considerations for an HTML Writer [#]_:

!   - Boolean attributes.  ``<element boolean>`` is good, ``<element
      boolean="boolean">`` is bad.  Use a special value in attribute
      mappings, such as ``None``?
***************
*** 106,109 ****
--- 106,112 ----
    and substitutions for dynamic stuff.

+ - Improve the granularity of document parts in the HTML writer, so
+   that one could just grab the parts needed.
+ 

  Coding Conventions
***************
*** 114,118 ****
  PEPs, with the following clarifications:

! - 4 spaces per indentation level. No tabs.
  - No one-liner compound statements (i.e., no ``if x: return``: use two
    lines & indentation), except for degenerate class or method
--- 117,121 ----
  PEPs, with the following clarifications:

! - 4 spaces per indentation level.  No tabs.
  - No one-liner compound statements (i.e., no ``if x: return``: use two
    lines & indentation), except for degenerate class or method
***************
*** 121,126 ****
  - "CamelCase" shall be used for class names.
  - Use "lowercase" or "lowercase_with_underscores" for function,
!   method, and variable names. For short names, maximum two joined
!   words, use lowercase (e.g. 'tagname'). For long names with three or
    more joined words, or where it's hard to parse the split between two
    words, use lowercase_with_underscores (e.g., 'note_explicit_target',
--- 124,129 ----
  - "CamelCase" shall be used for class names.
  - Use "lowercase" or "lowercase_with_underscores" for function,
!   method, and variable names.  For short names, maximum two joined
!   words, use lowercase (e.g. 'tagname').  For long names with three or
    more joined words, or where it's hard to parse the split between two
    words, use lowercase_with_underscores (e.g., 'note_explicit_target',
***************
*** 160,164 ****

  Should this be done before or after reference-resolving transforms
! are applied? What about references from within one subdocument to
  inside another?

--- 163,167 ----

  Should this be done before or after reference-resolving transforms
! are applied?  What about references from within one subdocument to
  inside another?

***************
*** 168,175 ****

  If the processed document is written to multiple files (possibly in a
! directory tree), it will need to be split up. References will have to
  be adjusted.

! (HTML only? See Distributors_ below.)

--- 171,178 ----

  If the processed document is written to multiple files (possibly in a
! directory tree), it will need to be split up.  References will have to
  be adjusted.

! (HTML only?  See Distributors_ below.)

***************
*** 211,215 ****
  - functions (+ formal parameters & defaults)

! (Extract comments too? For example, comments at the start of a module
  would be a good place for bibliographic field lists.)

--- 214,218 ----
  - functions (+ formal parameters & defaults)

! (Extract comments too?  For example, comments at the start of a module
  would be a good place for bibliographic field lists.)

***************
*** 254,273 ****

  I've had trouble reconciling the roles of input parser and output
! writer with the idea of modes ("readers" or "directors"). Does the
  mode govern the tranformation of the input, the output, or both?
  Perhaps the mode should be split into two.

! For example, say the source of our input is a Python module. Our
! "input mode" should be the "Python Source Reader". It discovers (from
! ``__docformat__``) that the input parser is "reStructuredText". If we
! want HTML, we'll specify the "HTML" output formatter. But there's a
! piece missing. What *kind* or *style* of HTML output do we want?
! PyDoc-style, LibRefMan style, etc. (many people will want to specify
! and control their own style). Is the output style specific to a
! particular output format (XML, HTML, etc.)? Is the style specific to
! the input mode? Or can/should they be independent?

  I envision interaction between the input parser, an "input mode" , and
! the output formatter. The same intermediate data format would be used
  between each of these, being transformed as it progresses.

--- 257,276 ----

  I've had trouble reconciling the roles of input parser and output
! writer with the idea of modes ("readers" or "directors").  Does the
  mode govern the tranformation of the input, the output, or both?
  Perhaps the mode should be split into two.

! For example, say the source of our input is a Python module.  Our
! "input mode" should be the "Python Source Reader".  It discovers (from
! ``__docformat__``) that the input parser is "reStructuredText".  If we
! want HTML, we'll specify the "HTML" output formatter.  But there's a
! piece missing.  What *kind* or *style* of HTML output do we want?
! PyDoc-style, LibRefMan style, etc.  (many people will want to specify
! and control their own style).  Is the output style specific to a
! particular output format (XML, HTML, etc.)?  Is the style specific to
! the input mode?  Or can/should they be independent?

  I envision interaction between the input parser, an "input mode" , and
! the output formatter.  The same intermediate data format would be used
  between each of these, being transformed as it progresses.