Re: [Python-Dev] The docs, reloaded

[Ron Adam]

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 generated from an rst file can have some
>  comments attached to it. Commenting doesn't require registration at the
>  moment.
>* antispam with optional reverse captcha (captcha for bots, a hidden input
>  field named "homepage" which bots hopefully fill out, dumb as they are) 
> and
>  a regular expression filter rules based on MoinMoin's BadContent file.
>* administration panel for moderating comments. You can find the admin 
> panel
>  at http://pydoc.gbrandl.de:3000/admin/ -- login credentials are
>  testuser:password)
>* feeds for comments on a page or the last n comments on the whole site.
>* source view is text only (again).
> 
> What still works:
>* intelligent error pages: if a page does not exist the URL path is used to
>  conduct a fuzzy keyword search (see below).
>* fuzzy keyword search: "os.path.exists" jumps to the entry, 
> "os.paht.exists"
>  shows some possibilities.
> 
> What needs to be implemented:
>* full text search
>* proposing documentation patches
> 
> Note that the comment area is really, really dark, that's intentional.  This 
> is
> meant to visually separate comments from the official docs, but if the 
> constrast
> is deemed to unsettling, another way can be found.
> 
> Also, we're experimenting with alternate stylesheets, e.g. placing the sidebar
> on the right of the main text, or a "traditional" style for those liking the
> original docs' style.
> 
> In any case, we're waiting for your input!
> 
> cheers,
> Georg and Armin

Yes, the comments are a bit too dark.  The separation could be done better 
by moving it below the footer.  Or better yet, duplicate the navigation bar 
between the the document page and the comments.


   
   crumbsnavagation
   
 side |main page
 bar  |
  |
  |
   
   crumbsnavagation
   
   User Comment section


   
copy right
   


The user comment section could have it's own side bar if that's desirable.

Also the python version information needs to be on every page someplace.


Ron
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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
 comments attached to it. Commenting doesn't require registration at the
 moment.
   * antispam with optional reverse captcha (captcha for bots, a hidden input
 field named "homepage" which bots hopefully fill out, dumb as they are) and
 a regular expression filter rules based on MoinMoin's BadContent file.
   * administration panel for moderating comments. You can find the admin panel
 at http://pydoc.gbrandl.de:3000/admin/ -- login credentials are
 testuser:password)
   * feeds for comments on a page or the last n comments on the whole site.
   * source view is text only (again).

What still works:
   * intelligent error pages: if a page does not exist the URL path is used to
 conduct a fuzzy keyword search (see below).
   * fuzzy keyword search: "os.path.exists" jumps to the entry, "os.paht.exists"
 shows some possibilities.

What needs to be implemented:
   * full text search
   * proposing documentation patches

Note that the comment area is really, really dark, that's intentional.  This is
meant to visually separate comments from the official docs, but if the constrast
is deemed to unsettling, another way can be found.

Also, we're experimenting with alternate stylesheets, e.g. placing the sidebar
on the right of the main text, or a "traditional" style for those liking the
original docs' style.

In any case, we're waiting for your input!

cheers,
Georg and Armin


-- 
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
Python-Dev@python.org
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

[Alexandre Vassalotti]

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
> possible to use those instead of the current LaTeX->latex2html toolchain.
>
> For the impatient: the result can be seen at .
>
[SNIP]
> Waiting for comments!

Here a small suggestion, move the sidebar to the right. Moving it to
the right makes it much less intrusive. See that by yourself:
http://peadrop.com/files/pydoc-sidebar-right.png

div.body {
   background-color:white;
   margin:0pt 190pt 0pt 0px;
}
div.sidebar {
   float:right;
   margin-left:-100%;
   width:230px;
}

Keep up the great work,
-- Alexandre
___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] The docs, reloaded

[Nick Craig-Wood]

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 raw reST is fine!

> 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.

I think the latter proposal sounds like the correct one.  In debian
for instance, the python docs are a seperate package, and it would
seem reasonable that you'd have to have that package installed to get
the long docs.

> > 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 you look at the documentation for subprocess for instance, you'll
see that the docstring is pretty much the same as the library
reference documentation which seems like needless duplication and
opportunity for code/doc skew.  Maybe one is auto generated from the
other - I don't know!

> > 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.

Well you could stop after reading the short bit!

> 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.

Sounds good!

Nick
-- 
Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick
___
Python-Dev mailing list
Python-Dev@python.org
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?]

[Georg Brandl]

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? (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).

Assuming that Fred goes into well-earned retirement from the doc
maintainer position (private mail exchange hinted that way), and
nobody more qualified steps up, I'd be available to take that post.
(If someone else wants to take maintainership of the content, very good,
I'd have to be maintainer of the build tools anyway.)

I'd then try to form a doc maintaining team, just as the PEP editor team
that was created recently, to deal with the (hopefully relatively large ;) )
amount of comments and edit requests.

> 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 agree.

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
Python-Dev@python.org
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?]

[Martin v. Löwis]

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
Python-Dev@python.org
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]

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
Python-Dev@python.org
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

[Georg Brandl]

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
Python-Dev@python.org
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]

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
Python-Dev@python.org
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

[Georg Brandl]

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
Python-Dev@python.org
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

[Georg Brandl]

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
Python-Dev@python.org
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]

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
Python-Dev@python.org
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]

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
Python-Dev@python.org
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

[BJörn Lindqvist]

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
Python-Dev@python.org
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]

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 going to say it :)

Now, at the risk of going even further out of the mainstream (actually, 
there's no risk, it's a dead certainty), if I had been clever enough to 
think that I could write a LaTeX translator, I probably would have made 
my target language Docbook or some other flavor of XML.

Now, you might argue that XML is more cumbersome and harder to author 
than reST, and that is certainly a valid argument. On the other hand, 
there are a couple of interesting advantages to using XML:

1) You get an instant WYSIWYG preview capability by publishing a 
standard CSS stylesheet along with the docs. Anyone would be able to see 
what the output would look like merely by viewing it in a browser. While 
there would be some document transformations which would be not be 
previewable in CSS (such as breaking the document up into hyperlinked 
chapters), you would at least be able to see enough to be able to do a 
decent job of editing the text without having to install any special 
tools. And some of those more difficult transformations would be doable 
with a suitable XSTL stylesheet, which can be directly executed in most 
browsers. (As an example, I once wrote an XSLT stylesheet that converted 
OpenDocument XML into the equivalent HTML - this was part of my Firefox 
ODFReader plugin [http://www.alcoholicsunanimous.com/odfreader/], that 
allowed ODF documents to be directly viewed in the browser without 
having to launch an external helper application.)

2) There are a few WYSIWYG XML editors out there, which allow you to 
edit the styled text directly in an editor (although I don't know of any 
open source ones.)

3) The document processing tool could be very minimal, mostly assembled 
out of standard modules for processing XML.

4) XML has a well-specified method of escaping into other (XML-based) 
languages, which is XML namespaces. So for those who want equations in 
their docs, they could simply insert a block of MathML inside their 
Docbook XML. Similarly, illustrations could be embedded using bitmap 
images or SVG as appropriate.

5) Having XML-based docs would make it easy to write other kinds of 
processors that operate on the docs in different ways, such as building 
a keyword index or doing various kinds of analysis.

Now, this suggestion of using XML isn't really a serious one. But I 
think that the various advantages that I have listed ought to be 
considered when thinking about how the tool chain for python 
documentations should operate.

I think that there is a big advantage to making the document processing 
tools simple and hosted entirely in Python. People who contribute to the 
docs are likely to know quite a bit about Python, but it is far from 
certain what else they might know. And tools written in Python are 
automatically able to run in diverse environments, which may not be the 
case for tools written in other languages. This means that tools that 
are in Python are more likely to be used, and further, they are more 
likely to be improved or specialized to the task by those who use them.

In terms of authoring, the convenience of the markup language is only 
one factor; A bigger factor I think is having a short feedback cycle 
between edit and test, where 'test' means seeing what your written text 
would look like in the finished product. The quicker you can make that 
feedback loop, the more likely people will be to work on the docs.

-- Talin
___
Python-Dev mailing list
Python-Dev@python.org
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

[Greg Ewing]

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, +--+
University of Canterbury,  | Carpe post meridiem! |
Christchurch, New Zealand  | (I'm not a morning person.)  |
[EMAIL PROTECTED]  +--+
___
Python-Dev mailing list
Python-Dev@python.org
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

[Greg Ewing]

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, +--+
University of Canterbury,  | Carpe post meridiem! |
Christchurch, New Zealand  | (I'm not a morning person.)  |
[EMAIL PROTECTED]  +--+
___
Python-Dev mailing list
Python-Dev@python.org
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]

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
 from under a pile of paper) use a web browser.

 If you've ever used pydoc you'll know it reads docstrings and for some
 modules they are great and for others they are sorely lacking.

 If pydoc could show all this documentation as well I'd be very happy!

 Maybe your quick dispatch feature could be added to pydoc too?
>>>  It is my intention to work together with Ron Adam to make the pydoc <->
>>>  documentation integration as seamless as possible.
>> 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!
> 
> One option is to use a text-mode browser (lynx, links, or the likes).
> 
> The other is to develop a terminal mode application (currently in pydoc,
> I believe)
 >
>> How would pydoc decide which bit of docs it is going to show?
>>
>> 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?
> 
> I really think that making pydoc a solid library to extract/search/navigate
> the documentation offers a lot of interesting perspectives.
> When one think beyond the application discussed here, there are a
> lot of tools (ipython, or any IDE for example) that could make great use
> of the facility.
> 
> [note: Ron and I seemed to disagree on what (and how) pydoc should be,
> and that in particular, but I keep a keen interest in having such a library.]

But we agree on making it a useful library module or package.  ;-)

And I don't see anything above I disagree with.

Cheers,
Ron


>> If you type "pydoc re" at the moment then it says in it
>>
>>   MODULE DOCS
>>   http://www.python.org/doc/current/lib/module-re.html
>>
>> which is pretty much useless to me when ssh-ed in to a linux box half
>> way around the world...
>>
 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
>>
>> --
>> Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick
>> ___
>> Python-Dev mailing list
>> Python-Dev@python.org
>> http://mail.python.org/mailman/listinfo/python-dev
>> Unsubscribe: 
>> http://mail.python.org/mailman/options/python-dev/lgautier%40gmail.com
>>
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/rrr%40ronadam.com
> 
> 

___
Python-Dev mailing list
Python-Dev@python.org
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]

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.
>>>
>>> If you've ever used pydoc you'll know it reads docstrings and for some
>>> modules they are great and for others they are sorely lacking.
>>>
>>> If pydoc could show all this documentation as well I'd be very happy!
>>>
>>> Maybe your quick dispatch feature could be added to pydoc too?
>>  It is my intention to work together with Ron Adam to make the pydoc <->
>>  documentation integration as seamless as possible.
> 
> 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.

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.


> 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'.


> If you type "pydoc re" at the moment then it says in it
> 
>   MODULE DOCS
>   http://www.python.org/doc/current/lib/module-re.html
> 
> which is pretty much useless to me when ssh-ed in to a linux box half
> way around the world...
> 
>>> 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
> 

___
Python-Dev mailing list
Python-Dev@python.org
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]

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)
> 
> ...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.

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?

-- Talin

___
Python-Dev mailing list
Python-Dev@python.org
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

[Scott Dial]

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 OK.
> Likewise with `comment' to 'comment'.
> 
> For an example see the first paragraph here:
> 
>   http://pydoc.gbrandl.de/reference/index.html
> 

In fairness to Georg, latex2html also misses the smart quotes. See the 
same paragraph here:

http://docs.python.org/ref/front.html

-- 
Scott Dial
[EMAIL PROTECTED]
[EMAIL PROTECTED]
___
Python-Dev mailing list
Python-Dev@python.org
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

[Fred L. Drake, Jr.]

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 OK.
 > Likewise with `comment' to 'comment'.
 >
 > For an example see the first paragraph here:
 >
 >   http://pydoc.gbrandl.de/reference/index.html

What latex does here for typeset output is nice, but it's also a bit of a hack 
job.  The ` and ' characters aren't smart, the fonts just have curved glyphs 
for them.  `` and '' are mapped to additional glyphs using ligatures, again 
part of the font information.

The result, of course, is really nice.  :-)

Scott Dial wrote:
 > In fairness to Georg, latex2html also misses the smart quotes. See the
 > same paragraph here:
 >
 > http://docs.python.org/ref/front.html

There's a way to make latex2html do "the right thing" for these, except... it 
then happily does so even to ` and '' (and `` and '') in code samples, since 
there's no equivalent to the font information used to handle this in latex.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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'.

Ahh, now the dime has fallen ;) (sorry, German phrase)

Yes, it should probably use Unicode equivalents of these quotes, as it
does with en- and em-dashes.

There are also nifty "post-processor" filters which operate on complete HTML
pages and replace normal quotes by "smart" ones, perhaps that is the way
to go.

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Ronald Oussoren]

 
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 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). 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.  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.

pydoc can already do this for the language reference (try 'pydoc import' on a 
system with a local install of the python documentation).

Ronald

>
>Skip
>___
>Python-Dev mailing list
>Python-Dev@python.org
>http://mail.python.org/mailman/listinfo/python-dev
>Unsubscribe: 
>http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com
>
>
___
Python-Dev mailing list
Python-Dev@python.org
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

[Laurent Gautier]

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 paper) use a web browser.
> > >
> > > If you've ever used pydoc you'll know it reads docstrings and for some
> > > modules they are great and for others they are sorely lacking.
> > >
> > > If pydoc could show all this documentation as well I'd be very happy!
> > >
> > > Maybe your quick dispatch feature could be added to pydoc too?
> >
> >  It is my intention to work together with Ron Adam to make the pydoc <->
> >  documentation integration as seamless as possible.
>
> 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!

One option is to use a text-mode browser (lynx, links, or the likes).

The other is to develop a terminal mode application (currently in pydoc,
I believe)

> How would pydoc decide which bit of docs it is going to show?
>
> 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?

I really think that making pydoc a solid library to extract/search/navigate
the documentation offers a lot of interesting perspectives.
When one think beyond the application discussed here, there are a
lot of tools (ipython, or any IDE for example) that could make great use
of the facility.

[note: Ron and I seemed to disagree on what (and how) pydoc should be,
and that in particular, but I keep a keen interest in having such a library.]



> If you type "pydoc re" at the moment then it says in it
>
>   MODULE DOCS
>   http://www.python.org/doc/current/lib/module-re.html
>
> which is pretty much useless to me when ssh-ed in to a linux box half
> way around the world...
>
> > > 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
>
> --
> Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/lgautier%40gmail.com
>
___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

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). 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.  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.

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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 highlighting of multiline ReST strings
> should be fixed. For example see the source for splitext().

Yeah. Georg said the same yesterday. I'll revert that change so that it displays
the plain sources as text/plain in the online version too.

Regards,
Armin

___
Python-Dev mailing list
Python-Dev@python.org
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

[Dennis Benzinger]

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
the real source without any highlighting. If you decide to keep the
syntax highlighting then the highlighting of multiline ReST strings
should be fixed. For example see the source for splitext().

Thanks for the work,
Dennis Benzinger
___
Python-Dev mailing list
Python-Dev@python.org
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]

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 pydoc you'll know it reads docstrings and for some
> > modules they are great and for others they are sorely lacking.
> > 
> > If pydoc could show all this documentation as well I'd be very happy!
> > 
> > Maybe your quick dispatch feature could be added to pydoc too?
> 
>  It is my intention to work together with Ron Adam to make the pydoc <->
>  documentation integration as seamless as possible.

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?

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 you type "pydoc re" at the moment then it says in it

  MODULE DOCS
  http://www.python.org/doc/current/lib/module-re.html

which is pretty much useless to me when ssh-ed in to a linux box half
way around the world...

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

-- 
Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick
___
Python-Dev mailing list
Python-Dev@python.org
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

[Steven Bethard]

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
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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:
>> 
>> - Cleaner URLs. You can actually guess them because we took the idea the PHP
>>   people had and check for similar pages if a page does not exist. We do 
>> however
>>   redirect if there was a match so that the URL stays unique.
>> 
>> - The search doesn't require JavaScript (but is currently disabled due to a
>>   buggy stemmer and indexer)
> 
> Also, try
> 
> http://pydoc.gbrandl.de:3000/os.path.exists
> 
> and

http://pydoc.gbrandl.de:3000/os.paht.exists

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 actually guess them because we took the idea the PHP
>   people had and check for similar pages if a page does not exist. We do 
> however
>   redirect if there was a match so that the URL stays unique.
> 
> - The search doesn't require JavaScript (but is currently disabled due to a
>   buggy stemmer and indexer)

Also, try

http://pydoc.gbrandl.de:3000/os.path.exists

and

___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin Blais]

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)

...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.
___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin Blais]

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 believe I just wrote that...
___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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 idea the PHP
  people had and check for similar pages if a page does not exist. We do however
  redirect if there was a match so that the URL stays unique.

- The search doesn't require JavaScript (but is currently disabled due to a
  buggy stemmer and indexer)

That's it for now, you can try it online at http://pydoc.gbrandl.de:3000/

Regards,
Armin

___
Python-Dev mailing list
Python-Dev@python.org
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

[BJörn Lindqvist]

> > 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 assigned the default role to `var` since it's used most
> frequently.
>
> Having two ways of spelling literal code is wasting markup, for me.

Reassign it then. :) `var` makes italic text but you can use *var* for
that instead. Minor point I know, but it would make reading ReST
source just a tiny bit easier.

-- 
mvh Björn
___
Python-Dev mailing list
Python-Dev@python.org
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

[Ka-Ping Yee]

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 ...

I think the issue is instant gratification.  You don't get the
satisfaction of seeing your changes unless you're willing to write
them in LaTeX, and that's a pretty big barrier -- a lot of what
motivates open source volunteers is the sense of fulfillment.

(Hence, by the same nature, Wiki-like editing with instant changes
visible online will probably greatly increase contributions.)


-- ?!ng
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] The docs, reloaded

[Jim Jewett]

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
documentation.  Now I don't read it so much; the time when I could
easily suggest doc changes without explicitly setting time aside has
passed.

At that time, the barriers to submitting were fairly large; these are
the ones I remember:

(1)  Not realizing that I *could* submit changes, and they would be welcome.
(2)  Not understanding it well enough to document it correctly.
(3)  Not having easy access to the source -- I didn't want to to
retype it, or to edit html only to find out it was maintained in some
other format.  Even once I found the cvs repository, the docs weren't
in the main area.
(4)  Not having an easy way to submit the changes quickly.
(5)  Wanting to check my work, in case I was wrong.

I have no idea how to fix (1) and (2).

Putting them on a wiki improves the situation with (3) and (4).

(5) is at least helped by keeping the formatting requirements as
simple as possible (not sure if ReST does this or not) and by letting
me verify them before I submit.

Getting docutils is already a barrier; I would like to see a stdlib
module (not script hidden off to the side) for verification and
conversion.  I don't think I installed docutils myself until I started
to write a PEP.  But once I did download and install and figure out
how to call it ... at least it generally worked, and ran with
something (python) I was already using.

Getting a 3rd party tool that ends up requiring fourth party tools
(such as LaTex, but then I need to a viewer, or the old toolchain that
required me to install Perl) ... took longer than my attention span.
This was despite the fact that I had already used all the needed tools
in previous years; they just weren't installed on the machines I had
at the time ... and installing them on windows was something that
would *probably* work *eventually*.  If I had been new to programming,
it would have been even more intimidating.

-jJ
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 "``'...'``" construct
>> > horribly unreadable because it makes it hard to find the Python syntax
>> > in all the reST.
>>
>> Well. That was a bad example. But if you look at the converted sources and 
>> open
>> the source file you can see that rst is a lot cleaner that latex for this 
>> type
>> of documentation.
> 
> 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 assigned the default role to `var` since it's used most
frequently.

Having two ways of spelling literal code is wasting markup, for me.

> The above is the most readable version. For example, semantic markup
> like :regexp:`<.\*>` doesn't serve any useful purpose. The end result
> is that the text is typesetted with a fixed-width font, no matter if
> you prepend :regexp: to it or not.

Yes, there are a few semantic roles that may be obsolete.

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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't available in Sanskrit yet" or "the dog ate my
>> -> >> changes before I could type them into the computer"). ;-)
>> -> 
>> -> Steve> But doesn't *everyone* now know that documentation 
>> contributions
>> -> Steve> don't have to be marked up? It's certainly been said
>> -> Steve> enough.
>> -> 
>> -> Sure, but that doesn't stop the true whiners. ;-)
>> 
>> Nothing stops the true whiners ;).
>> 
>> I think new and exciting ways of viewing, searching, annotating, linking
>> to/from, and indexing the docs are more important than new formats for
>> (not) writing the docs.
>> 
>> 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 ...

This is a JavaScript based search, which will only be (optionally) integrated
in the offline version.

The online version will get a more sophisticated search.
We've just finished to implement the quick dispatcher in the repository.
A request to

http://docs.python.org/os.path

would then redirect to the appropriate module page, as well as

http://docs.python.org/?q=os.path

Something like

http://docs.python.org/?q=os.paht (note the misspelling)

would lead to a page with close matching results, os.path being the first
of them.

(The web app is based on wsgiref, with a few wrappers around it...)

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[BJörn Lindqvist]

> > 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 unreadable because it makes it hard to find the Python syntax
> > in all the reST.
>
> Well. That was a bad example. But if you look at the converted sources and 
> open
> the source file you can see that rst is a lot cleaner that latex for this type
> of documentation.

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:

`\*?`, `+?`, `??`
  The "`*`", "`+`" and "`?`" qualifiers are all *greedy*; they match
  as much text as possible. Sometimes this behaviour isn't desired; if
  the RE `<.*>` is matched against `'title'`, it will match
  the entire string, and not just `''`. Adding "`?`" after the
  qualifier makes it perform the match in *non-greedy* or *minimal*
  fashion; as *few* characters as possible will be matched. Using
  `.*?` in the previous expression will match only `''`.

The above is the most readable version. For example, semantic markup
like :regexp:`<.\*>` doesn't serve any useful purpose. The end result
is that the text is typesetted with a fixed-width font, no matter if
you prepend :regexp: to it or not.


-- 
mvh Björn
___
Python-Dev mailing list
Python-Dev@python.org
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

[Jon Ribbens]

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 it's not finished yet?)
___
Python-Dev mailing list
Python-Dev@python.org
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

[Steve Holden]

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" or "the dog ate my
> -> >> changes before I could type them into the computer"). ;-)
> -> 
> -> Steve> But doesn't *everyone* now know that documentation contributions
> -> Steve> don't have to be marked up? It's certainly been said
> -> Steve> enough.
> -> 
> -> Sure, but that doesn't stop the true whiners. ;-)
> 
> Nothing stops the true whiners ;).
> 
> I think new and exciting ways of viewing, searching, annotating, linking
> to/from, and indexing the docs are more important than new formats for
> (not) writing the docs.
> 
> 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 ...

regards
  Steve
-- 
Steve Holden+1 571 484 6266   +1 800 494 3119
Holden Web LLC/Ltd   http://www.holdenweb.com
Skype: holdenweb  http://del.icio.us/steve.holden
-- Asciimercial -
Get on the web: Blog, lens and tag your way to fame!!
holdenweb.blogspot.comsquidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-- Thank You for Reading 

___
Python-Dev mailing list
Python-Dev@python.org
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

[Titus Brown]

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
-> >> changes before I could type them into the computer"). ;-)
-> 
-> Steve> But doesn't *everyone* now know that documentation contributions
-> Steve> don't have to be marked up? It's certainly been said
-> Steve> enough.
-> 
-> Sure, but that doesn't stop the true whiners. ;-)

Nothing stops the true whiners ;).

I think new and exciting ways of viewing, searching, annotating, linking
to/from, and indexing the docs are more important than new formats for
(not) writing the docs.

For example, this rocks! ::

http://pydoc.gbrandl.de/search.html?q=os.path&area=default

There have been (good) efforts to wikify the docs in the past. IMO what
would make them really work would be to have docs.python.org, the
"official" Python docs location, start hosting these efforts.  As long
as that location is static, I think the majority of users will ignore
other efforts.

cheers,
--titus

p.s. Are there good directions for installing the toolchain for current
docs building anywhere?  I've tried once or twice, but despite a lot of
LaTeX experience I could never get everything hooked up right.
___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

>> 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 *everyone* now know that documentation contributions
Steve> don't have to be marked up? It's certainly been said
Steve> enough.

Sure, but that doesn't stop the true whiners. ;-)

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Jon Ribbens]

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, complete with preview facility, might prove more effective.

Indeed. I know my instinctive reaction to the Python docs is "oh, this
is not something which the public can contribute to". Something more
like the PHP-style "public annotations" might be good - with an
appropriate moderation / voting system on the annotations it could
possibly be very good.
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 catching typical LaTeX mistakes and giving high-quality
> error reporting.  With that tool, I've been making doc contributions for years
> and not needed my own LaTeX build.

I'm not saying that LaTeX is hard for most of us, I say that it is *perceived*
to be hard by many.

And as soon as you dig into the deep support infrastructure, it gets
very confusing. Just look at this bug fix I made some time ago:
http://mail.python.org/pipermail/python-checkins/2007-April/059637.html

> Also, I did not need to learn LaTeX itself.  It was sufficient to read a 
> little
> of Documenting Python and then model the markup from existing docs.

ISTM that this is possible with the new markup too. I wrote a great part of the
new "Documenting Python" document, and after reading that one should be prepared
enough to write reST just as well.

> In contrast, whenever I've tried to build a complex ReST document,
> it was *always* a struggle.  Copying from existing docs doesn't help
> much there because the cues are more subtle.

I can't see many differences. If I can translate a \begin{classdesc}{...}
environment, I can also translate a ".. class::" directive for my new item.

> As Martin pointed out,
> most errors slide-by because the mis-markup is typically read as 
> valid, unmarked-up text.  I find myself having to continously build and
> view and html file as I write.  I like ResT for light-weight work but think
> it is not ready for prime-time with respect to more complex requirements.

Are the docs really that complex? I mean, look at the typical source of
a converted page. The most common things are "information units", i.e.

.. class::

directives, code snippets and plain old text. Cross-references work
flawlessly.

You may also ask Thomas Heller about documenting Python modules in reST.
AFAIR the ctypes docs were written with it and converted to LaTeX
afterwards.

> Fred is also correct in that we don't seem to have people rushing to
> contribute docs (more than a line or two).  For a long-time, we've
> always said that it is okay to submit plain text doc contributions and
> that another person downstream would do the mark-up.  We've had
> few takers.

Sometimes it's the way you present the ability to change things that
affects how many people actually do it.

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, complete with preview facility, might prove more effective.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Fred L. Drake, Jr.]

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/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] The docs, reloaded

[Georg Brandl]

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.
> 
> - 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.
> 
> - If you make a mistake in ReST, you will often get no warning nor
> error, and not the desired output.  If you were to use the amount of
> markup in that example, you would have to check your text with rst2xml
> frequently to make sure it groks what you're trying to say.  (And I've
> been there: I wrote an entire project who relies specifically on this,
> on precise structures generated by docutils (http://furius.ca/nabu/).
> It's *very* easy to make subtle errors that generate something else
> than what you want.)

That is correct, but can be helped with nice preview features.

> 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.)

While writing the converter, I stumbled about a few locations where the
LaTeX markup cannot be completely converted into reST, and a few locations
where invalid reST was generated and not warned about.

However, both of those problems occurred far less often than I'd anticipated.

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Raymond Hettinger]

> - 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 giving high-quality
error reporting.  With that tool, I've been making doc contributions for years
and not needed my own LaTeX build.

Also, I did not need to learn LaTeX itself.  It was sufficient to read a little
of Documenting Python and then model the markup from existing docs.

In contrast, whenever I've tried to build a complex ReST document,
it was *always* a struggle.  Copying from existing docs doesn't help
much there because the cues are more subtle.  As Martin pointed out,
most errors slide-by because the mis-markup is typically read as 
valid, unmarked-up text.  I find myself having to continously build and
view and html file as I write.  I like ResT for light-weight work but think
it is not ready for prime-time with respect to more complex requirements.

Fred is also correct in that we don't seem to have people rushing to
contribute docs (more than a line or two).  For a long-time, we've
always said that it is okay to submit plain text doc contributions and
that another person downstream would do the mark-up.  We've had
few takers.


Raymond
___
Python-Dev mailing list
Python-Dev@python.org
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

[Raymond Hettinger]

> - 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 giving high-quality
error reporting.  With that tool, I've been making doc contributions for years
and not needed my own LaTeX build.

Also, I did not need to learn LaTeX itself.  It was sufficient to read a little
of Documenting Python and then model the markup from existing docs.

In contrast, whenever I've tried to build a complex ReST document,
it was *always* a struggle.  Copying from existing docs doesn't help
much there because the cues are more subtle.  As Martin pointed out,
most errors slide-by because the mis-markup is typically read as 
valid, unmarked-up text.  I find myself having to continously build and
view and html file as I write.  I like ResT for light-weight work but think
it is not ready for prime-time with respect to more complex requirements.

Fred is also correct in that we don't seem to have people rushing to
contribute docs (more than a line or two).  For a long-time, we've
always said that it is okay to submit plain text doc contributions and
that another person downstream would do the mark-up.  We've had
few takers.


Raymond
___
Python-Dev mailing list
Python-Dev@python.org
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

[Raymond Hettinger]

> - 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 giving high-quality
error reporting.  With that tool, I've been making doc contributions for years
and not needed my own LaTeX build.

Also, I did not need to learn LaTeX itself.  It was sufficient to read a little
of Documenting Python and then model the markup from existing docs.

In contrast, whenever I've tried to build a complex ReST document,
it was *always* a struggle.  Copying from existing docs doesn't help
much there because the cues are more subtle.  As Martin pointed out,
most errors slide-by because the mis-markup is typically read as 
valid, unmarked-up text.  I find myself having to continously build and
view and html file as I write.  I like ResT for light-weight work but think
it is not ready for prime-time with respect to more complex requirements.

Fred is also correct in that we don't seem to have people rushing to
contribute docs (more than a line or two).  For a long-time, we've
always said that it is okay to submit plain text doc contributions and
that another person downstream would do the mark-up.  We've had
few takers.


Raymond
___
Python-Dev mailing list
Python-Dev@python.org
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

[Raymond Hettinger]

> - 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 giving high-quality
error reporting.  With that tool, I've been making doc contributions for years
and not needed my own LaTeX build.

Also, I did not need to learn LaTeX itself.  It was sufficient to read a little
of Documenting Python and then model the markup from existing docs.

In contrast, whenever I've tried to build a complex ReST document,
it was *always* a struggle.  Copying from existing docs doesn't help
much there because the cues are more subtle.  As Martin pointed out,
most errors slide-by because the mis-markup is typically read as 
valid, unmarked-up text.  I find myself having to continously build and
view and html file as I write.  I like ResT for light-weight work but think
it is not ready for prime-time with respect to more complex requirements.

Fred is also correct in that we don't seem to have people rushing to
contribute docs (more than a line or two).  For a long-time, we've
always said that it is okay to submit plain text doc contributions and
that another person downstream would do the mark-up.  We've had
few takers.


Raymond
___
Python-Dev mailing list
Python-Dev@python.org
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

[Steve Holden]

[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 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"). ;-)
> 
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 ...

regards
  Steve
-- 
Steve Holden+1 571 484 6266   +1 800 494 3119
Holden Web LLC/Ltd   http://www.holdenweb.com
Skype: holdenweb  http://del.icio.us/steve.holden
-- Asciimercial -
Get on the web: Blog, lens and tag your way to fame!!
holdenweb.blogspot.comsquidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-- Thank You for Reading 

___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

[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 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"). ;-)

But that's at least funnier than before :)

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] The docs, reloaded

[Georg Brandl]

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, and the driver
>> for that seems to be people's reluctance to work with the more
>> powerful, more complex tool.  Not saying it is invalid (it's about
>> people, in the end), but I still don't see what's the big problem with
>> LaTeX.
> The problem with latex is that it requires more knowledge thus the amount of
> people that can contribute is a lot lower. It's a lot harder to generate a
> searchindex, do interlinking, generate a dynamic documentation with comments 
> etc.

This could of course be done with LaTeX as well, but the current toolchain uses
latex2html which is written and customized in Perl -- I'd never try to do
anything with it.

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

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Raymond Hettinger]

> - 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 giving high-quality
error reporting.


Raymond
___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

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 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"). ;-)

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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 comparison with other lightweight markup languages.
(textile, markdown, wiki syntax). 

> 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, and the driver
> for that seems to be people's reluctance to work with the more
> powerful, more complex tool.  Not saying it is invalid (it's about
> people, in the end), but I still don't see what's the big problem with
> LaTeX.
The problem with latex is that it requires more knowledge thus the amount of
people that can contribute is a lot lower. It's a lot harder to generate a
searchindex, do interlinking, generate a dynamic documentation with comments 
etc.

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.

Regards,
Armin

___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

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
* edited setup.py to get them installed:

diff -u setup.py.~1~ setup.py
--- setup.py.~1~2007-03-21 18:45:38.0 -0500
+++ setup.py2007-05-22 07:07:25.0 -0500
@@ -115,6 +115,9 @@
  'tools/rst2xml.py',
  'tools/rst2pseudoxml.py',
  'tools/rstpep2html.py',
+ 'math/tools/rst2latex.py',
+ 'math/tools/rst2latexmath.py',
+ 'math/tools/rst2mathml.py',
  ],}
 """Distutils setup parameters."""

* ran "python setup.py install"

That's probably more than necessary, but with the math subdir I can easily
move the whole thing to a new snapshot and the setup.py change lets me
install them transparently.

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Fred L. Drake, Jr.]

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 quality online and written
 > documentation from one source.

The biggest potential wins I see for a new system are:

- more contributions

- platform-independent processing

I remain sceptical on being able to achieve the first, but there some hope for 
it.  The later should make things easier for people who are willing to put 
the work into contribution, which is valuable in its own right.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
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

[Barry Warsaw]

-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 have to admit
> I'm afraid we would be moving to a lesser technology, and the driver
> for that seems to be people's reluctance to work with the more
> powerful, more complex tool.  Not saying it is invalid (it's about
> people, in the end), but I still don't see what's the big problem with
> LaTeX.

I'm a fan of LaTeX (and latex, er, oops :) too, but what appeals to  
me most about moving to reST is that the tool chain simplifies  
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 quality online and written  
documentation from one source.

- -Barry

-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.7 (Darwin)

iQCVAwUBRlMC7XEjvBPtnXfVAQJoFQQAjvYsXamif459t34X4Bn00G0S1b3qeM1Y
PhwdAC5cuCpMoopVl+9vtjjcP4Np9P0buY09H+mLwv0nAZRNF7HT3xDr/U65FiX+
Aa7B9+3jVqRGg1+R6oYRKuPUmcLrBFESy6thKkw9audVsT5jgpBM9m9Y405QSIEU
MvK7hYrYBqQ=
=Jdbt
-END PGP SIGNATURE-
___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin Blais]

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 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.

- If you make a mistake in ReST, you will often get no warning nor
error, and not the desired output.  If you were to use the amount of
markup in that example, you would have to check your text with rst2xml
frequently to make sure it groks what you're trying to say.  (And I've
been there: I wrote an entire project who relies specifically on this,
on precise structures generated by docutils (http://furius.ca/nabu/).
It's *very* easy to make subtle errors that generate something else
than what you want.)

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.)
___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin Blais]

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) the syntax is surprisingly powerful. You can nest any block tag and I'm 
> not
> sure how often you have to nest roles and stuff like that. The goal of the new
> docs is a less complex syntax and currently nothing beats reStructuredText in
> terms of readability and possibilities.

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.  It is far from perfect, and definitely does
not have the flexibility that LaTeX provides.  Some of the syntax
cannot be nested (try to combine ** with literals).


> rst is simpler than latex:

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, and the driver
for that seems to be people's reluctance to work with the more
powerful, more complex tool.  Not saying it is invalid (it's about
people, in the end), but I still don't see what's the big problem with
LaTeX.
___
Python-Dev mailing list
Python-Dev@python.org
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 Coghlan]

[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 web,

MathML is the language used for equations in Open Document Format (aka 
ISO 26300). I don't know what extra typesetting tricks (if any) they 
wrap around it, though.

Cheers,
Nick.

-- 
Nick Coghlan   |   [EMAIL PROTECTED]   |   Brisbane, Australia
---
 http://www.boredomandlaziness.org
___
Python-Dev mailing list
Python-Dev@python.org
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 Coghlan]

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 "``'...'``" construct
> horribly unreadable because it makes it hard to find the Python syntax
> in all the reST.

It's interesting how perceptions can differ - I find heavily marked up 
latex tends to blur into a huge wall of text when I try to read it 
because of all of the {} and \ characters everywhere. With reST, on the 
other hand, I find the use of the relatively 'light' backquote and colon 
characters to delineate the markup breaks things up sufficiently that I 
can easily ignore the markup in order to read what has actually been 
written.

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.

Cheers,
Nick.


-- 
Nick Coghlan   |   [EMAIL PROTECTED]   |   Brisbane, Australia
---
 http://www.boredomandlaziness.org
___
Python-Dev mailing list
Python-Dev@python.org
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

[Neal Becker]

[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
> have pointed out, LaTeX notation is probably more familiar to people
> interested in math display than anything else.
> 

I know almost nothing about docutils internals.  How do I 'install' the above?

___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

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 more familiar to people
interested in math display than anything else.

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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 find the "``'...'``" construct
> horribly unreadable because it makes it hard to find the Python syntax
> in all the reST.

Well. That was a bad example. But if you look at the converted sources and open
the source file you can see that rst is a lot cleaner that latex for this type
of documentation.

Regards,
Armin

___
Python-Dev mailing list
Python-Dev@python.org
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

[Stephen J. Turnbull]

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 \regexp{<.*>} is matched against
 > \code{'title'}, it will match the entire string, and not just
 > \code{''}.  Adding \character{?} after the qualifier makes it
 > perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as
 > \emph{few} characters as possible will be matched.  Using \regexp{.*?}
 > in the previous expression will match only \code{''}.
 > 
 > Here the same in rst:
 > 
 > ``*?``, ``+?``, ``??``
 >The ``'\*'``, ``'+'``, and ``'?'`` qualifiers are all :dfn:`greedy`;
 >they match as much text as possible.  Sometimes this behaviour isn't
 >desired; if the RE :regexp:`<.\*>` is matched against
 >``'title'``, it will match the entire string, and not just
 >``''``.  Adding ``'?'`` after the qualifier makes it perform the
 >match in :dfn:`non-greedy` or :dfn:`minimal` fashion; as *few*
 >characters as possible will be matched.  Using :regexp:`.\*?` in the
 >previous expression will match only ``''``.

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 unreadable because it makes it hard to find the Python syntax
in all the reST.

I don't think that's an argument against switching to reST, though.
Georg's site speaks for itself.  Kudos!
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 script
>  > available if anyone wants it (it uses Myghty - Mason in Python.)
> 
> This is very cool.  ;-)

Indeed, it would be a great addition!

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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.
> 
> For a lightweight markup language that is human readable (which rst certainly
> is) the syntax is surprisingly powerful. You can nest any block tag and I'm 
> not
> sure how often you have to nest roles and stuff like that. The goal of the new
> docs is a less complex syntax and currently nothing beats reStructuredText in
> terms of readability and possibilities.

Also, I believe there are efforts within docutils to make a limited amount of
nested inline markup possible. Lea will probably be able to provide details.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Armin Ronacher]

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 is human readable (which rst certainly
is) the syntax is surprisingly powerful. You can nest any block tag and I'm not
sure how often you have to nest roles and stuff like that. The goal of the new
docs is a less complex syntax and currently nothing beats reStructuredText in
terms of readability and possibilities.

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 \regexp{<.*>} is matched against
\code{'title'}, it will match the entire string, and not just
\code{''}.  Adding \character{?} after the qualifier makes it
perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as
\emph{few} characters as possible will be matched.  Using \regexp{.*?}
in the previous expression will match only \code{''}.

Here the same in rst:

``*?``, ``+?``, ``??``
   The ``'\*'``, ``'+'``, and ``'?'`` qualifiers are all :dfn:`greedy`;
   they match as much text as possible.  Sometimes this behaviour isn't
   desired; if the RE :regexp:`<.\*>` is matched against
   ``'title'``, it will match the entire string, and not just
   ``''``.  Adding ``'?'`` after the qualifier makes it perform the
   match in :dfn:`non-greedy` or :dfn:`minimal` fashion; as *few*
   characters as possible will be matched.  Using :regexp:`.\*?` in the
   previous expression will match only ``''``.

Regards,
Armin

___
Python-Dev mailing list
Python-Dev@python.org
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

[Stephen J. Turnbull]

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 supports it, but adding support shouldn't be hard.

I don't think even thinking about that is Georg's responsibility, of
course.
___
Python-Dev mailing list
Python-Dev@python.org
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

[Bob Ippolito]

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
> > considered.  I have no idea what tools he used to build his new
> > documentation set.  I only briefly glanced at a couple of the output pages.
> > I think what he has done is marvelous.  However, I don't think the door
> > should be shut on equation display.  Is there a route to it based on the
> > tools Georg is using?
>
> I don't think anything in the world can replace TeX for math
> typesetting. So if math typesetting was a requirement (which it
> should not be, for that very reason), then we could not consider
> anything but TeX.

You can use docutils to generate LaTeX output from reST, and you can
put raw LaTeX into the output with ".. raw:: latex". I would imagine
this is sufficient for now.

-bob
___
Python-Dev mailing list
Python-Dev@python.org
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

[Steven Bethard]

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, and it's far too large and unwieldy. IMHO it would be
> >> much better if only the top-level modules were shown here - having
> >> the single package 'distutils', for example, take up nearly 50
> >> entries in the list is almost certainly hindering a lot more people
> >> than it helps. It would perhaps be better if such packages show up as
> >> one entry, which shows the sub-modules when clicked on.
>
> Georg> Sure, that is certainly possible.
>
> 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 (it uses Myghty - Mason in Python.)

+1 for integrating this with the official docs. I loved this the last
time you posted it too.

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
___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

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

I have no idea if either one has backend support for presentation outside
the web, but if people are interested in this (probably within the docutils
scope) they probably should be considered.  ASCIIMathML in particular is
probably worth using now within even if you can't convert it to any other
format.  It's about as readable as LaTeX source.

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Aahz]

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 it would be much better if only
> the top-level modules were shown here - having the single package
> 'distutils', for example, take up nearly 50 entries in the list is
> almost certainly hindering a lot more people than it helps. It would
> perhaps be better if such packages show up as one entry, which shows
> the sub-modules when clicked on.

That's a good point in general, but I think we want to manually label
some submodules as having entries in the global module index (notably
os.path).
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

"Look, it's your affair if you want to play with five people, but don't
go calling it doubles."  --John Cleese anticipates Usenet
___
Python-Dev mailing list
Python-Dev@python.org
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

[Neal Becker]

[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 description of audioop, AFAIR, an contains a sum
> over Georg> square roots...
> 
> Georg> So, that's not really a concern of mine ;)
> 
> 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.
> 
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.  It happens that for math markup, there
isn't really anything better (or more familiar) than latex.

___
Python-Dev mailing list
Python-Dev@python.org
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

[Fred L. Drake, Jr.]

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 (it uses Myghty - Mason in Python.)

This is very cool.  ;-)


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
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

[Fred L. Drake, Jr.]

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 mailing list
Python-Dev@python.org
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

[skip]

>> 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 better if only the top-level modules were shown here - having
>> the single package 'distutils', for example, take up nearly 50
>> entries in the list is almost certainly hindering a lot more people
>> than it helps. It would perhaps be better if such packages show up as
>> one entry, which shows the sub-modules when clicked on.

Georg> Sure, that is certainly possible.

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 (it uses Myghty - Mason in Python.)

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin v. Löwis]

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, rather than
> ReST, which elements of the the Python community maintain?

No - I have no particular preference wrt. to the markup language.
I can personally live with all of them, and I like none of them.

I hear that contributors complain about having to use TeX, and
I hear other people say that they were more happy if they could
use ReST instead of TeX. Making contributors happy is really what
the objective should be (if the quality of the typesetting output
is adequate - and most people use the HTML output these days,
where latex2html may not have adequate quality).

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.

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin v. Löwis]

> 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 elsewhere.
> 
> 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.

It may be significant for other people, but it is not significant for
the Python documentation.

> They will be
> able to continue to use the old tools, but where will they get them if they
> are no longer part of Python?

We are not going to remove old releases from the net.

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
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

[Martin v. Löwis]

> 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
> documentation set.  I only briefly glanced at a couple of the output pages.
> I think what he has done is marvelous.  However, I don't think the door
> should be shut on equation display.  Is there a route to it based on the
> tools Georg is using?

I don't think anything in the world can replace TeX for math
typesetting. So if math typesetting was a requirement (which it
should not be, for that very reason), then we could not consider
anything but TeX.

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
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

[A.M. Kuchling]

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 big stumbling block in switching away from LaTeX has always been
the effort of making a good conversion; if Georg's work does 80% of
the job, we should definitely take advantage of the opportunity and 
try to switch.

Advantages of reST:

* The required tool chain shrinks (at least if you're not making printed
  output, which will probably still go through LaTeX).
* Tool chain is now more easily scriptable, and it'll be easier to 
  make use of the docs from Python code.
* We can produce XML output through the rst2xml script.

Disadvantages:

* reST markup isn't much simpler than LaTeX.

--amk
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 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 better if only
> the top-level modules were shown here - having the single package
> 'distutils', for example, take up nearly 50 entries in the list is
> almost certainly hindering a lot more people than it helps. It would
> perhaps be better if such packages show up as one entry, which shows
> the sub-modules when clicked on.

Sure, that is certainly possible.

Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Jon Ribbens]

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. 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 better if only
the top-level modules were shown here - having the single package
'distutils', for example, take up nearly 50 entries in the list is
almost certainly hindering a lot more people than it helps. It would
perhaps be better if such packages show up as one entry, which shows
the sub-modules when clicked on.
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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.  They will be
>  > able to continue to use the old tools, but where will they get them if
>  > they are no longer part of Python?
> 
> 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 is a good idea! The converter is not likely to work with other projects
out of the box (it's been finetuned for the Doc/ sources), and it's not clear
whether they would want to switch in any case. Many of the features that the
new system would be able to provide aren't needed for them anyway, and I, as
a maintainer, would be very reluctant to put extra work in that too...


cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

[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 support possible third parties.
> 
> 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.

And that is reasonable, of course.

> I have no idea what tools he used to build his new
> documentation set.  I only briefly glanced at a couple of the output pages.
> I think what he has done is marvelous.  However, I don't think the door
> should be shut on equation display.  Is there a route to it based on the
> tools Georg is using?

In the end, it all depends on what kind of support basic reST can deliver.
IMO, you still get the best math output from LaTeX, but I don't really know
many other things.

That is also something I want to convey: I'm very fond of LaTeX, and use it
regularly for all my University work. For the Python docs, however, I can
see many advantages of the docutils approach.

> If not, then I think some accommodation should be
> made.  I'm being vague here on purpose because I'm unfamiliar with the
> available tools.  The one thing I do know is that LaTeX provides that today
> and by removing it from the toolchain you have removed a significant piece
> of functionality.

That's the point I see differently: for the Python core docs, it's not
significant, and my efforts are primarily limited to that area.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Barry Warsaw]

-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 it does
> not meet their needs, they have to look elsewhere.

I would take a fairly broad view of the term "for Python" though.   
Specifically, third party modules and applications written for and in  
Python should be explicitly supported.  I think we'd like to see one  
(preferred) documentation tool chain for core Python, plus the vast  
number of third party modules and apps.  I don't see any reason why  
Georg's reST-based system couldn't provide that (80/20 rule perhaps?).

I'd point to for example the howto templates, which can be easily  
used for third party applications.  Mailman uses howtos for example.

BTW, Georg excellent work.  I'm a big latex fan and long-time user,  
but I do think that using reST will open the door to a lot more  
contributions.

- -Barry

-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.7 (Darwin)

iQCVAwUBRlHzJXEjvBPtnXfVAQLNXQP/QUuZ2gc/DpoidI9jYt7mr66Z+JYHsslv
fe4CvFSjd9OxwA3eOynd9dSOSkO6QHQPDVomW8axEkJJSHWNosnr9gmDZcC75nAD
JTt4rGImqwkcVIAzE91pZ3fmce/ltp9p1Ru3B1dDRmXbNgHxZ9njaz60MPFszC/H
19jSBo5sqSU=
=hlhi
-END PGP SIGNATURE-
___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 making
> parseable docstrings for auto-generated API documentation using existing tools
> or slightly modified versions thereof. No one is actually contemplating 
> building
> a new tool. AFAICT, Georg's (excellent) work doesn't address that use.

Indeed, I don't intend to do anything about docstrings. IMO, docs automatically
generated from docstrings can work, but only if there's a single consistent
style applied, and the whole thing is written in a markup language, of course,
not text only.

This is not the case for the Python standard library, so converting it is not
an option; in any case, putting all information that is available in the docs
into the docstrings would make many modules much less readable.


> I don't
> think there is anything to coordinate, here. Provided that Georg's system
> doesn't place too many restrictions on the reST it handles, we could use the
> available reST math options if we wanted to use Georg's system.

Of course, for numpy math is much more of importance than for the core.
I'm sure the docutils developers will be supportive in case someone volunteers
to create/improve reST math capabilities.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Georg Brandl]

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 thought that it should be
>>  possible to use those instead of the current LaTeX->latex2html
>>  toolchain.
> 
> Good idea!
> 
> Latex is a barrier for contribution to the docs.  I imagine most
> people would be much better at contributing to the docs in reST.  (Me
> included: I learnt latex at university a couple of decades ago and
> have now forgotten it completely!)
> 
>>  - a "quick-dispatch" function: e.g., docs.python.org/q?os.path.split would
>> redirect you to the matching location.
> 
> 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 pydoc you'll know it reads docstrings and for some
> modules they are great and for others they are sorely lacking.
> 
> If pydoc could show all this documentation as well I'd be very happy!
> 
> Maybe your quick dispatch feature could be added to pydoc too?

It is my intention to work together with Ron Adam to make the pydoc <->
documentation integration as seamless as possible.

>>  Concluding, a small caveat: The conversion/build tools are, of course, not
>>  complete yet. There are a number of XXX comments in the text, most of them
>>  indicate that the converter could not handle a situation -- that would have
>>  to be corrected once after conversion is done.
> 
> It is missing conversion of ``comment'' at the moment as I'm sure you
> know...

Sorry, what did you mean?

> You will need to make your conversion perfect before you convince the
> people who wrote most of that documentation I suspect!

It already is as good as it gets, barring a few bugs here and there.
Which I'd like to hear about, when you find them!

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
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

[Bill Janssen]

> 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 the the Python community maintain?

Bill




___
Python-Dev mailing list
Python-Dev@python.org
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

[Bill Janssen]

> 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.''

Bill
___
Python-Dev mailing list
Python-Dev@python.org
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

[Fred L. Drake, Jr.]

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 use the old tools, but where will they get them if
 > they are no longer part of Python?

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.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

>> 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.

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 elsewhere.

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 use the old tools, but where will they get them if they
are no longer part of Python?

Skip
___
Python-Dev mailing list
Python-Dev@python.org
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

[skip]

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 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
documentation set.  I only briefly glanced at a couple of the output pages.
I think what he has done is marvelous.  However, I don't think the door
should be shut on equation display.  Is there a route to it based on the
tools Georg is using?  If not, then I think some accommodation should be
made.  I'm being vague here on purpose because I'm unfamiliar with the
available tools.  The one thing I do know is that LaTeX provides that today
and by removing it from the toolchain you have removed a significant piece
of functionality.

Skip
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com