Re: [Jython-dev] Proposal for new Jython User Guide - TOC

i am also interested to contribute to the New jython User Guide-TOC=0Athank=
s a lot.=0A=0A=0A----- Original Message ----=0AFrom: Frank Wierzbicki <fwie=
rzbicki@...>=0ATo: Dave Kuhlman <dkuhlman@...>=0ACc: jython-dev@=
lists.sourceforge.net=0ASent: Friday, 21 September, 2007 7:22:54 AM=0ASubje=
ct: Re: [Jython-dev] Proposal for new Jython User Guide - TOC=0A=0AOn 9/20/=
07, Dave Kuhlman <dkuhlman@...> wrote:=0A> Looks like it was generated=
from reST (RestructuredText), which is also what I=0A> use for my course n=
otes. So, one approach is to use standard reST (and pay a=0A> little atten=
tion to the model set by the old UG), then apply the same style CSS=0A> she=
et to our docs. That will give us a consistent look.=0A>=0A> Are we agreed=
that reST and Docutils is our preferred document format?=0AWell, it is at =
least *my* preferred format :) -- I did the initial=0Atranslation from the =
old site into ReStructuredText, and am very fond=0Aof the format. I have a=
long term goal of moving to the same system=0Athat python.org uses, which =
is at least partially based on this=0AReStructuredText, although I'm fuzzy =
on details (about python.orgs=0Awebsite setup).=0A=0A-Frank=0A=0A----------=
---------------------------------------------------------------=0AThis SF.n=
et email is sponsored by: Microsoft=0ADefy all challenges. Microsoft(R) Vis=
ual Studio 2005.=0Ahttp://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/=
=0A_______________________________________________=0AJython-dev mailing lis=
t=0AJython-dev@...=0Ahttps://lists.sourceforge.net/lists/=
listinfo/jython-dev=0A=0A=0A=0A=0A=0A=0A=0A Bring your gang together -=
do your thing. Go to http://in.promos.yahoo.com/groups

Thread view

See below:
Regards,=20
Greg.
> -----Original Message-----
> From: Dave Kuhlman [mailto:dkuhlman@...]
> Sent: Thursday, September 20, 2007 10:50 AM
[snip]
> I'm starting to do a little thinking on this. I think that the
> part of my class notes that need the most attention *for my
> purposes* are the sections on extending Jython with Java and
> embedding Jython in Java (Section 3, in your TOC). So, my first
> suggestion would be to ask you to give me some guidance about what
> stylistic and formatting changes you would suggest, and then let
> me work on those sections (extending and embedding).
Dave, That would be great. The embedding and extending part was the part
I was concerned about since I don't feel I know enough to write
effectively about it.
As for stylistic and formatting changes, well I haven't thought too much
along those lines, I've been more in the content mode. I'm not sure if
the Jython project has a defined style. Frank, Charlie or one of the
others may be a better resource for that. Guys, Do we have a "style
sheet" or is it, as long as it looks good its ok?=20
I think my biggest thing is making sure there is a logical flow and that
concepts flow from one into the next. Personally I don't like it when an
writer introduces a new concept and then says something like 'we'll
cover that later...' or a topic gets spread across multiple chapters.
For example, no offence intended Dave, in 'Learning Jyhton', doc strings
are covered in 3 or more separate places. Doc strings aren't *that*
complicated. :)
That being say I do like the general format of your document, Dave and
thinking to formatting the rest of the JUG like that might be the way
go.
> [snip]
> > Do you think we should merge the 2 documents first? Or merge as we
go?
> >
>=20
> I'm not too sure. From my point of view, perhaps keeping them
> separate for awhile makes most sense. That way I can work on
> updating my course notes/materials in preperation for my next class
> *and* hope to contribute that work to (insert it into) the new
> Jython user guide a little later.
That makes sense. Sounds good to me. I appreciate your contribution thus
far. :)
> [snip]
> > > Sounds good. But, it might be difficult to keep it quick/brief
> > > *and* provide enough explanation so that it is meaningful.
> >
> > Yes, I agree. That why I don't think I'd expand much more then what
> > you've done. At the moment I cant think what that might be but...
>=20
> So, perhaps we want to try at each "bullet point" or minor topic is
> to (1) give a hint of an explanation and (2) provide a link to
> documentation elsewhere.
I think just a brief explanation. Maybe an example. I was thinking along
the lines of linking into the Python docs on python.org. But would that
make this less useful for people that want to print it out? Do we want
to worry about that when it easily available online? What I don't want
is a rehash/duplication of the Python docs that's pointless. It might
get redundant but having a like that was something like: for further
help (information?) on <TOPIC> please see docs.python.org/[topic link]
[snip]
>=20
> Dave
>=20
> --
> Dave Kuhlman
> http://www.rexx.com/~dkuhlman
This message and any attachments are intended only for the use of the add=
ressee and may contain information that is privileged and confidential. I=
f the reader of the message is not the intended recipient or an authorize=
d representative of the intended recipient, you are hereby notified that =
any dissemination of this communication is strictly prohibited. If you ha=
ve received this communication in error, please notify us immediately by =
e-mail and delete the message and any attachments from your system.

i am also interested to contribute to the New jython User Guide-TOC=0Athank=
s a lot.=0A=0A=0A----- Original Message ----=0AFrom: Frank Wierzbicki <fwie=
rzbicki@...>=0ATo: Dave Kuhlman <dkuhlman@...>=0ACc: jython-dev@=
lists.sourceforge.net=0ASent: Friday, 21 September, 2007 7:22:54 AM=0ASubje=
ct: Re: [Jython-dev] Proposal for new Jython User Guide - TOC=0A=0AOn 9/20/=
07, Dave Kuhlman <dkuhlman@...> wrote:=0A> Looks like it was generated=
from reST (RestructuredText), which is also what I=0A> use for my course n=
otes. So, one approach is to use standard reST (and pay a=0A> little atten=
tion to the model set by the old UG), then apply the same style CSS=0A> she=
et to our docs. That will give us a consistent look.=0A>=0A> Are we agreed=
that reST and Docutils is our preferred document format?=0AWell, it is at =
least *my* preferred format :) -- I did the initial=0Atranslation from the =
old site into ReStructuredText, and am very fond=0Aof the format. I have a=
long term goal of moving to the same system=0Athat python.org uses, which =
is at least partially based on this=0AReStructuredText, although I'm fuzzy =
on details (about python.orgs=0Awebsite setup).=0A=0A-Frank=0A=0A----------=
---------------------------------------------------------------=0AThis SF.n=
et email is sponsored by: Microsoft=0ADefy all challenges. Microsoft(R) Vis=
ual Studio 2005.=0Ahttp://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/=
=0A_______________________________________________=0AJython-dev mailing lis=
t=0AJython-dev@...=0Ahttps://lists.sourceforge.net/lists/=
listinfo/jython-dev=0A=0A=0A=0A=0A=0A=0A=0A Bring your gang together -=
do your thing. Go to http://in.promos.yahoo.com/groups

Jeff,=20
Thanks. That's great!
Frank. I think you're the keeper of the server. Would you add this code?
Regards,
Greg.
> -----Original Message-----
> From: Jeff Rush [mailto:jeff@...]
> Sent: Friday, September 21, 2007 9:37 AM
> To: Moore, Greg
> Cc: Frank Wierzbicki; Dave Kuhlman; jython-dev@...
> Subject: Re: [Jython-dev] Proposal for new Jython User Guide - TOC
>=20
> >> -----Original Message-----
> >> From: Frank Wierzbicki
> >> Sent: Thursday, September 20, 2007 6:53 PM
> >> Subject: Re: [Jython-dev] Proposal for new Jython User Guide - TOC
> >
> > Yes, I think using reST and the docutils are the way to go. I've had
> > little experience with it but from what I've read it looks pretty
> > simple. There is only one thing that may get lost which would be
> > unfortunate (but not tragic) and thats the syntax highlighting for
code
> > examples. With the Wiki formatting you can use {{{#!python but I
haven't
> > come across something similar for reST. Does the restructured text
have
> > any syntax highlighting/coloring features?
>=20
> Yes, you can do syntax highlighting:
>=20
> "Using Pygments in ReST documents"
> http://pygments.org/docs/rstdirective/
>=20
> -Jeff
This message and any attachments are intended only for the use of the add=
ressee and may contain information that is privileged and confidential. I=
f the reader of the message is not the intended recipient or an authorize=
d representative of the intended recipient, you are hereby notified that =
any dissemination of this communication is strictly prohibited. If you ha=
ve received this communication in error, please notify us immediately by =
e-mail and delete the message and any attachments from your system.

On 9/21/07, Moore, Greg <Greg_W_Moore@...> wrote:
>
> Jeff,
> Thanks. That's great!
>
> Frank. I think you're the keeper of the server. Would you add this code?
I think that this is doable -- though probably not on the wiki (I'm
not the keeper of the wiki, that's hosted by python.org) but I think I
would be able to add this to the script that generates the web page
when we get to that point.
-Frank

Moore, Greg <Greg_W_Moore <at> adp.com> writes:
>
> As for stylistic and formatting changes, well I haven't thought too much
> along those lines, I've been more in the content mode. I'm not sure if
> the Jython project has a defined style. Frank, Charlie or one of the
> others may be a better resource for that. Guys, Do we have a "style
> sheet" or is it, as long as it looks good its ok?
I'm looking at the old Jython User Guide (the one at:
http://www.jython.org/Project/userguide.html).
Looks like it was generated from reST (RestructuredText), which is also what I
use for my course notes. So, one approach is to use standard reST (and pay a
little attention to the model set by the old UG), then apply the same style CSS
sheet to our docs. That will give us a consistent look.
Are we agreed that reST and Docutils is our preferred document format?
The existing/old user guide is, by the way, very useful. Greg has talked about
merging the old and new UGs. So, I need to do some thinking about how to
rearrange my document so as to make doing that merger easy.
>
> I think my biggest thing is making sure there is a logical flow and that
> concepts flow from one into the next. Personally I don't like it when an
> writer introduces a new concept and then says something like 'we'll
> cover that later...' or a topic gets spread across multiple chapters.
> For example, no offence intended Dave, in 'Learning Jyhton', doc strings
> are covered in 3 or more separate places. Doc strings aren't *that*
> complicated. :)
>
Point taken. I've added an item to my to-do list.
> I think just a brief explanation. Maybe an example. I was thinking along
> the lines of linking into the Python docs on python.org. But would that
> make this less useful for people that want to print it out? Do we want
> to worry about that when it easily available online? What I don't want
> is a rehash/duplication of the Python docs that's pointless. It might
> get redundant but having a like that was something like: for further
> help (information?) on <TOPIC> please see docs.python.org/[topic link]
Yes. I agree. (1) It would be a shame not to re-use good documentation that
is already at http://www.python.org/docs and (2) we want to use the power of the Web.
Dave

On 9/20/07, Dave Kuhlman <dkuhlman@...> wrote:
> Looks like it was generated from reST (RestructuredText), which is also what I
> use for my course notes. So, one approach is to use standard reST (and pay a
> little attention to the model set by the old UG), then apply the same style CSS
> sheet to our docs. That will give us a consistent look.
>
> Are we agreed that reST and Docutils is our preferred document format?
Well, it is at least *my* preferred format :) -- I did the initial
translation from the old site into ReStructuredText, and am very fond
of the format. I have a long term goal of moving to the same system
that python.org uses, which is at least partially based on this
ReStructuredText, although I'm fuzzy on details (about python.orgs
website setup).
-Frank

See below
> -----Original Message-----
> From: Frank Wierzbicki
> Sent: Thursday, September 20, 2007 6:53 PM
> Subject: Re: [Jython-dev] Proposal for new Jython User Guide - TOC
>=20
> On 9/20/07, Dave Kuhlman <dkuhlman@...> wrote:
> > Looks like it was generated from reST (RestructuredText), which is
also
> > what I
> > use for my course notes. So, one approach is to use standard reST
(and
> >pay a little attention to the model set by the old UG), then apply
the
> > same style CSS sheet to our docs. That will give us a consistent
look.
> >
> > Are we agreed that reST and Docutils is our preferred document
format?
> Well, it is at least *my* preferred format :) -- I did the initial
> translation from the old site into ReStructuredText, and am very fond
> of the format. I have a long term goal of moving to the same system
> that python.org uses, which is at least partially based on this
> ReStructuredText, although I'm fuzzy on details (about python.orgs
> website setup).
Yes, I think using reST and the docutils are the way to go. I've had
little experience with it but from what I've read it looks pretty
simple. There is only one thing that may get lost which would be
unfortunate (but not tragic) and thats the syntax highlighting for code
examples. With the Wiki formatting you can use {{{#!python but I haven't
come across something similar for reST. Does the restructured text have
any syntax highlighting/coloring features?
Just for the record, I especially don't want to loose any information in
the existing Jython User Guide. It is very valuable, my only intent is
to expand on what already there.
Regards,
Greg.
This message and any attachments are intended only for the use of the add=
ressee and may contain information that is privileged and confidential. I=
f the reader of the message is not the intended recipient or an authorize=
d representative of the intended recipient, you are hereby notified that =
any dissemination of this communication is strictly prohibited. If you ha=
ve received this communication in error, please notify us immediately by =
e-mail and delete the message and any attachments from your system.

>> -----Original Message-----
>> From: Frank Wierzbicki
>> Sent: Thursday, September 20, 2007 6:53 PM
>> Subject: Re: [Jython-dev] Proposal for new Jython User Guide - TOC
>
> Yes, I think using reST and the docutils are the way to go. I've had
> little experience with it but from what I've read it looks pretty
> simple. There is only one thing that may get lost which would be
> unfortunate (but not tragic) and thats the syntax highlighting for code
> examples. With the Wiki formatting you can use {{{#!python but I haven't
> come across something similar for reST. Does the restructured text have
> any syntax highlighting/coloring features?
Yes, you can do syntax highlighting:
"Using Pygments in ReST documents"
http://pygments.org/docs/rstdirective/
-Jeff

On 9/20/07, Dave Kuhlman <dkuhlman@...> wrote:
> Moore, Greg <Greg_W_Moore <at> adp.com> writes:
> >
> > As for stylistic and formatting changes, well I haven't thought too much
> > along those lines, I've been more in the content mode. I'm not sure if
> > the Jython project has a defined style. Frank, Charlie or one of the
> > others may be a better resource for that. Guys, Do we have a "style
> > sheet" or is it, as long as it looks good its ok?
>
> Are we agreed that reST and Docutils is our preferred document format?
+1 from me.
Charlie

On Thu, Sep 20, 2007 at 11:45:15PM +0000, Dave Kuhlman wrote:
> Are we agreed that reST and Docutils is our preferred document format?
Note that Python 2.6 has switched to using reST, so it would be pretty
easy to incorporate material from the tutorial, library reference, or
whatever. The resulting output from the 2.6 documentation is at
http://docs.python.org/dev/ and looks quite different from the 2.5 docs.
--amk