Re: [Python-Dev] The docs, reloaded

Georg Brandl wrote: > Hi, > > We managed to get an up to date version of the web version of the docs running > on the server. The address is still the same (http://pydoc.gbrandl.de:3000) > and > it's also still running on top of wsgiref. > > Changes so far: >* comments: each page that is gen

Re: [Python-Dev] The docs, reloaded

Hi, We managed to get an up to date version of the web version of the docs running on the server. The address is still the same (http://pydoc.gbrandl.de:3000) and it's also still running on top of wsgiref. Changes so far: * comments: each page that is generated from an rst file can have some

Re: [Python-Dev] The docs, reloaded

On 5/19/07, Georg Brandl <[EMAIL PROTECTED]> wrote: > over the last few weeks I've hacked on a new approach to Python's > documentation. > As Python already has an excellent documentation framework, the docutils, > with a > readable yet extendable markup format, reST, I thought that it should be

Re: [Python-Dev] The docs, reloaded

Hoi, Due to some server issues I had to take the web version down. But expect an updated version in a few days. Regards, Armin ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mai

Re: [Python-Dev] The docs, reloaded

On Thu, May 24, 2007 at 12:43:18PM -0500, Ron Adam wrote: > And for console text output, is the unmodified reST suitable, or would it > be desired to modify it in some way? Currently pydoc output looks like a man page under Unix. if it could look like that then that would be great. Otherwise ra

Re: [Python-Dev] The docs, reloaded [PEP?]

Martin v. Löwis schrieb: > 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? (o

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 n

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

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! > >>> > >>> H

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

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

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

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? > > P

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

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

Re: [Python-Dev] The docs, reloaded

Greg Ewing 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?-) I wasn't goin

Re: [Python-Dev] The docs, reloaded

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?-) -- Greg Ewing, Computer Science Dept,

Re: [Python-Dev] The docs, reloaded

Georg Brandl wrote: > Ahh, now the dime has fallen ;) (sorry, German phrase) In English it's "the penny has dropped", so it's not much different. :-) Although I thought dimes were an American thing, and Germans would be more likely to use a different coin. -- Greg Ewing, Computer Science Dept,

Re: [Python-Dev] The docs, reloaded

Laurent Gautier wrote: > 2007/5/23, Nick Craig-Wood <[EMAIL PROTECTED]>: >> Georg Brandl <[EMAIL PROTECTED]> wrote: >>> Nick Craig-Wood schrieb: Being a seasoned unix user, I tend to reach for pydoc as my first stab at finding some documentation rather than (after excavating the mouse >>

Re: [Python-Dev] The docs, reloaded

Nick Craig-Wood wrote: > Georg Brandl <[EMAIL PROTECTED]> wrote: >> Nick Craig-Wood schrieb: >>> Being a seasoned unix user, I tend to reach for pydoc as my first stab >>> at finding some documentation rather than (after excavating the mouse >>> from under a pile of paper) use a web browser. >>> >

Re: [Python-Dev] The docs, reloaded

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

Re: [Python-Dev] The docs, reloaded

Nick Craig-Wood wrote: > ``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

Re: [Python-Dev] The docs, reloaded

Nick Craig-Wood wrote: > ``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 probabl

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

Re: [Python-Dev] The docs, reloaded

On Wednesday, May 23, 2007, at 12:40PM, <[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 t

Re: [Python-Dev] The docs, reloaded

2007/5/23, Nick Craig-Wood <[EMAIL PROTECTED]>: > Georg Brandl <[EMAIL PROTECTED]> wrote: > > Nick Craig-Wood schrieb: > > > Being a seasoned unix user, I tend to reach for pydoc as my first stab > > > at finding some documentation rather than (after excavating the mouse > > > from under a pile of

Re: [Python-Dev] The docs, reloaded

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 i

Re: [Python-Dev] The docs, reloaded

Hoi, Dennis Benzinger gmx.net> writes: > Looks good. But should the source pages really use syntax highlighting? > I think if somebody is interested in the source then they should get > the real source without any highlighting. If you decide to keep the > syntax highlighting then the highlightin

Re: [Python-Dev] The docs, reloaded

Am Wed, 23 May 2007 08:30:17 +0200 schrieb Georg Brandl <[EMAIL PROTECTED]>: > [...] > Also, try > > http://pydoc.gbrandl.de:3000/os.path.exists > [...] Looks good. But should the source pages really use syntax highlighting? I think if somebody is interested in the source then they should get th

Re: [Python-Dev] The docs, reloaded

Georg Brandl <[EMAIL PROTECTED]> wrote: > Nick Craig-Wood schrieb: > > Being a seasoned unix user, I tend to reach for pydoc as my first stab > > at finding some documentation rather than (after excavating the mouse > > from under a pile of paper) use a web browser. > > > > If you've ever used py

Re: [Python-Dev] The docs, reloaded

On 5/23/07, Georg Brandl <[EMAIL PROTECTED]> wrote: > Also, try > > http://pydoc.gbrandl.de:3000/os.path.exists Beautiful! STeVe -- I'm not *in*-sane. Indeed, I am so far *out* of sane that you appear a tiny blip on the distant coast of sanity. --- Bucky Katt, Get Fuzzy _

Re: [Python-Dev] The docs, reloaded

Georg Brandl schrieb: > Armin Ronacher schrieb: >> Hoi, >> >> Additionally to the offline docs that Georg published some days ago there is >> also a web version which currently looks and works pretty much like the >> offline >> version. There are however some differences that are worth knowing: >

Re: [Python-Dev] The docs, reloaded

Armin Ronacher schrieb: > Hoi, > > Additionally to the offline docs that Georg published some days ago there is > also a web version which currently looks and works pretty much like the > offline > version. There are however some differences that are worth knowing: > > - Cleaner URLs. You can ac

Re: [Python-Dev] The docs, reloaded

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 doc

Re: [Python-Dev] The docs, reloaded

On 5/22/07, Georg Brandl <[EMAIL PROTECTED]> wrote: > > > Don't get me wrong, LaTeX is a powerful tool and I use it for every bigger > > document i type. I just think it's not the best choice for documenting > > scripting > > languages. > > Who's documenting a scripting language? Hehe I can't bel

Re: [Python-Dev] The docs, reloaded

Hoi, Additionally to the offline docs that Georg published some days ago there is also a web version which currently looks and works pretty much like the offline version. There are however some differences that are worth knowing: - Cleaner URLs. You can actually guess them because we took the ide

Re: [Python-Dev] The docs, reloaded

> > In your examples, I think the ReST version can be cleaned up quite a > > bit. First by using the .. default-role:: literal directive so that > > you can type `foo()` instead of using double back quotes and then you > > can remove the redundant semantic markup. Like this: > > I've already assign

Re: [Python-Dev] The docs, reloaded

On Tue, 22 May 2007, Steve Holden wrote: > But doesn't *everyone* now know that documentation contributions don't > have to be marked up? It's certainly been said enough. Maybe that fact > should be more prominent in the documentation? Then we'll just have to > worry about getting people to read it

[Python-Dev] The docs, reloaded

Martin v. Löwis schrieb: > That docutils happens to be written in Python should make little > difference - it's *not* part of the Python language project, > and is just a tool for us, very much like latex and latex2html. Not entirely. When I first started looking at python, I read a lot of docum

Re: [Python-Dev] The docs, reloaded

BJörn Lindqvist schrieb: >> > IMO that pair of examples shows clearly that, in this application, >> > reST is not an improvement over LaTeX in terms of readability/ >> > writability of source. It's probably not worse, although I can't help >> > muttering "EIBTI". In particular I find the "``'...'

Re: [Python-Dev] The docs, reloaded

Steve Holden schrieb: > Titus Brown wrote: >> On Tue, May 22, 2007 at 11:45:04AM -0500, [EMAIL PROTECTED] wrote: >> -> >> -> >> You at least take away a common excuse for lack of contributions. >> -> >> True whiners will just come up with new ones (e.g., "the >> -> >> documentation isn

Re: [Python-Dev] The docs, reloaded

> > IMO that pair of examples shows clearly that, in this application, > > reST is not an improvement over LaTeX in terms of readability/ > > writability of source. It's probably not worse, although I can't help > > muttering "EIBTI". In particular I find the "``'...'``" construct > > horribly un

Re: [Python-Dev] The docs, reloaded

On Tue, May 22, 2007 at 01:19:36PM -0400, Steve Holden wrote: > > For example, this rocks! :: > > > > http://pydoc.gbrandl.de/search.html?q=os.path&area=default > > It would be more impressive if the search string returned hits ... Also if it was not completely reliant on JavaScript... (Maybe

Re: [Python-Dev] The docs, reloaded

Titus Brown wrote: > On Tue, May 22, 2007 at 11:45:04AM -0500, [EMAIL PROTECTED] wrote: > -> > -> >> You at least take away a common excuse for lack of contributions. > -> >> True whiners will just come up with new ones (e.g., "the > -> >> documentation isn't available in Sanskrit yet"

Re: [Python-Dev] The docs, reloaded

On Tue, May 22, 2007 at 11:45:04AM -0500, [EMAIL PROTECTED] wrote: -> -> >> You at least take away a common excuse for lack of contributions. -> >> True whiners will just come up with new ones (e.g., "the -> >> documentation isn't available in Sanskrit yet" or "the dog ate my -> >>

Re: [Python-Dev] The docs, reloaded

>> You at least take away a common excuse for lack of contributions. >> True whiners will just come up with new ones (e.g., "the >> documentation isn't available in Sanskrit yet" or "the dog ate my >> changes before I could type them into the computer"). ;-) Steve> But doesn't

Re: [Python-Dev] The docs, reloaded

On Tue, May 22, 2007 at 06:13:36PM +0200, Georg Brandl wrote: > Finding the location that tells you how to suggest changes, and opening > a new bug in the infamous SF tracker is not really something people do > happily. A "click here to suggest a change" link that leads to a pseudo- > edit-form, co

Re: [Python-Dev] The docs, reloaded

Raymond Hettinger schrieb: >> - If you make a mistake in LaTeX, you will get a cryptic error which >> is usually a little difficult to figure out (if you're not used to >> it). You can an error though. > > FWIW, the pure Python program in Tools/scripts/texchecker.py does a > pretty good job of

Re: [Python-Dev] The docs, reloaded

On Tuesday 22 May 2007, Georg Brandl wrote: > But that's at least funnier than before :) It's not our job to make whiner-babies sound funny. -Fred -- Fred L. Drake, Jr. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/ma

Re: [Python-Dev] The docs, reloaded

Martin Blais schrieb: > On 5/22/07, Nick Coghlan <[EMAIL PROTECTED]> wrote: >> >> So in Armin's example, I found the reST version *much* easier to read. >> Whether that difference in perception is due simply to my relative lack >> of experience in using LaTeX, or to something else, I have no idea.

Re: [Python-Dev] The docs, reloaded

> - If you make a mistake in LaTeX, you will get a cryptic error which > is usually a little difficult to figure out (if you're not used to > it). You can an error though. FWIW, the pure Python program in Tools/scripts/texchecker.py does a pretty good job of catching typical LaTeX mistakes and

Re: [Python-Dev] The docs, reloaded

> - If you make a mistake in LaTeX, you will get a cryptic error which > is usually a little difficult to figure out (if you're not used to > it). You can an error though. FWIW, the pure Python program in Tools/scripts/texchecker.py does a pretty good job of catching typical LaTeX mistakes and

Re: [Python-Dev] The docs, reloaded

> - If you make a mistake in LaTeX, you will get a cryptic error which > is usually a little difficult to figure out (if you're not used to > it). You can an error though. FWIW, the pure Python program in Tools/scripts/texchecker.py does a pretty good job of catching typical LaTeX mistakes and

Re: [Python-Dev] The docs, reloaded

> - If you make a mistake in LaTeX, you will get a cryptic error which > is usually a little difficult to figure out (if you're not used to > it). You can an error though. FWIW, the pure Python program in Tools/scripts/texchecker.py does a pretty good job of catching typical LaTeX mistakes and

Re: [Python-Dev] The docs, reloaded

[EMAIL PROTECTED] wrote: > Fred> The biggest potential wins I see for a new system are: > > Fred> - more contributions > > Fred> - platform-independent processing > > Fred> I remain sceptical on being able to achieve the first, but there > Fred> some hope for it. > > You at

Re: [Python-Dev] The docs, reloaded

[EMAIL PROTECTED] schrieb: > Fred> The biggest potential wins I see for a new system are: > > Fred> - more contributions > > Fred> - platform-independent processing > > Fred> I remain sceptical on being able to achieve the first, but there > Fred> some hope for it. > > You a

Re: [Python-Dev] The docs, reloaded

Hoi, Georg Brandl gmx.net> writes: > Who's documenting a scripting language? Wanted to say agile :D Regards, Armin ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.o

Re: [Python-Dev] The docs, reloaded

Armin Ronacher schrieb: >> That, and the ability to already parse it from Python and more easily >> convert to other formats (one of LaTeX's weaknesses), are the only >> benefits that I can see to switching away from LaTeX. I have to admit >> I'm afraid we would be moving to a lesser technology, a

Re: [Python-Dev] The docs, reloaded

> - If you make a mistake in LaTeX, you will get a cryptic error which > is usually a little difficult to figure out (if you're not used to > it). You can an error though. FWIW, the pure Python program in Tools/scripts/texchecker.py does a pretty good job of catching typical LaTeX mistakes and

Re: [Python-Dev] The docs, reloaded

Fred> The biggest potential wins I see for a new system are: Fred> - more contributions Fred> - platform-independent processing Fred> I remain sceptical on being able to achieve the first, but there Fred> some hope for it. You at least take away a common excuse for lack of

Re: [Python-Dev] The docs, reloaded

Hoi, Martin Blais furius.ca> writes: > About possibilities: I'm sorry but that is simply not true. LaTeX > provides the full power of macro expansion, while ReST is a fixed > (almost, roles are an exception) syntax which has its own set of > problems and ambiguities. I was speaking of rst in co

Re: [Python-Dev] The docs, reloaded

Neal> I know almost nothing about docutils internals. How do I Neal> 'install' the above? Me either. Here's what I did: * download and expand the latest docutils snapshot * replicate Jens's work in a directory called "math" at the top level of the docutils directory *

Re: [Python-Dev] The docs, reloaded

On Tuesday 22 May 2007, Barry Warsaw wrote: > considerably. Even with a nice distro packaging system it can be a > PITA to get all the tools you need to build the documentation > properly installed. A pure-Python solution, even a lesser one, would > be a win if we can still produce top qualit

Re: [Python-Dev] The docs, reloaded

-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On May 22, 2007, at 10:37 AM, Martin Blais wrote: > That, and the ability to already parse it from Python and more easily > convert to other formats (one of LaTeX's weaknesses), are the only > benefits that I can see to switching away from LaTeX. I h

Re: [Python-Dev] The docs, reloaded

On 5/22/07, Nick Coghlan <[EMAIL PROTECTED]> wrote: > > So in Armin's example, I found the reST version *much* easier to read. > Whether that difference in perception is due simply to my relative lack > of experience in using LaTeX, or to something else, I have no idea. - If you make a mistake in

Re: [Python-Dev] The docs, reloaded

On 5/22/07, Armin Ronacher <[EMAIL PROTECTED]> wrote: > > > > > > * reST markup isn't much simpler than LaTeX. > > > > * reST doesn't support nested markup, which is used in the current > > documentation. > > For a lightweight markup language that is human readable (which rst certainly > is) th

Re: [Python-Dev] The docs, reloaded

[EMAIL PROTECTED] wrote: > True enough. There is MathML and its offspring, ASCIIMathML, which are > probably worth looking at. > > http://www.w3.org/Math/ > http://www1.chapman.edu/~jipsen/asciimath.html > > I have no idea if either one has backend support for presentation outside > the

Re: [Python-Dev] The docs, reloaded

Stephen J. Turnbull wrote: > IMO that pair of examples shows clearly that, in this application, > reST is not an improvement over LaTeX in terms of readability/ > writability of source. It's probably not worse, although I can't help > muttering "EIBTI". In particular I find the "``'...'``" constr

Re: [Python-Dev] The docs, reloaded

[EMAIL PROTECTED] wrote: > > It would appear that while we slept Jens Mortensen was busy at work on his > rst2{latex,latexmath,mathml}.py scripts: > > http://docutils.sourceforge.net/sandbox/jensj/latex_math/ > > Note the date on the files. It seems to work pretty well, and as others > hav

Re: [Python-Dev] The docs, reloaded

It would appear that while we slept Jens Mortensen was busy at work on his rst2{latex,latexmath,mathml}.py scripts: http://docutils.sourceforge.net/sandbox/jensj/latex_math/ Note the date on the files. It seems to work pretty well, and as others have pointed out, LaTeX notation is probably

Re: [Python-Dev] The docs, reloaded

Hoi, Stephen J. Turnbull xemacs.org> writes: > > IMO that pair of examples shows clearly that, in this application, > reST is not an improvement over LaTeX in terms of readability/ > writability of source. It's probably not worse, although I can't help > muttering "EIBTI". In particular I fin

Re: [Python-Dev] The docs, reloaded

Armin Ronacher writes: > rst is simpler than latex: > > LaTeX: > > \item[\code{*?}, \code{+?}, \code{??}] The \character{*}, > \character{+}, and \character{?} qualifiers are all \dfn{greedy}; they > match as much text as possible. Sometimes this behaviour isn't > desired; if the RE \re

Re: [Python-Dev] The docs, reloaded

Fred L. Drake, Jr. schrieb: > On Monday 21 May 2007, [EMAIL PROTECTED] wrote: > > Take a look at . It records request > > counts for the various pages and presents the most frequently requested > > pages in a section at the top of the page. I can make the scri

Re: [Python-Dev] The docs, reloaded

Armin Ronacher schrieb: > Hoi, > > Fred L. Drake, Jr. acm.org> writes: > >> >> On Monday 21 May 2007, A.M. Kuchling wrote: >> > Disadvantages: >> > >> > * reST markup isn't much simpler than LaTeX. >> >> * reST doesn't support nested markup, which is used in the current >> documentation.

Re: [Python-Dev] The docs, reloaded

Hoi, Fred L. Drake, Jr. acm.org> writes: > > On Monday 21 May 2007, A.M. Kuchling wrote: > > Disadvantages: > > > > * reST markup isn't much simpler than LaTeX. > > * reST doesn't support nested markup, which is used in the current > documentation. For a lightweight markup language that

Re: [Python-Dev] The docs, reloaded

Neal Becker writes: > Perhaps my comment was misunderstood. I have no objection to a new system, > and it does not have to be based on latex. I just hope there will be some > escape mechanism that allows math. Docutils already provides the "raw" directive. I don't know if the latex backend

Re: [Python-Dev] The docs, reloaded

On 5/21/07, "Martin v. Löwis" <[EMAIL PROTECTED]> wrote: > > I think the people who have responded to my comment read too much into it. > > Nowhere do I think I asked Georg to write an equation typesetter to include > > in the Python documentation toolchain. I asked that math capability be > > con

Re: [Python-Dev] The docs, reloaded

On 5/21/07, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > > >> One comment I have, I don't know if it's relevant - it perhaps > >> depends on whether the "Global Module Index" is auto-generated or > >> not. This is the page I visit the most out of all the Python > >> documentation,

Re: [Python-Dev] The docs, reloaded

Neal> It happens that for math markup, there isn't really anything Neal> better (or more familiar) than latex. True enough. There is MathML and its offspring, ASCIIMathML, which are probably worth looking at. http://www.w3.org/Math/ http://www1.chapman.edu/~jipsen/asciimath.html

Re: [Python-Dev] The docs, reloaded

On Mon, May 21, 2007, Jon Ribbens wrote: > > One comment I have, I don't know if it's relevant - it perhaps depends > on whether the "Global Module Index" is auto-generated or not. This is > the page I visit the most out of all the Python documentation, and > it's far too large and unwieldy. IMHO

Re: [Python-Dev] The docs, reloaded

[EMAIL PROTECTED] wrote: > > >>> What would be my choices for add math to the documentation? > > >> Where in the current documentation is there any math notation /at > >> all/? > > Georg> There is exactly one instance of LaTeX math in the whole docs, > Georg> it's in the des

Re: [Python-Dev] The docs, reloaded

On Monday 21 May 2007, [EMAIL PROTECTED] wrote: > Take a look at . It records request > counts for the various pages and presents the most frequently requested > pages in a section at the top of the page. I can make the script > available if anyone wants it (

Re: [Python-Dev] The docs, reloaded

On Monday 21 May 2007, A.M. Kuchling wrote: > Disadvantages: > > * reST markup isn't much simpler than LaTeX. * reST doesn't support nested markup, which is used in the current documentation. -Fred -- Fred L. Drake, Jr. ___ Python-Dev maili

Re: [Python-Dev] The docs, reloaded

>> One comment I have, I don't know if it's relevant - it perhaps >> depends on whether the "Global Module Index" is auto-generated or >> not. This is the page I visit the most out of all the Python >> documentation, and it's far too large and unwieldy. IMHO it would be >> much

Re: [Python-Dev] The docs, reloaded

Bill Janssen schrieb: >> We are developing a programming language here, not a typesetting >> system. > > Good point, Martin. Are you implying that the documentation should be > kept in LaTeX, a widely-accepted widely-disseminated stable > documentation language, which someone else maintains, rath

Re: [Python-Dev] The docs, reloaded

> Martin> I disagree. The documentation infrastructure of Python should > Martin> only consider the needs of Python itself. If other people can > Martin> use that infrastructure for other purposes, fine - if they find > Martin> that it does not meet their needs, they have to look el

Re: [Python-Dev] The docs, reloaded

> I think the people who have responded to my comment read too much into it. > Nowhere do I think I asked Georg to write an equation typesetter to include > in the Python documentation toolchain. I asked that math capability be > considered. I have no idea what tools he used to build his new > do

Re: [Python-Dev] The docs, reloaded

On Mon, May 21, 2007 at 09:23:47AM -0400, Fred L. Drake, Jr. wrote: > I'll be happy to pull the existing tools out into a separate distribution if > we move to something else for Python. There are too many users of the > existing tools to abandon. That seems like a straightforward task. The

Re: [Python-Dev] The docs, reloaded

Jon Ribbens schrieb: > On Sat, May 19, 2007 at 07:14:09PM +0200, Georg Brandl wrote: >> For the impatient: the result can be seen at . > > I think that looks great. > > One comment I have, I don't know if it's relevant - it perhaps depends > on whether the "Global Module

Re: [Python-Dev] The docs, reloaded

On Sat, May 19, 2007 at 07:14:09PM +0200, Georg Brandl wrote: > For the impatient: the result can be seen at . I think that looks great. One comment I have, I don't know if it's relevant - it perhaps depends on whether the "Global Module Index" is auto-generated or not. T

Re: [Python-Dev] The docs, reloaded

Fred L. Drake, Jr. schrieb: > On Monday 21 May 2007, [EMAIL PROTECTED] wrote: > > Then I submit that you are probably removing some significant piece of > > functionality from the provided documentation toolchain which some people > > probably rely on. After all, that's what LaTeX excels at. T

Re: [Python-Dev] The docs, reloaded

[EMAIL PROTECTED] schrieb: > Brett> Martin beat me to my comment. =) Python's needs should come > Brett> first, period. If Georg wants to add math support, fine. But > Brett> honestly I would rather he spend his time on Python-specific > Brett> stuff then get bogged down to suppo

Re: [Python-Dev] The docs, reloaded

-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On May 21, 2007, at 12:28 AM, Martin v. Löwis wrote: > I disagree. The documentation infrastructure of Python should only > consider the needs of Python itself. If other people can use that > infrastructure for other purposes, fine - if they find that

Re: [Python-Dev] The docs, reloaded

Robert Kern schrieb: > Neal Becker wrote: > >> There is an effort as part of numpy to come up with a new system using >> docstrings. It seems to me it would be unfortunate if these two efforts >> were not coordinated. > > I don't think so. The issue with numpy is getting our act together and mak

Re: [Python-Dev] The docs, reloaded

Nick Craig-Wood schrieb: > Georg Brandl <[EMAIL PROTECTED]> wrote: >> over the last few weeks I've hacked on a new approach to Python's >> documentation. >> As Python already has an excellent documentation framework, the docutils, >> with a >> readable yet extendable markup format, reST, I tho

Re: [Python-Dev] The docs, reloaded

> We are developing a programming language here, not a typesetting > system. Good point, Martin. Are you implying that the documentation should be kept in LaTeX, a widely-accepted widely-disseminated stable documentation language, which someone else maintains, rather than ReST, which elements of

Re: [Python-Dev] The docs, reloaded

> Could this be a language-independent documenting toolkit? Could > we document LISP or Ruby code with it? Might want to look at "noweb", http://www.eecs.harvard.edu/~nr/noweb/: ``...noweb works ``out of the box'' with any programming language, and supports TeX, latex, HTML, and troff back ends.

Re: [Python-Dev] The docs, reloaded

On Monday 21 May 2007, [EMAIL PROTECTED] wrote: > Then I submit that you are probably removing some significant piece of > functionality from the provided documentation toolchain which some people > probably rely on. After all, that's what LaTeX excels at. They will be > able to continue to u

Re: [Python-Dev] The docs, reloaded

>> You must realize that people will use the core tools to create >> documentation for third party packages which aren't in the core. If >> you replace LaTeX with something else I think you need to keep math >> in mind whether it's used in the core documentation or not. Marti

Re: [Python-Dev] The docs, reloaded

Brett> Martin beat me to my comment. =) Python's needs should come Brett> first, period. If Georg wants to add math support, fine. But Brett> honestly I would rather he spend his time on Python-specific Brett> stuff then get bogged down to support possible third parties. I thin

  1   2   >