My Title

 tag?  For example:

def run(server_class=BaseHTTPServer.HTTPServer,
        handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

(Cut'n'paste from the Python library reference as displayed by KDE KFM)
If a Browser (MS IE 5.0) would display this, it is definitely broken.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)

From dgoodger@bigfoot.com  Sat Jun 16 23:17:28 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Sat, 16 Jun 2001 18:17:28 -0400
Subject: [Doc-SIG] Re:HTML TT tag not preserving whitespace
In-Reply-To: 
Message-ID: 

on 2001-06-16 2:13 PM, Peter Funk (pf@artcom-gmbh.de) wrote:
> May be I've missed the point, but was wrong with the  tag?  For example:

We're talking about inline literal markup like , not literal blocks like
. This applies with text like::

    There are three spaces in x after x = '   '.

Guido was saying that would need at least one   to come out right.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From dgoodger@bigfoot.com  Sun Jun 17 03:50:49 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Sat, 16 Jun 2001 22:50:49 -0400
Subject: [Doc-SIG] Proposal for indented sections in reStructuredText
In-Reply-To: 
Message-ID: 

on 2001-06-15 2:10 AM, Peter Funk (pf@artcom-gmbh.de) wrote:
> If restructured text limits itself to at most two levels, using '=' as
> a underline character for top level headings und '-' as a underline
> character for nested section headings is okay.
> 
> But IMO the different over- und underlining styles and the automatic
> recognition of styles described in your proposal is way too much freedom
> for writers.  This seems unpythonic to me.  At least for Python doc-strings
> the title style to be used should be restricted.

I want to keep reStructuredText -- the syntax markup spec -- completely
separate from the the conventions or limits imposed by Python docstrings.
Saying that any aspect of reStructuredText is "pythonic" or "unpythonic" is
a disservice. reStructuredText stands on its own, usage-neutral. I'd like to
think that reStructuredText (or any markup syntax) could be applied in a
variety of domains, just as I would defend the use of XML, POD, JavaDoc, or
TeX as perfectly valid syntaxes in Python docstrings (don't ask me to use
them though). Whether the biases or familiarities which attract individuals
to Python also attract them to a certain docstring markup syntax... ;-)

Having said that (let me switch perspectives here), if the docstring
conventions were to specify a subset of reStructuredText, that would be
fine.

And yes, I know that I am guilty of conflict of interest regarding
reStructuredText and the Docstring Processing System projects. I'm guilty of
making decisions for reStructuredText based on "pythonic" criteria, of
trying to appeal to the Python community and its final arbiter. Perhaps I
should clean up my act and remove all inter-project contamination? Nah.

Sometimes I take all of this too seriously.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From dgoodger@bigfoot.com  Sun Jun 17 04:07:32 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Sat, 16 Jun 2001 23:07:32 -0400
Subject: [Doc-SIG] A couple quick comments
In-Reply-To: <200106161221.f5GCLJm21541@gradient.cis.upenn.edu>
Message-ID: 

on 2001-06-16 8:21 AM, Edward D. Loper (edloper@gradient.cis.upenn.edu)
wrote:
> 1. I think we should try to concentrate on building a markup
> language for docstrings.  I think that trying to create a
> general-purpose markup language, which is simple and easy and
> wonderful etc., is going to be too hard of a project.  We'll make
> more progress if we just try to concentrate on docstrings.

I personally am aiming for the general-purpose solution. I'd encourage you
or anyone to pursue a docstring-specific variant or alternative. Whatever
gets us there faster.

Perhaps I'll change my tune once I've completed a few more hundred lines of
code.

> 3. I think we should try to direct some energy at figuring out the
> details of the DPS.

Yes please! There are lots of "XXX" bits in PEP 258.

> If we're to accept David's proposed
> approach, then markup decisions should be made pretty far down
> the road: first we create the DPS, then we construct a number of
> actual markups, so we can play with them and try them out, and
> *then* we'll have more experience with which to make decisions
> about which markup features we want.

I prefer the Extreme Programming "continuous evolution" approach to design.
I don't know what the DPS needs until I tackle each side of each API. I do
welcome the advice of others with experience.

In other words, not having a complete PEP 258 won't hinder me from writing
an input parser. I personally won't be able to fill in some of the "XXX"
bits until I've got at least a partial solution in place.

Thanks.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From tony@lsl.co.uk  Mon Jun 18 10:12:09 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 18 Jun 2001 10:12:09 +0100
Subject: [Doc-SIG] Documentation markup & processing / PEPs
In-Reply-To: 
Message-ID: <001701c0f7d6$c0f55720$f05aa8c0@lslp7o.int.lsl.co.uk>

David Goodger wrote:
> Note that "is not guaranteed" is written, on purpose,
> specifically to cover cases of output formats that can't
> preserve whitespace.

...elucidation of how HTML works...

But what I wanted was the formatter to generate appropriate   tags
for me.

> I'll amend the spec along the lines of "although every
> attempt to preserve whitespace will be made, it is not
> guaranteed to be preserved," and specifically mention
> HTML's TT behavior.

Gosh, coming from (amongst other things) a TeX background, it always
makes go *cringe* when HTML is used as a description of formatting (yes,
I know, I know).

Anyway, what I (that is, me - I can't guarantee anyone else)
*specifically* want is two things:

1. Ability to have inline literals with the 'correct' number of spaces
(which is achievable to the "normal" standard in HTML with  , with
verbatim spaces in [La]TeX, and by other means in other presentation
media.

2. Ability to have a non-breaking space (which *seems* to work with
  in HTML - I haven't got a spec to hand, but "seems to work" does
appear to be the "normal" standard for HTML), and is ~ in [La]TeX, etc.

Of these, the second is the more important to me, and a folding of the
two into   for HTML and ~ for [La]TeX seems to be the easiest to do
(otherwise we need an escape mechanism for non-breaking spaces, which
I'd decrie). So if inline literals preserve spaces and can't span lines,
I would be happy (NB: it *should* be up to the presentation format what
it does with these, so the parser certainly shouldn't be dropping the
spaces, for inline literals at least).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

From tony@lsl.co.uk  Mon Jun 18 10:12:13 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 18 Jun 2001 10:12:13 +0100
Subject: [Doc-SIG] A couple quick comments
In-Reply-To: <200106161344.JAA02272@cj20424-a.reston1.va.home.com>
Message-ID: <001801c0f7d6$c3030170$f05aa8c0@lslp7o.int.lsl.co.uk>

Guido van Rossum wrote (in response to Edward Loper):
> >   4. I don't see a good reason to specify the interfaces
> >   used between DPS pieces using DOM.  Using/manipulating
> >   DOM can be much more of a pain than using/manipulating
> >   Python objects.
>
> Agreed!  The DOM is a painful standard and unless there are external
> reasons to use it, I'd rather use Python the way I intended it. :-)

Certainly using Python directly would be nicer (heh, that's a given),
although I don't think I find that bit of the XML world as painful as
Guido.

I'd not grumble if DOM "intermediary" was not required. My initial
reason for wanting the DOM in place was because I thought we might have
multiple back/fore-ends developed indendependently. This seems less
important now we have a centralised set of PEPs to work around. Given
the agreement above, I would go for dropping it as an intermediary form.

Of course, there's still the problem of working out the API, in that
case...

The DTDs or some other formalism are still a useful thing to have
around, I think, and it may well *be* useful to be able to produce DOM
for other purposes.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

From dgoodger@bigfoot.com  Tue Jun 19 05:14:05 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Tue, 19 Jun 2001 00:14:05 -0400
Subject: [Doc-SIG] The Rise and Fall of Indented Sections
Message-ID: 

Following two impassioned arguments [1]_ on the Doc-SIG against
abolishing indentation for section structure, I reconsidered my
arguments and posted a comporomise `Proposal for indented sections in
reStructuredText`_.

.. [1] One from `Wolfgang Lipp`_ and one from `Edward Welbourne`_.

.. Wolfgang Lipp:
   http://mail.python.org/pipermail/doc-sig/2001-June/001872.html
.. Edward Welbourne:
   http://mail.python.org/pipermail/doc-sig/2001-June/001877.html
.. Proposal for indented sections in reStructuredText:
   http://mail.python.org/pipermail/doc-sig/2001-June/001890.html

Response from most of the pro-indentation camp was positive. `Guido
van Rossum`_ was against section-indentation, citing 30+ centuries of
tradition, reinforcing my original arguments, and invoking "there's
only one way to do it." As Dictator and chief arbiter of Python
morals, Guido's opinions are always influential. But the most
convincing arguments came from a surprising source: `Ken Manheimer`_,
a once-stalwart proponent of indented sections, made a strong case
*against* their continued use. He still likes them, finds them easier
to read, but concedes that they can be hard to write. He'll miss them.

You've got to admire that kind of objectivity.

.. Guido van Rossum:
   http://mail.python.org/pipermail/doc-sig/2001-June/001893.html
.. Ken Manheimer:
   http://mail.python.org/pipermail/doc-sig/2001-June/001901.html

Convinced by Guido's and Ken's arguments, in the wee hours of Friday,
June 15, I put out a call for final arguments in favor of indented
sections. Some attempts were made, but we knew the cause was lost. It
is my sad duty to report the tragic demise of indented sections in
reStructuredText.

Indented sections are dead! Long live reStructuredText!

In Memoriam
-----------

Born June 12, died June 18. It had a brief but exciting life.
Requiescat In Pace.

For the sake of posterity, the text removed from the spec regarding
indented sections is included below.

Removed from `Problems With StructuredText`_, version 0.2.1, end of
section 3:

    However, indented sections are dear to many users of
    StructuredText. reStructuredText recognizes the value of indented
    sections by also allowing entire section bodies to be indented
    relative to the title. Title adornment (an underline and possibly
    an overline) is still required, as is overall consistency. Once a
    section is indented, all subsections must also be indented
    relative to their titles. Title adornment style usage must remain
    consistent.

.. Problems With StructuredText:
   http://structuredtext.sf.net/spec/problems.txt

Removed from `reStructuredText Markup Specification`_, version 0.2.1,
'Section Structure', end of first paragraph:

    A section may optionally be indented relative to its enclosing
    block. Once a section is indented, all of its subsections must be
    further indented.

End of second paragraph:

    With indented sections, adornment styles may be reused.

.. reStructuredText Markup Specification:
   http://structuredtext.sf.net/spec/reStructuredText.txt

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From rternosk@appliedtheory.com  Tue Jun 19 15:44:38 2001
From: rternosk@appliedtheory.com (Robert Ternosky)
Date: Tue, 19 Jun 2001 10:44:38 -0400
Subject: [Doc-SIG] PDF/PS problems with tableiii from python.sty
Message-ID: <200106191444.f5JEicI10119@bearcat.appliedtheory.com>

I'm converting some of LaTeX docs I've written to using the
python-docs texinputs. Things have been going great until
I started re-doing tables. I want to use the \tableiii and \lineiii
macros to replace this:

\begin{table}[h]
       \begin{tabular}{|l|l|l|}
         \hline
         $\strong{Party}$&$\strong{Obligations}$&$\strong{Benefits}$\\
         \hline
         Client   & Satisfy Precondition:  & From Postcondition: \\
                  & Call 'put' on a        & stack is updated: is not \\
                  & non-full stack only    & empty, x on top (item yields \\
                  &                        & x), count increased by 1 \\
         \hline
         Supplier & Satisfy Postcondition: & From Precondition: \\
                  & Update stack to have x & Simpler processing thanks \\
                  & on top (item yields x) & to the assumption that \\
                  & count increased by 1,  & stack is not full \\
                  & not empty.             & \\
         \hline
       \end{tabular}
       \caption{Obligation and Benefits of put routine}
\end{table}

with this:

    \begin{tableiii}{|l|l|l|}{code}{Party}{Obligations}{Benefits}
      \lineiii{Client}
        {Satisfy Precondition: \\ Only call put on a non-full stack.}
        {From Postcondition: \\ stack is updated: it's not empty, \\
         x is on top (item yields x), \\ count increased by 1}
      \lineiii{Supplier}
        {Satisfy Postcondition: \\ Update stack to have x on top \\
         (item yields x), count increased by 1, \\ stack not empty.}
        {From Precondition: \\ Simpler processing thanks to the \\
         assumption that stack is not full.}
      \label{tab:putMethod}
    \end{tableiii}

I also tried removing the '\\' markers so that the 2nd and 3rd args to \lineiii
we're one long string. In both cases the table is unreadable in the
Postscript and PDF versions, but the HTML comes out perfect.

Am I mis-using this? The problem seems to arise due to the multi-line nature
of the 2nd and 3rd arguments to \lineiii. 

Can I not use the macros in this case? 
Any suggestions?
--------
Bob Ternosky
rternosk@appliedtheory.com
AppliedTheory Corporation

From sam@ddmweb.com  Tue Jun 19 17:30:01 2001
From: sam@ddmweb.com (Sam Penrose)
Date: Tue, 19 Jun 2001 09:30:01 -0700
Subject: [Doc-SIG] Re: PEP 257: Docstring Conventions
In-Reply-To: 
References: 
Message-ID: <01061910135400.04347@frock.ddmweb.com>

Sorry for the delay in getting back to you; I was on vacation.

My mistake on the purpose of 257.

What is readable depends in on context. I think Guido's
Style Guide is basically great but too specific in some ways and not
specific enough in others to use as a spec. The Guide mashes together
commentary which, when made a spec, is appropriate for differing
contexts:

1) The minimum necessary for cross-platform and cross-editor
development.

2) Additional layers and conventions important for those contributing
to Python release code so that they can work together.

3) What Guido thinks looks good; the "for symetry" comment I singled
is one example; "The closing quotes are on the same line as the opening
quotes. This looks better for one-liners" is another. While I happen to
agree with this and follow it, I don't think it belongs in a
specification (as opposed to a Style Guide). I am a little uncomfortable
with your comment that "the DPS will know about some of the
conventions, so following them will get you the best results." "Getting
the best results" has the sound of "a little bit pregnant" to me, as do
some of your other phrases. What is style and what is spec?

4) To be crystal clear: I would like to see a clear line between which
standards can be violated at the cost of dirty looks and which will
cause DSP code to fail, and I'd like to see some of the current PEP
contents explicitly moved to the first category.

this-opinion-is-worth-what-you-paid-for-it-ly,
S

On Thu, 14 Jun 2001, you wrote:
> on 2001-06-13 4:45 PM, Sam Penrose (sam@ddmweb.com) wrote:
> >>>> This is a PEP-ification of part of Guido van Rossum's Python Style
> > Guide ... <<<
> > 
> > parts of the Style Guide weather the conversion to a specification
> > better than others. For example...
> [omitted]
> > .... seems a bit visually oriented for the purpose of making
> > docstrings machine-parseable.
> 
> Making docstrings machine-parsable is not the point of PEP 257, nor of the
> Style Guide from which it sprang. The point is to standardize the high-level
> structure of docstrings: what should they contain, and how to say it
> (without touching on any markup syntax within docstrings). Docstring spacing
> is one of the conventions that make Python code readable, IMHO. The
> Docstring Processing System is made up of layers of specs. PEP 257 is the
> highest-level, semantic part.
> 
> The PEP contains conventions, not laws or syntax. If you violate the
> conventions, the worst you'll get is some dirty looks. But the DPS will know
> about some of the conventions, so following them will get you the best
> results.
> 
> BTW, what's wrong with that specific convention?
> 
> -- 
> David Goodger    dgoodger@bigfoot.com    Open-source projects:
>  - Python Docstring Processing System: http://docstring.sf.net
>  - reStructuredText: http://structuredtext.sf.net
>  - The Go Tools Project: http://gotools.sf.net

From castor@snafu.de  Wed Jun 20 12:53:01 2001
From: castor@snafu.de (castor@snafu.de)
Date: Wed, 20 Jun 2001 11:53:01 MET
Subject: [Doc-SIG] Implicit Link Targets
Message-ID: 

Reading the `specification docs`_ once more, I realized it
might be pretty desirable to have implicit link targets. More
specifically, I suggest that titles of sections like

	Section Titles
	==============

as well as figure captions

	A figure (a graphic with a caption) could be placed like this::     

		.. figure:: larch.png        

		The larch.

could be made available as implicit link targets (I'm not
quite sure whether figure captions are actually recognized as
a distinct element in the spec; I'd have to check that).

Since "Whitespace is normalized within hyperlink names, which
are case-insensitive", authors can then refer to `section
titles`_ and `the larch`_. It might be desirable to issue
warnings in case non-unique titles/captions are actually
referred to within the text.

Implicit targets could be supplemented/overridden by explicit
targets; their use would obliterate the need for most explicit
targets seen in a text like the specification itself.

Is that desirable/implementable?

-wolf

. _specification docs: http://structuredtext.sourceforge.net/

From tony@lsl.co.uk  Wed Jun 20 11:09:53 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 20 Jun 2001 11:09:53 +0100
Subject: [Doc-SIG] Implicit Link Targets
In-Reply-To: 
Message-ID: <000201c0f971$260a16f0$f05aa8c0@lslp7o.int.lsl.co.uk>

castor@snafu.de (what a nice name) wrote:
> Reading the `specification docs`_ once more, I realized it
> might be pretty desirable to have implicit link targets. More
> specifically, I suggest that titles of sections like
>
> 	Section Titles
> 	==============
>
> as well as figure captions
...deletia...
> Is that desirable/implementable?

The obvious problem is that of any such scheme, which is the difficulty
of preserving unambiguity. There are contexts where one is required (by
some external fiat or other) to write documents with a structure like:

	Section 1
	---------

	Introduction
	~~~~~~~~~~~~

	blah blah

	Details
	~~~~~~~

	blah blah

	Section 2
	---------

	Introduction
	~~~~~~~~~~~~

	blah blah

and so on (I'm sure you get the idea). It becomes impossible to indicate
a particular "Introduction" unambiguously without a more complex scheme
(for instance, having to specify `Section 1//Introduction`_ - this way
lies XPath) and given that the document owner (presumably) knows when
they want labels, it's easier for them to just put them in where they're
actually needed.

There's also, then, the "side benefit" that one can see *what* is being
referenced from elsewhere (heh, a "ComeFrom" statement!) - although this
is not something I've ever particularly made conscious use of.

The advantage of David's original idea is that it is both simple and
globally used.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
In Python it's clearer to talk about "names" and "bindings"
rather than "variables" and "values". (Greg Ewing)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

From dgoodger@bigfoot.com  Thu Jun 21 04:27:54 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Wed, 20 Jun 2001 23:27:54 -0400
Subject: [Doc-SIG] Re: PEP 257: Docstring Conventions
In-Reply-To: <01061910135400.04347@frock.ddmweb.com>
Message-ID: 

on 2001-06-19 12:30 PM, Sam Penrose (sam@ddmweb.com) wrote:
> What is readable depends in on context. I think Guido's
> Style Guide is basically great but too specific in some ways and not
> specific enough in others to use as a spec. The Guide mashes together
> commentary which, when made a spec, is appropriate for differing
> contexts:
...
> What is style and what is spec?
> 
> 4) To be crystal clear: I would like to see a clear line between which
> standards can be violated at the cost of dirty looks and which will
> cause DSP code to fail, and I'd like to see some of the current PEP
> contents explicitly moved to the first category.

These are valid points. I will work on making changes to the PEP. Any help
you (or anyone) could give, such as specific "this is style and that is
spec", or complete rewrites ;-) would be very welcome and helpful.

> this-opinion-is-worth-what-you-paid-for-it-ly,

Far, FAR more, to be sure. Thank you.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From dgoodger@bigfoot.com  Thu Jun 21 05:01:46 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Thu, 21 Jun 2001 00:01:46 -0400
Subject: [Doc-SIG] Implicit Link Targets
In-Reply-To: 
Message-ID: 

on 2001-06-20 7:53 AM, castor@snafu.de (castor@snafu.de) wrote:
> Reading the `specification docs`_ once more, I realized it
> might be pretty desirable to have implicit link targets.

Having implicit link targets for titles is a good idea. Note that the
'figure' directive was just an example, and isn't an 'official' part of the
spec.

> It might be desirable to issue
> warnings in case non-unique titles/captions are actually
> referred to within the text.
> 
> Implicit targets could be supplemented/overridden by explicit
> targets; their use would obliterate the need for most explicit
> targets seen in a text like the specification itself.
> 
> Is that desirable/implementable?

Yes, just as you specify. I spent a few minutes coming up with some simple
rules:

1. Keep track of implicit & explicit links in separate dictionaries.

2. In case of:

   - duplicate explicit & implicit targets: priority to explicit
   - duplicate implicit targets: disable all of them, don't warn
   - duplicate explicit targets: warn & diable all of them

   'Disable' means to remove link names from targets. System warning
   elements can be inserted where target links are disabled.

The DPS won't care whether links are implicit or explicit. The parser must
deliver a set of *unique* target links (as attributes on elements). The DPS
can warn of unresolvable links, even giving reasons for the warnings.

It will certainly make cross-reference-rich documents (like the spec :-)
easier to read, and won't detract from understandability. "See 'Details'
below" is a very common prose idiom, the literary hyperlink exactly. Just so
long as there's a zero-tolerance policy on implicit hyperlink ambiguity in
place, I don't see why it can't fly.

Does this allay your misgivings, Tony?

Thanks, Wolf.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From dgoodger@bigfoot.com  Thu Jun 21 05:14:55 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Thu, 21 Jun 2001 00:14:55 -0400
Subject: [Doc-SIG] Documentation markup & processing / PEPs
In-Reply-To: <001701c0f7d6$c0f55720$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: 

on 2001-06-18 5:12 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote:
> Anyway, what I (that is, me - I can't guarantee anyone else)
> *specifically* want is two things:
> 
> 1. Ability to have inline literals with the 'correct' number of spaces
... 
> 2. Ability to have a non-breaking space

In what contexts do you need a non-breaking space? One area reStructuredText
doesn't touch is character sets or (SG|HT|X)ML-character-entity-equivalents.
  can be considered part of markup or of character sets/entities.
Suggestions?

One point: I believe some time ago you thought that you could get away with
using inline literals for non-breaking spaces::

    no`` ``break

(At the time the markup was single-backquotes, not double as above.) That's
not supported by the spec, since the start-strings and end-strings aren't in
the proper context; reversed contexts, in fact.

> So if inline literals preserve spaces and can't span lines,
> I would be happy

Inline anything is part of the flow of the paragraph, and thus should be
able to flow right along with the rest of the paragraph text. I can see
satisfying 'preserve spaces', but inline literals *may* span lines.

> (NB: it *should* be up to the presentation format what
> it does with these, so the parser certainly shouldn't be dropping the
> spaces, for inline literals at least).

Agreed.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net

From tony@lsl.co.uk  Thu Jun 21 10:39:52 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 21 Jun 2001 10:39:52 +0100
Subject: [Doc-SIG] Documentation markup & processing / PEPs
In-Reply-To: 
Message-ID: <000901c0fa36$1f76c7f0$f05aa8c0@lslp7o.int.lsl.co.uk>

David Goodger wrote:
> In what contexts do you need a non-breaking space?

Hmm. As always, I don't have a proper example to hand. Strings are
always an obvious example (although such are, of course, most likely to
occur in block literals, where spaces *are* preserved).

If one has tables, then something like:

	+-----------+---------+
	| String    | Meaning |
	+===========+=========+
	| `"  x "`  | One     |
      | `" x  "`  | Two     |
	+-----------+---------+

(yes, I know that's doubtless "drawn" wrongly) might be an example - the
number of spaces is plainly being used significantly, and this *is* the
sort of thing one might want to do in a doc string.

> One area reStructuredText doesn't touch is character sets or
> (SG|HT|X)ML-character-entity-equivalents.
>   can be considered part of markup or of character sets/entities.
> Suggestions?

Hmm - I would be against introducing XML character entities (for two
reasons - firstly because we don't want to be tied to XML, and secondly
because if people see *one* XML-ism, then they may assume others
"work"). Oh, and thirdly because they break the "the bare text should be
readable" principle of StructuredText, which is STILL the most important
reason for going this route.

> One point: I believe some time ago you thought that you could
> get away with using inline literals for non-breaking spaces::
>
>     no`` ``break

Yes - I rather liked that, but as I recall Guido said it was a nasty
trick he didn't like. Ho hum (and, as you say, it doesn't work in your
current scheme, nor would it have worked in the earlier scheme).

To clarify - I can probably put up with not having non-breaking spaces
in "ordinary" text (although I say that reluctantly, because I feel
they're useful - but then we're not trying for an all powerful
typesetting system), but I feel that we really *do* need them in literal
text.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

From tony@lsl.co.uk  Thu Jun 21 10:41:00 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 21 Jun 2001 10:41:00 +0100
Subject: [Doc-SIG] Implicit Link Targets
In-Reply-To: 
Message-ID: <000a01c0fa36$47810670$f05aa8c0@lslp7o.int.lsl.co.uk>

David Goodger wrote:
...an explanation of how he proposed to make implicit links work...
> Does this allay your misgivings, Tony?

I think so. It's not something I'm *too* worried about (!) - since my
main concern is doc-strings, which don't normally have much sectional
structure, it's something I'm willing to let flow and develop itself, to
some extent. As you say, cross-reference rich documents will be simpler
to read (as text) with this scheme, which is a Good Thing given the
StructuredText principle of "the bare text must be readable".

(btw - the sort of overly formal document structure I was mentioning
last time is a pain for all sorts of reason, anyway, so I hope one
doesn't have to write too many of them).

I *am* glad you're not trying to support "scoping" (i.e., if I reference
"introduction" in *this* section, and there's an "introduction" in
another section, the one in this section gets chosen) since I think this
would make the scheme over-complex.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

From fdrake@beowolf.digicool.com  Fri Jun 22 19:31:44 2001
From: fdrake@beowolf.digicool.com (Fred Drake)
Date: Fri, 22 Jun 2001 14:31:44 -0400 (EDT)
Subject: [Doc-SIG] [maintenance doc updates]
Message-ID: <20010622183144.C6A5428927@beowolf.digicool.com>

The development version of the documentation has been updated:

	http://python.sourceforge.net/maint-docs/

Lots of smallish updates and corrections, moved the license statements to
an appendix.

From fdrake@beowolf.digicool.com  Fri Jun 22 19:53:37 2001
From: fdrake@beowolf.digicool.com (Fred Drake)
Date: Fri, 22 Jun 2001 14:53:37 -0400 (EDT)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20010622185337.BE51228927@beowolf.digicool.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Lots of smallish updates and corrections, moved the license statements to
an appendix.

This version includes some contributed changes to the documentation for the
cmath module.  To make the LaTeX to HTML conversion work, I have made the
resulting HTML contain entity references for the "plus/minus" and "infinity"
symbols (± and ∞, respectively).  These may be problematic for
some browsers.  Please let me know how it looks on your browser by sending
an email to python-docs@python.org.  Be sure to state your browser name and
version, and what operating system you are using.  Thanks!

  http://python.sourceforge.net/devel-docs/lib/module-cmath.html

From fdrake@acm.org  Fri Jun 22 21:29:28 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 22 Jun 2001 16:29:28 -0400 (EDT)
Subject: [Doc-SIG] Browsers & the Python documentation
Message-ID: <15155.43688.608790.42183@cj42289-a.reston1.va.home.com>

  Ok, between a few responses I've received from my query about
browser support for ± and ∞, and the browsers I happen to
have installed, here's what I've found:

Browser    |   Version   |  O/S  | ± | ∞
-----------|-------------|-------|----------|--------
Mozilla    |  0.9, 0.9.1 | Linux |    ok    |    ok
Navigator  |  4.76, 4.77 | Linux |    ok    |   no!
Opera      |         5.0 | Linux |    ok    |   no!
Amaya      |       4.3.2 | Linux |    ok    |    ok
Konqueror  |       1.9.8 | Linux |    ok    |   no!
StarOffice |         5.2 | Linux |    ok    |   no!
gnome-help |         0.4 | Linux |    ok    |   no!  (but it sucks anyway)
Lynx       |  2.8.4dev.8 | Linux |    ok    |   no!
Links      |        0.92 | Linux |   kinda  |   no!
-----------|-------------|-------|----------|--------
MSIE       |         5.5 |Win98SE|    ok    |    ok
-----------|-------------|-------|----------|--------
MSIE       | 6.0 preview | Win2K |    ok    |    ok
Mozilla    |         0.9 | Win2K |    ok    |    ok
Navigator  |         6.0 | Win2K |    ok    |    ok
Opera      |        5.11 | Win2K |    ok    |   no!

  I'd love to hear about browsers on Mac OS as well!

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations

From fdrake@beowolf.digicool.com  Fri Jun 22 21:52:48 2001
From: fdrake@beowolf.digicool.com (Fred Drake)
Date: Fri, 22 Jun 2001 16:52:48 -0400 (EDT)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20010622205248.6290128927@beowolf.digicool.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Changed the revised cmath documentation to use "j" as a suffix for complex
literals instead of using "i" as a prefix; this is more similar to Python.
Changed the font of the suffix to match that used elsewhere in the
documentation.

This should be a little more readable, but does not change any potential
browser compatibility issues, so I still need reports of compatibility or
non-compatibility.  See my prelimiary report on the topic at:

    http://mail.python.org/pipermail/doc-sig/2001-June/001940.html

From mwh@python.net  Sat Jun 23 10:16:58 2001
From: mwh@python.net (Michael Hudson)
Date: 23 Jun 2001 10:16:58 +0100
Subject: [Doc-SIG] Browsers & the Python documentation
In-Reply-To: "Fred L. Drake, Jr."'s message of "Fri, 22 Jun 2001 16:29:28 -0400 (EDT)"
References: <15155.43688.608790.42183@cj42289-a.reston1.va.home.com>
Message-ID: 

"Fred L. Drake, Jr."  writes:

>   Ok, between a few responses I've received from my query about
> browser support for ± and ∞, and the browsers I happen to
> have installed, here's what I've found:
> 
> 
> Browser    |   Version   |  O/S  | ± | ∞
> -----------|-------------|-------|----------|--------
> Mozilla    |  0.9, 0.9.1 | Linux |    ok    |    ok
> Navigator  |  4.76, 4.77 | Linux |    ok    |   no!
> Opera      |         5.0 | Linux |    ok    |   no!
> Amaya      |       4.3.2 | Linux |    ok    |    ok
> Konqueror  |       1.9.8 | Linux |    ok    |   no!
> StarOffice |         5.2 | Linux |    ok    |   no!
> gnome-help |         0.4 | Linux |    ok    |   no!  (but it sucks anyway)
> Lynx       |  2.8.4dev.8 | Linux |    ok    |   no!
> Links      |        0.92 | Linux |   kinda  |   no!

  w3m        |       0.1.6 | Linux |    ok    |   no

Is there an infinity symbol in iso-8859-1?  That would make it tricky
for text-mode browsers at the moment...

Cheers,
M.

-- 
    . <- the point                                your article -> .
    |------------------------- a long way ------------------------|
                                        -- Cristophe Rhodes, ucam.chat

From tim.one@home.com  Sat Jun 23 10:25:55 2001
From: tim.one@home.com (Tim Peters)
Date: Sat, 23 Jun 2001 05:25:55 -0400
Subject: [Doc-SIG] Browsers & the Python documentation
In-Reply-To: 
Message-ID: 

[Michael Hudson]
> Is there an infinity symbol in iso-8859-1?  That would make it tricky
> for text-mode browsers at the moment...

oo - oo == NaN.  Especially at 5 in the morning, two little "o"s juxtaposed look
more like infinity than God Himself .

From dgoodger@bigfoot.com  Sat Jun 23 14:49:49 2001
From: dgoodger@bigfoot.com (David Goodger)
Date: Sat, 23 Jun 2001 09:49:49 -0400
Subject: [Doc-SIG] Browsers & the Python documentation
In-Reply-To: <15155.43688.608790.42183@cj42289-a.reston1.va.home.com>
Message-ID: 

Browser    |   Version   |  O/S  | ± | ∞
-----------|-------------|-------|----------|--------
MSIE       |         5.0 | MacOS*|    ok    |    ok
Navigator  |        4.72 | MacOS*|    ok    |    no

* MacOS 8.6

From fdrake@beowolf.digicool.com  Sun Jun 24 03:41:04 2001
From: fdrake@beowolf.digicool.com (Fred Drake)
Date: Sat, 23 Jun 2001 22:41:04 -0400 (EDT)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20010624024104.A757728927@beowolf.digicool.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

A couple of small updates, including spelling the keywords correctly in
the language reference.

This version brings back the hyperlinked grammar productions I played
around with earlier.  They still need work, but they are somewhat better
than plain text.

From summer@ourobourus.com  Wed Jun 27 09:11:51 2001
From: summer@ourobourus.com (Mark Summerfield)
Date: Wed, 27 Jun 2001 10:11:51 +0200
Subject: [Doc-SIG] Announce: RTX 1.0.0 yet another plain-text-ish markup
Message-ID: <01062710115144.28534@sylkie>

Hi,

If you're interested in plain text-ish markup you might find RTX of
interest: http://www.ourobourus.com

It is vaguely reminiscent of doxygen since it takes lots of ideas from
qdoc (of which doxygen is a public implementation).

Basically you can write with a minimally intrusive markup and produce
HTML, SGML (docbook), Lout (which generates postscript and PDF) and
plain text. It handles lists and tables as well as 'categorising'
markup, e.g. \key Alt+F. It does not support much 'formatting' markup,
e.g. fonts etc. in the text itself, but you have considerable control
over how the output works in the supported formats (so you can control
fonts, colours etc. globally for consistency by changing simple
configuration files). It is quite easy to subclass to produce your own
format (it's all written in pure Python).

I don't use it to markup Python code, at least not yet, but doing so
should be straightforward. Below are some notes on this possibility
(but extracting marked up text from Python code isn't supported yet --
but hopefully will be soon).

Here's how a fragment of David Goodger's documentation looks using
his reStructuredText:

    def __init__(self, stateclasses, initialstate, debug=0):
        """
        Initialize a `StateMachine` object; add state objects.

        Parameters:

        - `stateclasses`: a list of `State` (sub)classes.
        - `initialstate: a string, the name of the initial state (class 
name).
        - `debug`: a boolean; produce verbose output if true (nonzero).
        """

here's how you'd achieve the same thing using RTX (only I wouldn't do
this; see the final example):

    def __init__(self, stateclasses, initialstate, debug=0):
        """
        Initialize a \class StateMachine object; add state objects.

        Parameters:
	\list
        \e \p stateclasses a list of \class State (sub)classes.
        \e \p initialstate a string, the name of the initial state 
(class name).
        \e \p debug a boolean; produce verbose output if true (nonzero).
	\endlist
        """

The \e is a cell or list element, the \p is a parameter. (If you need
to group a phrase you'd do \b[bold phrase] -- yes bold and italic are
supported even though they aren't categorisation.)

The way I'd have written the thing is like this:

    def __init__(self, stateclasses, initialstate, debug=0):
        '''
        Initialize a \class StateMachine object; add state objects.

	The \p stateclasses is a list of \class State (sub)classes. The
	initial state (which is a class name) is in the \p
	initialstate string. If you want verbose output set \p debug
	to true (its default is false). 
        '''

If you wanted to do this you'd have to extract the text yourself and
then run it through RTX. I will make RTX capable of doing this itself
soon.

BTW I am not keen on defining the presentational structure within the
description itself. For me the presentation is a concern of the output
formatter and what I want to feed into that is categorisation, i.e.
this is a class name, this is a method name, etc.

-- 
Mark.

From fdrake@acm.org  Fri Jun 29 20:24:00 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 29 Jun 2001 15:24:00 -0400 (EDT)
Subject: [Doc-SIG] Python 2.1 docs in GNU info format
Message-ID: <15164.54736.838888.800048@cj42289-a.reston1.va.home.com>

  Milan Zamazal has contributed Python 2.1 documentation in GNU info
format.  It is available on python.org:

ftp://ftp.python.org/pub/python/doc/2.1/

and on SourceForge:

http://sourceforge.net/project/showfiles.php?group_id=5470&release_id=41415

  Thanks, Milan!

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations