Reference guide, and images

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Reference guide, and images

A.M. Kuchling
1) The reference guide occasionally refers to past Python versions,
mentioning that a feature was introduced in such-and-such a version.  
For example, in lexical_analysis.rst:

. [#] In versions of Python prior to 2.4, octal and hexadecimal
   literals in the range just above the largest representable plain
   integer but below the largest unsigned 32-bit number (on a machine
   using 32-bit arithmetic), 4294967296, were taken as the negative
   plain integer obtained by subtracting 4294967296 from their
   unsigned value.

Should the reference guide include this past history, or just describe
the version of Python it's shipped with?

2) With the shift to HTML and Sphinx, it's probably much easier to include
images in the docs.  (I'm thinking of reviving the railroad syntax
diagrams.)  What image format would be best?  Bitmaps (PNG/JPG) or
vector (SVG)?

3) In the 'what's new', I have comments recording bug and patch
numbers, because it's useful information for me.  It strikes me
that this information might be interesting to include as part of
the published HTML.  Does that seem like a good idea?  I envision
something very brief; perhaps the text would read "Contributed by
so-so; <patch #X>.  Can anyone suggest a better rendering?

--amk
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Reference guide, and images

Georg Brandl-2
A.M. Kuchling schrieb:

> 1) The reference guide occasionally refers to past Python versions,
> mentioning that a feature was introduced in such-and-such a version.  
> For example, in lexical_analysis.rst:
>
> .. [#] In versions of Python prior to 2.4, octal and hexadecimal
>    literals in the range just above the largest representable plain
>    integer but below the largest unsigned 32-bit number (on a machine
>    using 32-bit arithmetic), 4294967296, were taken as the negative
>    plain integer obtained by subtracting 4294967296 from their
>    unsigned value.
>
> Should the reference guide include this past history, or just describe
> the version of Python it's shipped with?

Personally, I'm fine with these notes within in the 2.x series. For the
3.0, I'd like to remove them, just as we've removed all versionadded/changed
tags.

> 2) With the shift to HTML and Sphinx, it's probably much easier to include
> images in the docs.  (I'm thinking of reviving the railroad syntax
> diagrams.)  What image format would be best?  Bitmaps (PNG/JPG) or
> vector (SVG)?

PNG would be my choice since it's widely supported and loss-free. SVG
is nice but browser adoption is lousy.

For latex output, PNG works with pdflatex, for postscript I'll have to
whip up a conversion stage.

> 3) In the 'what's new', I have comments recording bug and patch
> numbers, because it's useful information for me.  It strikes me
> that this information might be interesting to include as part of
> the published HTML.  Does that seem like a good idea?  I envision
> something very brief; perhaps the text would read "Contributed by
> so-so; <patch #X>.  Can anyone suggest a better rendering?

Apart from rendering questions, this is something a custom role can do
nicely:

Contributed by Joe; :issue:`9999`.

I'll add one to the custom Python extensions.

Georg

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Reference guide, and images

Georg Brandl-2
Georg Brandl schrieb:

>> 3) In the 'what's new', I have comments recording bug and patch
>> numbers, because it's useful information for me.  It strikes me
>> that this information might be interesting to include as part of
>> the published HTML.  Does that seem like a good idea?  I envision
>> something very brief; perhaps the text would read "Contributed by
>> so-so; <patch #X>.  Can anyone suggest a better rendering?
>
> Apart from rendering questions, this is something a custom role can do
> nicely:
>
> Contributed by Joe; :issue:`9999`.
>
> I'll add one to the custom Python extensions.

Okay, there is now an :issue: directive. Currently it only formats to
"issue XXX"; if you like brackets or different formatting let me know.

Georg

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Reference guide, and images

Paul Moore
On 09/04/2008, Georg Brandl <[hidden email]> wrote:
> Okay, there is now an :issue: directive. Currently it only formats to
>  "issue XXX"; if you like brackets or different formatting let me know.

In HTML, could it be a link to the bug tracker?
Paul
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Reference guide, and images

Georg Brandl-2
Paul Moore schrieb:
> On 09/04/2008, Georg Brandl <[hidden email]> wrote:
>> Okay, there is now an :issue: directive. Currently it only formats to
>>  "issue XXX"; if you like brackets or different formatting let me know.
>
> In HTML, could it be a link to the bug tracker?

It is already; otherwise the role wouldn't have any advantage over writing
out "issue XXX" ;)

Georg

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Reference guide, and images

Paul Moore
On 09/04/2008, Georg Brandl <[hidden email]> wrote:
>  > In HTML, could it be a link to the bug tracker?
>
> It is already; otherwise the role wouldn't have any advantage over writing
>  out "issue XXX" ;)

Doh. Time for me to get some sleep...

Paul.
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig