Re: [Python-Dev] The docs, reloaded
On 5/24/07, Greg Ewing <[EMAIL PROTECTED]> wrote: > Talin wrote: > > As in the > > above example, the use of backticks can be signal to the document > > processor that the enclosed text should be examined for identifiers and > > other Python syntax. > > Does this mean it's time for "pyST" -- Python-structured > text?-) Not before someone writes it. Georg Brandl's awesome ReST based system has the nice property that it actually exists and works. For a great number of reasons it is superior to the existing LaTeX based system, and I hope and think that they are strong enough to replace LaTeX with it. -- mvh Björn ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded
On Wed, May 23, 2007 at 05:39:38AM -0500, [EMAIL PROTECTED] wrote: > Nick> If you type "pydoc re" at the moment then it says in it > > Nick> MODULE DOCS > Nick> http://www.python.org/doc/current/lib/module-re.html > > Nick> which is pretty much useless to me when ssh-ed in to a linux box > Nick> half way around the world... > > I get quite a bit of information about re (I've never known /F to be a > documentation slouch). Yes it is certainly better than no docs. It doesn't for instance have any regexp info, and I can never remember all the special non matching brackets (eg (?:...) so I have to read for the full docs for that. > Only one bit of that information is a reference to the page in the > library reference manual. And if I happen to be ssh'd into a > machine halfway round the world through a Gnome terminal I can right > mouse over that URL and pop the page up in my default local browser. > If you set the PYTHONDOCS environment variable you can point it to a > local (or at least different) copy of the libref manual. I take your point. However the unix tradition is that everything is in the man pages. man pages have expanded over the years to include info pages and you *can* read the full python docs via info, it just isn't quite as convenient as pydoc. I think perl had the right idea with perldoc. You can read all the perl documentation whether it is in module documentation (like docstrings) or general documentation (like the latex docs under discussion). I'd like to see pydoc be a viewer for all the python documentation, not just a subset of it. > A flag could be added to pydoc to show that content instead, however > being html it probably would be difficult to read unless pumped > through lynx -dump or something similar. I'm assuming that we do reST all the python documentation which would make it easier. -- Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded
On Wed, May 23, 2007 at 12:46:50PM -0500, Ron Adam wrote:
> Nick Craig-Wood wrote:
> >So I'll be able to read the main docs for a module in a terminal
> >without reaching for the web browser (or info)? That would be great!
> >
> >How would pydoc decide which bit of docs it is going to show?
>
> Pydoc currently gets topic info for some items by scraping the text from
> document 'local' web pages. This is kind of messy for a couple of reasons.
>- The documents may not be installed locally.
>- It can be problematic locating the docs even if they are installed.
>- They are not formatted well after they are retrieved.
>
> I think this is an area for improvement.
And it would be improved by converting the docs to reST I imagine.
> This feature is also limited to a small list where the word being searched
> for is a keyword, or a very common topic reference, *and* they are not
> likely to clash with other module, class, or function names.
>
> The introspection help parts of pydoc are completely separate from topic
> help parts. So replacing this part can be done without much trouble. What
> the best behavior is and how it should work would need to be discussed.
>
> Keep in mind doc strings are meant to be more of a quick reference to an
> item, and Pydoc is the interface for that.
I think that if reST was an acceptable form for the documentation, and
it could be auto included in the main docs from docstrings then you
would find more modules completely documented in __doc__.
> >If I type "pydoc re" is it going to give me the rather sparse __doc__
> >from the re module or the nice reST docs? Or maybe both, one after
> >the other? Or will I have to use a flag to dis-ambiguate?
>
> If retrieval from the full docs is desired, then it will probably need to
> be disambiguated in some way or be a separate interface.
>
>help('re')# Quick reference on 're'.
>helpdocs('re')# Full documentation for 're'.
Actually if it gave both sets of docs quick, then long, one after the
other that would suit me fine.
--
Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Adventures with x64, VS7 and VS8 on Windows
> -Original Message- > though, not cygwin (a la bsmedberg's new MozillaBuild stuff). I just > wish there were an autoconf alternative that wasn't as painful as > autoconf. I have a few attempts for my purposes that are written in > Python (an obvious bootstrapping problem for building Python itself :). > Only for the theorist. As you, we use build tools for our stackless branch written in python. There exist successfully built python versions back from the nineties, which can be considered "external" tools for all practical purposes. Building python with python is really nifty. Kristjan ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded
Nick Craig-Wood schrieb: >> > It is missing conversion of ``comment'' at the moment as I'm sure you >> > know... >> >> Sorry, what did you mean? > > ``comment'' produces smart quotes in latex if I remember correctly. > You probably want to convert it somehow because it looks a bit odd on > the web page as it stands. I'm not sure what the reST replacement > might be, but converting it just to "comment" would probably be OK. > Likewise with `comment' to 'comment'. > > For an example see the first paragraph here: > > http://pydoc.gbrandl.de/reference/index.html Okay, there's now support for SmartyPants in Subversion -- it converts these quotes as well as triple dashes to their pretty equivalents. cheers, Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded
Talin schrieb: > Martin Blais wrote: >> On 5/22/07, Martin Blais <[EMAIL PROTECTED]> wrote: >>> ReST works well only when there is little markup. Writing code >>> documentation generally requires a lot of markup, you want to make >>> variables, classes, functions, parameters, constants, etc.. (A better >>> avenue IMHO would be to augment docutils with some code to >>> automatically figure out the syntax of functions, parameters, classes, >>> etc., i.e., less markup, and if we do this in Python we may be able to >>> use introspection. This is a challenge, however, I don't know if it >>> can be done at all.) >> >> Just to follow-up on that idea: I don't think it would be very >> difficult to write a very small modification to docutils that >> interprets the default role with more "smarts", for example, you can >> all guess what the types of these are about: >> >> `class Foo` (this is a class Foo) >> `bar(a, b, c) -> str` (this is a function "bar" which returns a string) >> `name (attribute)` (this is an attribute) What's better here than :class:`Foo` or :attr:`name`? You wouldn't want to put an " (attribute)" after all references to it in your text, so this is just an alternative way to spell roles. >> ...so why couldn't the computer solve that problem for you? I'm sure >> we could make it happen. Essentially, what is missing from ReST is >> "less markup for documenting programs". By restricting the >> problem-set to Python programs, we can go a long way towards making >> much of this automatic, even without resorting to introspecting the >> source code that is being documented. > > I was going to suggest something similar. > > Ideally, any markup language ought to have a kind of "Huffman Coding" of > complexity - in other words, the markup symbols that are used the most > frequently are the ones that should be the shortest and easiest to type. > > Just as in real Huffman Coding, the popularity of a given element is > going to depend on context. This would imply that there should be > customizations of the markup language for different knowledge domains. > > While there are some benefits to having a 'standard' markup, any truly > universal markup is going to be much heavier and more cumbersome than > one that is specialized for the task. > > I would advocate a system in which the author inserts minimalistic > 'hints' into the text, and the document processor uses those hints along > with some automatic reasoning to determine the final markup. As in the > above example, the use of backticks can be signal to the document > processor that the enclosed text should be examined for identifiers and > other Python syntax. What I could propose is that we could abandon :class:`foo`, :meth:`foo` etc. and just use `foo`. There shouldn't be too many cases where this gets ambiguous crossreferencing. Variables would just use *var*, since they're not marked up speciall anyways. > I would also suggest that one test for evaluating the quality of markup > syntax is whether or not it can be learned by example - can a user > follow the pattern of some other part of the docs, without having to > learn the syntax in a formal way? I think he/she can, given a piece of document that contains most of the needed markup constructs. You'll pretty soon grok that reST uses indentation (and you'll be pleased with it if you like Python, which seems a reasonable assumption ;). You'll also get that :foo:`bar` is the syntax for semantic inline markup. Code examples are always introduced with a "::" (okay, the exact rules are a bit nifty, but very convenient if you know them). What else do you need to know? ".. function::" directives are quite easy to recognize. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded
Nick Craig-Wood wrote:
> On Wed, May 23, 2007 at 12:46:50PM -0500, Ron Adam wrote:
>> Nick Craig-Wood wrote:
>>> So I'll be able to read the main docs for a module in a terminal
>>> without reaching for the web browser (or info)? That would be great!
>>>
>>> How would pydoc decide which bit of docs it is going to show?
>> Pydoc currently gets topic info for some items by scraping the text from
>> document 'local' web pages. This is kind of messy for a couple of reasons.
>>- The documents may not be installed locally.
>>- It can be problematic locating the docs even if they are installed.
>>- They are not formatted well after they are retrieved.
>>
>> I think this is an area for improvement.
>
> And it would be improved by converting the docs to reST I imagine.
Yes, this will need a reST to html converter for displaying in the html
browser. DocUtils provides that, but it's not part of the library. (?)
And for console text output, is the unmodified reST suitable, or would it
be desired to modify it in some way?
Should a subset of the main documents be included with pydoc to avoid the
documents not available messages if they are not installed?
Or should the topics retrieval code be moved from pydoc to the main
document tools so it's installed with the documents. Then that can be
maintianed with the documents instead of being maintained with pydoc. Then
pydoc will just looks for it, instead of looking for the html pages.
>> This feature is also limited to a small list where the word being searched
>> for is a keyword, or a very common topic reference, *and* they are not
>> likely to clash with other module, class, or function names.
>>
>> The introspection help parts of pydoc are completely separate from topic
>> help parts. So replacing this part can be done without much trouble.
What
>> the best behavior is and how it should work would need to be discussed.
>>
>> Keep in mind doc strings are meant to be more of a quick reference to an
>> item, and Pydoc is the interface for that.
>
> I think that if reST was an acceptable form for the documentation, and
> it could be auto included in the main docs from docstrings then you
> would find more modules completely documented in __doc__.
That would be fine for third party modules if they want to do that or if
there is not much difference between the two.
>>> If I type "pydoc re" is it going to give me the rather sparse __doc__
>> >from the re module or the nice reST docs? Or maybe both, one after
>>> the other? Or will I have to use a flag to dis-ambiguate?
>> If retrieval from the full docs is desired, then it will probably need to
>> be disambiguated in some way or be a separate interface.
>>
>>help('re')# Quick reference on 're'.
>>helpdocs('re')# Full documentation for 're'.
>
> Actually if it gave both sets of docs quick, then long, one after the
> other that would suit me fine.
That may work well for the full documentation, but the quick reference
wouldn't be a short quick reference any more.
I'm attempting to have a pydoc api call that gets a single item or sub-item
and format it to a desired output so it can be included in other content.
That's makes it possible for the full docs (not necessarily pythons) to
embed pydoc output in it if it's desirable. This will need pydoc
formatters for the target document type. I hope to include a reST output
formatter for pydoc.
The help() function is imported from pydoc by site.py when you start
python. It may not be difficult to have it as a function that first tries
pydoc to get a request, and if the original request is returned unchanged,
tries to get information from the full documentation. There could be a way
to select one or the other, (or both).
But this feature doesn't need to be built into pydoc, or the full
documentation. They just need to be able to work together so things like
this are possible in an easy to write 4 or 5 line function. (give or take a
few lines)
So it looks like most of these issues are more a matter of how to organize
the interfaces. It turns out that what I've done with pydoc, and what
Georg is doing with the main documentation should work together quite nicely.
Cheers,
Ron
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded
Ron Adam schrieb: > Nick Craig-Wood wrote: > > On Wed, May 23, 2007 at 12:46:50PM -0500, Ron Adam wrote: > >> Nick Craig-Wood wrote: > >>> So I'll be able to read the main docs for a module in a terminal > >>> without reaching for the web browser (or info)? That would be great! > >>> > >>> How would pydoc decide which bit of docs it is going to show? > >> Pydoc currently gets topic info for some items by scraping the text from > >> document 'local' web pages. This is kind of messy for a couple of > reasons. > >>- The documents may not be installed locally. > >>- It can be problematic locating the docs even if they are installed. > >>- They are not formatted well after they are retrieved. > >> > >> I think this is an area for improvement. > > > > And it would be improved by converting the docs to reST I imagine. > > Yes, this will need a reST to html converter for displaying in the html > browser. DocUtils provides that, but it's not part of the library. (?) > > And for console text output, is the unmodified reST suitable, or would it > be desired to modify it in some way? A text writer for docutils should not be hard to write. You'd get something that looks like the reST, but stripped of markup that makes no sense when viewed on a terminal, such as :class:`xyz`. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded [PEP?]
This subject is generating a lot of discussion and [almost entirely] positive feedback. It would be a great shame to run out of steam. Does it need a PEP to see a chance of it getting accepted as the formal documentation system? (or a pronouncement that it will never happen...) Michael Foord Georg Brandl wrote: > Ron Adam schrieb: > >> Nick Craig-Wood wrote: >> > On Wed, May 23, 2007 at 12:46:50PM -0500, Ron Adam wrote: >> >> Nick Craig-Wood wrote: >> >>> So I'll be able to read the main docs for a module in a terminal >> >>> without reaching for the web browser (or info)? That would be great! >> >>> >> >>> How would pydoc decide which bit of docs it is going to show? >> >> Pydoc currently gets topic info for some items by scraping the text from >> >> document 'local' web pages. This is kind of messy for a couple of >> reasons. >> >>- The documents may not be installed locally. >> >>- It can be problematic locating the docs even if they are installed. >> >>- They are not formatted well after they are retrieved. >> >> >> >> I think this is an area for improvement. >> > >> > And it would be improved by converting the docs to reST I imagine. >> >> Yes, this will need a reST to html converter for displaying in the html >> browser. DocUtils provides that, but it's not part of the library. (?) >> >> And for console text output, is the unmodified reST suitable, or would it >> be desired to modify it in some way? >> > > A text writer for docutils should not be hard to write. You'd get something > that > looks like the reST, but stripped of markup that makes no sense when viewed on > a terminal, such as :class:`xyz`. > > Georg > > ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] The docs, reloaded [PEP?]
Michael Foord schrieb: > This subject is generating a lot of discussion and [almost entirely] > positive feedback. It would be a great shame to run out of steam. > > Does it need a PEP to see a chance of it getting accepted as the formal > documentation system? (or a pronouncement that it will never happen...) No. First of all, it needs a dedicated developer (preferably, but not necessarily a committer) who indicates willingness to maintain that for the coming years and releases. It might be that Fred Drake's offer to maintain the documentation would be still valid after such a switch, but we should not assume so without explicit confirmation. It might be that this would be the time to pass one documentation maintenance to somebody else (and I seriously do not have any one particular in mind here). Then, I think a should be made where the documentation is converted. Again, a volunteer would be needed to create the branch, and then eventually merge it back to the trunk. It might be helpful, but isn't strictly necessary, to close all documentation patches before doing so, as they all break with the conversion. For that activity, multiple volunteers would be useful. I don't think a formal document needs to be written, unless there is a hint of disagreement within the community. In that case, a process PEP would be necessary. However, it is much more important that the documentation maintainer explicitly agrees than that nobody explicitly disagrees, or that a pronouncement is made - the pronouncement alone will *not* cause this change to be carried out. Regards, Martin ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Wither PEP 335 (Overloadable Boolean Operators)?
On 5/18/07, Guido van Rossum <[EMAIL PROTECTED]> wrote: > While reviewing PEPs, I stumbled over PEP 335 ( Overloadable Boolean > Operators) by Greg Ewing. I am of two minds of this -- on the one > hand, it's been a long time without any working code or anything. OTOH > it might be quite useful to e.g. numpy folks. > > It is time to reject it due to lack of interest, or revive it! Last call for discussion! I'm tempted to reject this -- the ability to generate optimized code based on the shortcut semantics of and/or is pretty important to me. -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Wither PEP 335 (Overloadable Boolean Operators)?
Guido van Rossum wrote: > Last call for discussion! I'm tempted to reject this -- the ability to > generate optimized code based on the shortcut semantics of and/or is > pretty important to me. Please don't be hasty. I've had to think about this issue a bit. The conclusion I've come to is that there may be a small loss in the theoretical amount of optimization opportunity available, but not much. Furthermore, if you take into account some other improvements that can be made (which I'll explain below) the result is actually *better* than what 2.5 currently generates. For example, Python 2.5 currently compiles if a and b: into JUMP_IF_FALSE L1 POP_TOP JUMP_IF_FALSE L1 POP_TOP JUMP_FORWARD L2 L1: 15 POP_TOP L2: Under my PEP, without any other changes, this would become LOGICAL_AND_1 L1 LOGICAL_AND_2 L1: JUMP_IF_FALSE L2 POP_TOP JUMP_FORWARD L3 L2: 15 POP_TOP L3: The fastest path through this involves executing one extra bytecode. However, since we're not using JUMP_IF_FALSE to do the short-circuiting any more, there's no need for it to leave its operand on the stack. So let's redefine it and change its name to POP_JUMP_IF_FALSE. This allows us to get rid of all the POP_TOPs, plus the jump at the end of the statement body. Now we have LOGICAL_AND_1 L1 LOGICAL_AND_2 L1: POP_JUMP_IF_FALSE L2 L2: The fastest path through this executes one *less* bytecode than in the current 2.5-generated code. Also, any path that ends up executing the body benefits from the lack of a jump at the end. The same benefits also result when the boolean expression is more complex, e.g. if a or b and c: becomes LOGICAL_OR_1 L1 LOGICAL_AND_1 L2 LOGICAL_AND_2 L2: LOGICAL_OR_2 L1: POP_JUMP_IF_FALSE L3 L3: which contains 3 fewer instructions overall than the corresponding 2.5-generated code. So I contend that optimization is not an argument for rejecting this PEP, and may even be one for accepting it. -- Greg ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Wither PEP 335 (Overloadable Boolean Operators)?
On 5/24/07, Greg Ewing <[EMAIL PROTECTED]> wrote: > Guido van Rossum wrote: > > > Last call for discussion! I'm tempted to reject this -- the ability to > > generate optimized code based on the shortcut semantics of and/or is > > pretty important to me. > > Please don't be hasty. I've had to think about this issue > a bit. > > The conclusion I've come to is that there may be a small loss > in the theoretical amount of optimization opportunity available, > but not much. Furthermore, if you take into account some other > improvements that can be made (which I'll explain below) the > result is actually *better* than what 2.5 currently generates. > > For example, Python 2.5 currently compiles > >if a and b: > > > into > > > JUMP_IF_FALSE L1 > POP_TOP > > JUMP_IF_FALSE L1 > POP_TOP > > JUMP_FORWARD L2 >L1: > 15 POP_TOP >L2: > > Under my PEP, without any other changes, this would become > > > LOGICAL_AND_1 L1 > > LOGICAL_AND_2 >L1: > JUMP_IF_FALSE L2 > POP_TOP > > JUMP_FORWARD L3 >L2: > 15 POP_TOP >L3: > > The fastest path through this involves executing one extra > bytecode. However, since we're not using JUMP_IF_FALSE to > do the short-circuiting any more, there's no need for it > to leave its operand on the stack. So let's redefine it and > change its name to POP_JUMP_IF_FALSE. This allows us to > get rid of all the POP_TOPs, plus the jump at the end of > the statement body. Now we have > > > LOGICAL_AND_1 L1 > > LOGICAL_AND_2 >L1: > POP_JUMP_IF_FALSE L2 > >L2: > > The fastest path through this executes one *less* bytecode > than in the current 2.5-generated code. Also, any path that > ends up executing the body benefits from the lack of a > jump at the end. > > The same benefits also result when the boolean expression is > more complex, e.g. > >if a or b and c: > > > becomes > > > LOGICAL_OR_1 L1 > > LOGICAL_AND_1 L2 > > LOGICAL_AND_2 >L2: > LOGICAL_OR_2 >L1: > POP_JUMP_IF_FALSE L3 > >L3: > > which contains 3 fewer instructions overall than the > corresponding 2.5-generated code. > > So I contend that optimization is not an argument for > rejecting this PEP, and may even be one for accepting > it. Do you have an implementation available to measure this? In most cases the cost is not in the number of bytecode instructions executed but in the total amount of work. Two cheap bytecodes might well be cheaper than one expensive one. However, I'm happy to keep your PEP open until you have code that we can measure. (However, adding additional optimizations elsewhere to make up for the loss wouldn't be fair -- we would have to compare with a 2.5 or trunk (2.6) interpreter with the same additional optimizations added.) -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
