Opaque documentation

Discussion in 'Python' started by egbert, Oct 28, 2005.

  1. egbert

    egbert Guest

    Once in a while you come acros aline of documentation
    that you have to, or that invites you to, read it again.
    This is what I found in PyGTK:

    The set_screen method sets the 'screen" property to
    the gtk.gdk.Screen specified by screen. The "screen" property
    contains the screen that the window is displayed on.

    The screen on the second line, before the period, is in italics,
    if that helps.

    I like these texts. Prose should not disclose its secrets at once.
    If you have other examples, please let us know.
    --
    Egbert Bouwman - Keizersgracht 197 II - 1016 DS Amsterdam - 020 6257991
    ========================================================================
    egbert, Oct 28, 2005
    #1
    1. Advertising

  2. egbert

    Ben Sizer Guest

    egbert wrote:
    > Once in a while you come acros aline of documentation
    > that you have to, or that invites you to, read it again.
    > This is what I found in PyGTK:
    >
    > The set_screen method sets the 'screen" property to
    > the gtk.gdk.Screen specified by screen. The "screen" property
    > contains the screen that the window is displayed on.


    Clearly this is a violation of "once and only once". I'd reword it as:

    The set_screen method sets the property to the gtk.gdk specified
    by. The property contains the that the window is displayed on.

    ;) Maybe if I was being less facetious, someone could reword it as:

    The set_screen method sets the 'screen" property to
    the supplied gtk.gdk.Screen object. This property
    contains the screen that the window is displayed on.

    Documentation is often a problem with Python and its libraries, sadly.
    The same almost certainly goes for most open source projects.

    --
    Ben Sizer
    Ben Sizer, Oct 28, 2005
    #2
    1. Advertising

  3. egbert

    Mike Meyer Guest

    "Ben Sizer" <> writes:
    > Documentation is often a problem with Python and its libraries, sadly.
    > The same almost certainly goes for most open source projects.


    You over-specified the last clause. It should say "most software
    projects."

    <mike
    --
    Mike Meyer <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
    Mike Meyer, Oct 28, 2005
    #3
  4. Mike Meyer <> wrote:

    > "Ben Sizer" <> writes:
    > > Documentation is often a problem with Python and its libraries, sadly.
    > > The same almost certainly goes for most open source projects.

    >
    > You over-specified the last clause. It should say "most software
    > projects."


    You over-specified the last clause. It should say "most projects."


    Alex
    Alex Martelli, Oct 29, 2005
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. dna
    Replies:
    0
    Views:
    1,149
  2. Martin Meier

    opaque - Bedeutung ?

    Martin Meier, Sep 10, 2004, in forum: Java
    Replies:
    3
    Views:
    1,393
    Eric Sosman
    Sep 10, 2004
  3. Brian Tozer

    Semi-opaque colored background

    Brian Tozer, Feb 8, 2004, in forum: HTML
    Replies:
    11
    Views:
    4,780
    Steve Pugh
    Feb 9, 2004
  4. Beauregard T. Shagnasty

    IE hides inline images with opaque background

    Beauregard T. Shagnasty, Dec 31, 2004, in forum: HTML
    Replies:
    13
    Views:
    889
  5. Ellarco
    Replies:
    12
    Views:
    594
    Jerry Coffin
    Oct 3, 2003
Loading...

Share This Page