First documentation skeleton
2 views
Skip to first unread message
Steve Howe
Jun 9, 2005, 3:34:37 AM6/9/05
to cherry...@googlegroups.com
Hello all,
Sorry for the delay. Here are my first documentation drafts - I mean
*really* drafts, just the basic structure and one or other things ready.
Since I'm used to DocBook, I thought I could help by doing the initial
efforts.
Notes:
1) I have used dockbook-xsl 1.68.2 and docbook 4.5, which is the latest
stable (enough) version. We can upgrade to docbook 5.0 later when it
gets mature.
2) The XSLT processor used was xsltproc, which is at least 10x faster
then saxon, but any processor could be used. The command line to compile:
# xsltproc --timing --output index.htm --xinclude stylesheets/onechunk.xsl cherrypy.xml
I guess this gives others some resources to start to play, and later I
plan to make a script to build all target documentations automatically.
There are already stylesheets for onechunk, chunked and htmlhelp
targets.
Note: the stylesheets include absolute paths that match my system.
Anyone could patch that for matching his own system; the build scripts
will fix that automatically in the future.
3) I have made the first level (cherrypy.xml - the book), second level
(preface.xml, tutorial.xml, users.xml, administration.xml,
developers.xml, docs.xml, appendix.xml - the chapters) and some third or
higher level sections. The chapters are:
preface.xml: Preface: Introduction, About, License, Support, etc.
tutorial.xml: Tutorial
users.xml: Users Guide
administration.xml: Administrators Guide
developers.xml: Developers reference/API
docs.xml: Documentation writers
appendix.xml: FAQ, Recipes, Resources, What's New
4) Specially the "users", "admins" and "developers" chapters are pretty
empty and we need to define what should go inside them. Adding new
sections is easy: just use one of the existing section files (such as
introduction) as template. Probably subsections should stay in the saame
file as their parent section to keep number of files reduced - but if a
subsection is very huge, it won't hurt splitting and including it.
By the way, I like the CherryPy 1.0 documentation and although I think
we can do really better, there are lots of things that could be borrowed
from it: it's not a wasted job.
5) I've activated the "use.id.as.filename" flag in the chunked/htmlhelp
stylesheets, so the default file names will be the id names. Every
book/chapter/section will generate a html file for chunked outputs. For
overriding that, use the <?dbhtml filename="xxxx.html"?> directive, as I
did on the cherrypy.xml file.
6) I've also included a basic CSS stylesheet, and we will probably want
to customize it. Is there any good web designer wanting to help us with
it ?
7) Resources:
* For an introduction to using docbook tools, please check:
http://www.sagehill.net/docbookxsl/ToolsSetup.html
* "DocBook 5.0: The Definitive Guide" (reference, including tags)
http://www.docbook.org/tdg5/en/html/docbook.html
Next I'll start making the build scripts.
I took the liberty of assigning some tasks to some of us, but of course
nobody has obligation to do anything and these can be changed at will.
So I think the next steps are:
* Review these files I created; [Sylvain, Remi?]
* Define the topics/sections that should go inside the chapters
[Sylvain, Remi?]
* Write the documentation project guidelines: formatting, styles
[Sylvain]
* Define who will write what [Sylvain, Howe, Remi?]
* Write better the about/copyright/credits sections of the book. I did
a pretty basic work there (if we can call that "work") [Sylvain, Howe,
Remi?]
* Write the Cheetah macros that will be used to [Howe]
* Write the build scripts for all documentation targets [Howe]
* Define the order of topics writing [Sylvain]
* SVN repository access to the documentation writers [Remi].
I personally would like to get a separated SVN repository, so that we
won't mess around with the core CherryPy. Is that possible, Remi ?
--
Best regards,
Steve mailto:ho...@carcass.dhs.org
Sorry for the delay. Here are my first documentation drafts - I mean
*really* drafts, just the basic structure and one or other things ready.
Since I'm used to DocBook, I thought I could help by doing the initial
efforts.
Notes:
1) I have used dockbook-xsl 1.68.2 and docbook 4.5, which is the latest
stable (enough) version. We can upgrade to docbook 5.0 later when it
gets mature.
2) The XSLT processor used was xsltproc, which is at least 10x faster
then saxon, but any processor could be used. The command line to compile:
# xsltproc --timing --output index.htm --xinclude stylesheets/onechunk.xsl cherrypy.xml
I guess this gives others some resources to start to play, and later I
plan to make a script to build all target documentations automatically.
There are already stylesheets for onechunk, chunked and htmlhelp
targets.
Note: the stylesheets include absolute paths that match my system.
Anyone could patch that for matching his own system; the build scripts
will fix that automatically in the future.
3) I have made the first level (cherrypy.xml - the book), second level
(preface.xml, tutorial.xml, users.xml, administration.xml,
developers.xml, docs.xml, appendix.xml - the chapters) and some third or
higher level sections. The chapters are:
preface.xml: Preface: Introduction, About, License, Support, etc.
tutorial.xml: Tutorial
users.xml: Users Guide
administration.xml: Administrators Guide
developers.xml: Developers reference/API
docs.xml: Documentation writers
appendix.xml: FAQ, Recipes, Resources, What's New
4) Specially the "users", "admins" and "developers" chapters are pretty
empty and we need to define what should go inside them. Adding new
sections is easy: just use one of the existing section files (such as
introduction) as template. Probably subsections should stay in the saame
file as their parent section to keep number of files reduced - but if a
subsection is very huge, it won't hurt splitting and including it.
By the way, I like the CherryPy 1.0 documentation and although I think
we can do really better, there are lots of things that could be borrowed
from it: it's not a wasted job.
5) I've activated the "use.id.as.filename" flag in the chunked/htmlhelp
stylesheets, so the default file names will be the id names. Every
book/chapter/section will generate a html file for chunked outputs. For
overriding that, use the <?dbhtml filename="xxxx.html"?> directive, as I
did on the cherrypy.xml file.
6) I've also included a basic CSS stylesheet, and we will probably want
to customize it. Is there any good web designer wanting to help us with
it ?
7) Resources:
* For an introduction to using docbook tools, please check:
http://www.sagehill.net/docbookxsl/ToolsSetup.html
* "DocBook 5.0: The Definitive Guide" (reference, including tags)
http://www.docbook.org/tdg5/en/html/docbook.html
Next I'll start making the build scripts.
I took the liberty of assigning some tasks to some of us, but of course
nobody has obligation to do anything and these can be changed at will.
So I think the next steps are:
* Review these files I created; [Sylvain, Remi?]
* Define the topics/sections that should go inside the chapters
[Sylvain, Remi?]
* Write the documentation project guidelines: formatting, styles
[Sylvain]
* Define who will write what [Sylvain, Howe, Remi?]
* Write better the about/copyright/credits sections of the book. I did
a pretty basic work there (if we can call that "work") [Sylvain, Howe,
Remi?]
* Write the Cheetah macros that will be used to [Howe]
* Write the build scripts for all documentation targets [Howe]
* Define the order of topics writing [Sylvain]
* SVN repository access to the documentation writers [Remi].
I personally would like to get a separated SVN repository, so that we
won't mess around with the core CherryPy. Is that possible, Remi ?
--
Best regards,
Steve mailto:ho...@carcass.dhs.org
Sylvain Hellegouarch
Jun 9, 2005, 4:53:37 AM6/9/05
to cherry...@googlegroups.com
Hi Steve,
Selon Steve Howe <ho...@carcass.dhs.org>:
> Hello all,
>
> Sorry for the delay. Here are my first documentation drafts - I mean
> *really* drafts, just the basic structure and one or other things ready.
> Since I'm used to DocBook, I thought I could help by doing the initial
> efforts.
First of all, no worries for any delay since there is no planning yet :)
Anyway, thank you for this effort and it's quite cool because it was more or
less the structure I had ended up with on my own. I'll give a hint on what I
would change.
>
> Notes:
>
> 1) I have used dockbook-xsl 1.68.2 and docbook 4.5, which is the latest
> stable (enough) version. We can upgrade to docbook 5.0 later when it
> gets mature.
Good though Vex doesn't support it yet. I'll try XXE or simply emacs :)
>
> 2) The XSLT processor used was xsltproc, which is at least 10x faster
> then saxon, but any processor could be used. The command line to compile:
>
> # xsltproc --timing --output index.htm --xinclude stylesheets/onechunk.xsl
> cherrypy.xml
Well, if we need to automate that using Python we'll use 4Suite I think. But it
doesn't really matter so far.
>
> I guess this gives others some resources to start to play, and later I
> plan to make a script to build all target documentations automatically.
> There are already stylesheets for onechunk, chunked and htmlhelp
> targets.
Great. The stylesheet is a really good start. Clear, modern and "breathy" :)
>
> Note: the stylesheets include absolute paths that match my system.
> Anyone could patch that for matching his own system; the build scripts
> will fix that automatically in the future.
>
> 3) I have made the first level (cherrypy.xml - the book), second level
> (preface.xml, tutorial.xml, users.xml, administration.xml,
> developers.xml, docs.xml, appendix.xml - the chapters) and some third or
> higher level sections. The chapters are:
>
> preface.xml: Preface: Introduction, About, License, Support, etc.
> tutorial.xml: Tutorial
> users.xml: Users Guide
> administration.xml: Administrators Guide
> developers.xml: Developers reference/API
> docs.xml: Documentation writers
> appendix.xml: FAQ, Recipes, Resources, What's New
Ok here is what I had come up with :
Preface : Introduction, About, History (which will contain : CherryPy 1.0,
CherryPy 2.0, CherryPy 2.1, etc. Thoe will allow us to explain quickly how Remi
started the project and why he made some changes between version). It'll be a
few lines giving the big story between each version)
Tutorial : Basically close to what the Tutorial already is
I'd like this section to be as clear and simple as possible. It should be based
on a simple application, like a blog for instance (I've just made one really
simple that could be a start). I don't want too much details to be given in
that section. This must be some kind of "copy-paste-run" section. When
finishing reading that section, people should already be in love with CP :)
Users : I guess this part is dealt with the Tutorial section. I'm not still sure
what to do with it.
Developers : Should explain the *all* the concepts of CP in details, it should
also explains the cpg object (request, response, etc.), sessions, cookies, the
config system. Each standard filter should be explained as well with a tested
example and also offer a complete reference on how to build a filter. Basically
it must explain all the key concepts of CP in a comprehensive way.
Administrations : I think this section should describe the different server
solutions
Appendix : Credits, Licenses, Copyright
>
> 4) Specially the "users", "admins" and "developers" chapters are pretty
> empty and we need to define what should go inside them. Adding new
> sections is easy: just use one of the existing section files (such as
> introduction) as template. Probably subsections should stay in the saame
> file as their parent section to keep number of files reduced - but if a
> subsection is very huge, it won't hurt splitting and including it.
I agree.
>
> By the way, I like the CherryPy 1.0 documentation and although I think
> we can do really better, there are lots of things that could be borrowed
> from it: it's not a wasted job.
I don't remember it to be honest. I'll give ita look.
>
> 5) I've activated the "use.id.as.filename" flag in the chunked/htmlhelp
> stylesheets, so the default file names will be the id names. Every
> book/chapter/section will generate a html file for chunked outputs. For
> overriding that, use the <?dbhtml filename="xxxx.html"?> directive, as I
> did on the cherrypy.xml file.
I'm fine with that.
I am good with that as well. My girlfriend is not gonna seeing me a lot in the
next few weeks. ;)
Thanks for the great job Steve. This week end I'll be free and I'll start
working on it a bit more.
- Sylvain
----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.
Selon Steve Howe <ho...@carcass.dhs.org>:
> Hello all,
>
> Sorry for the delay. Here are my first documentation drafts - I mean
> *really* drafts, just the basic structure and one or other things ready.
> Since I'm used to DocBook, I thought I could help by doing the initial
> efforts.
Anyway, thank you for this effort and it's quite cool because it was more or
less the structure I had ended up with on my own. I'll give a hint on what I
would change.
>
> Notes:
>
> 1) I have used dockbook-xsl 1.68.2 and docbook 4.5, which is the latest
> stable (enough) version. We can upgrade to docbook 5.0 later when it
> gets mature.
>
> 2) The XSLT processor used was xsltproc, which is at least 10x faster
> then saxon, but any processor could be used. The command line to compile:
>
> # xsltproc --timing --output index.htm --xinclude stylesheets/onechunk.xsl
> cherrypy.xml
doesn't really matter so far.
>
> I guess this gives others some resources to start to play, and later I
> plan to make a script to build all target documentations automatically.
> There are already stylesheets for onechunk, chunked and htmlhelp
> targets.
>
> Note: the stylesheets include absolute paths that match my system.
> Anyone could patch that for matching his own system; the build scripts
> will fix that automatically in the future.
>
> 3) I have made the first level (cherrypy.xml - the book), second level
> (preface.xml, tutorial.xml, users.xml, administration.xml,
> developers.xml, docs.xml, appendix.xml - the chapters) and some third or
> higher level sections. The chapters are:
>
> preface.xml: Preface: Introduction, About, License, Support, etc.
> tutorial.xml: Tutorial
> users.xml: Users Guide
> administration.xml: Administrators Guide
> developers.xml: Developers reference/API
> docs.xml: Documentation writers
> appendix.xml: FAQ, Recipes, Resources, What's New
Preface : Introduction, About, History (which will contain : CherryPy 1.0,
CherryPy 2.0, CherryPy 2.1, etc. Thoe will allow us to explain quickly how Remi
started the project and why he made some changes between version). It'll be a
few lines giving the big story between each version)
Tutorial : Basically close to what the Tutorial already is
I'd like this section to be as clear and simple as possible. It should be based
on a simple application, like a blog for instance (I've just made one really
simple that could be a start). I don't want too much details to be given in
that section. This must be some kind of "copy-paste-run" section. When
finishing reading that section, people should already be in love with CP :)
Users : I guess this part is dealt with the Tutorial section. I'm not still sure
what to do with it.
Developers : Should explain the *all* the concepts of CP in details, it should
also explains the cpg object (request, response, etc.), sessions, cookies, the
config system. Each standard filter should be explained as well with a tested
example and also offer a complete reference on how to build a filter. Basically
it must explain all the key concepts of CP in a comprehensive way.
Administrations : I think this section should describe the different server
solutions
Appendix : Credits, Licenses, Copyright
>
> 4) Specially the "users", "admins" and "developers" chapters are pretty
> empty and we need to define what should go inside them. Adding new
> sections is easy: just use one of the existing section files (such as
> introduction) as template. Probably subsections should stay in the saame
> file as their parent section to keep number of files reduced - but if a
> subsection is very huge, it won't hurt splitting and including it.
>
> By the way, I like the CherryPy 1.0 documentation and although I think
> we can do really better, there are lots of things that could be borrowed
> from it: it's not a wasted job.
>
> 5) I've activated the "use.id.as.filename" flag in the chunked/htmlhelp
> stylesheets, so the default file names will be the id names. Every
> book/chapter/section will generate a html file for chunked outputs. For
> overriding that, use the <?dbhtml filename="xxxx.html"?> directive, as I
> did on the cherrypy.xml file.
next few weeks. ;)
>
> I personally would like to get a separated SVN repository, so that we
> won't mess around with the core CherryPy. Is that possible, Remi ?
I still don't know about that. I haven't made my mind yet. remi?
> I personally would like to get a separated SVN repository, so that we
> won't mess around with the core CherryPy. Is that possible, Remi ?
Thanks for the great job Steve. This week end I'll be free and I'll start
working on it a bit more.
- Sylvain
----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.
Steve Howe
Jun 9, 2005, 5:35:46 AM6/9/05
to Sylvain Hellegouarch
Hello Sylvain,
Thursday, June 9, 2005, 5:53:37 AM, you wrote:
> First of all, no worries for any delay since there is no planning yet :)
I planned to release it yesterday, but due to docbook issues, I had to
postpone my plans...
> Good though Vex doesn't support it yet. I'll try XXE or simply emacs :)
Vim has great XML support, and I know Emcas has too, but I use Jedit
which has a visual XML validating plugin, great stuff, works well for
me.
> Great. The stylesheet is a really good start. Clear, modern and "breathy" :)
Thanks. I actually use it on final users documentation.
> Ok here is what I had come up with :
> Preface : Introduction, About, History (which will contain : CherryPy 1.0,
> CherryPy 2.0, CherryPy 2.1, etc. Thoe will allow us to explain quickly how Remi
> started the project and why he made some changes between version). It'll be a
> few lines giving the big story between each version)
I have thought in "History"/"Changelog"/"What's New" on the appendix and
not on preface. On Preface I would expect more introductory stuff. For
instance, on the PostgreSQL manuals, it's on the Appendix. On the Python
documentations, it's a separate book, however.
> Tutorial : Basically close to what the Tutorial already is
> I'd like this section to be as clear and simple as possible. It should be based
> on a simple application, like a blog for instance (I've just made one really
> simple that could be a start). I don't want too much details to be given in
> that section. This must be some kind of "copy-paste-run" section. When
> finishing reading that section, people should already be in love with CP :)
Well, I agree and have a suggestion... I read somewhere Remi's own
description of planning CherryPy, why did he made each decision, etc.
That's perfect material for convincing users that CherryPy is actually
great. Remi, can use use that ? Do you know what document I'm talking
about ? I can't find the url anymore :(
> Users : I guess this part is dealt with the Tutorial section. I'm not still sure
> what to do with it.
> Developers : Should explain the *all* the concepts of CP in details, it should
> also explains the cpg object (request, response, etc.), sessions, cookies, the
> config system. Each standard filter should be explained as well with a tested
> example and also offer a complete reference on how to build a filter. Basically
> it must explain all the key concepts of CP in a comprehensive way.
I would think that users are those who do not care about the internals,
while developers do. Perhaps we should split in "Reference" and
"Internals" sections ?
> Administrations : I think this section should describe the different server
> solutions
And CherryPy installation (which is pretty much a python setup.py
install, allright). We should probably pint out how to fetch a snapshot
from SVN, too - or point the web page that shows how to do it.
> Appendix : Credits, Licenses, Copyright
What about the FAQ and Recipes ?
I think the most important step now is having a good definition of the
topis to be written. If we do a mess here, the whole project will be a
mess too. It will worth to spend some time on a more careful planning on
those.
> Thanks for the great job Steve. This week end I'll be free and I'll start
> working on it a bit more.
Ok, thanks. I'll have a pretty busy weekend so don't expect much
development from me, but I might end up finding time to the build
script and/or the macros.
Thursday, June 9, 2005, 5:53:37 AM, you wrote:
> First of all, no worries for any delay since there is no planning yet :)
postpone my plans...
> Good though Vex doesn't support it yet. I'll try XXE or simply emacs :)
which has a visual XML validating plugin, great stuff, works well for
me.
> Great. The stylesheet is a really good start. Clear, modern and "breathy" :)
> Ok here is what I had come up with :
> Preface : Introduction, About, History (which will contain : CherryPy 1.0,
> CherryPy 2.0, CherryPy 2.1, etc. Thoe will allow us to explain quickly how Remi
> started the project and why he made some changes between version). It'll be a
> few lines giving the big story between each version)
not on preface. On Preface I would expect more introductory stuff. For
instance, on the PostgreSQL manuals, it's on the Appendix. On the Python
documentations, it's a separate book, however.
> Tutorial : Basically close to what the Tutorial already is
> I'd like this section to be as clear and simple as possible. It should be based
> on a simple application, like a blog for instance (I've just made one really
> simple that could be a start). I don't want too much details to be given in
> that section. This must be some kind of "copy-paste-run" section. When
> finishing reading that section, people should already be in love with CP :)
description of planning CherryPy, why did he made each decision, etc.
That's perfect material for convincing users that CherryPy is actually
great. Remi, can use use that ? Do you know what document I'm talking
about ? I can't find the url anymore :(
> Users : I guess this part is dealt with the Tutorial section. I'm not still sure
> what to do with it.
> Developers : Should explain the *all* the concepts of CP in details, it should
> also explains the cpg object (request, response, etc.), sessions, cookies, the
> config system. Each standard filter should be explained as well with a tested
> example and also offer a complete reference on how to build a filter. Basically
> it must explain all the key concepts of CP in a comprehensive way.
while developers do. Perhaps we should split in "Reference" and
"Internals" sections ?
> Administrations : I think this section should describe the different server
> solutions
install, allright). We should probably pint out how to fetch a snapshot
from SVN, too - or point the web page that shows how to do it.
> Appendix : Credits, Licenses, Copyright
What about the FAQ and Recipes ?
I think the most important step now is having a good definition of the
topis to be written. If we do a mess here, the whole project will be a
mess too. It will worth to spend some time on a more careful planning on
those.
> Thanks for the great job Steve. This week end I'll be free and I'll start
> working on it a bit more.
development from me, but I might end up finding time to the build
script and/or the macros.
Sylvain Hellegouarch
Jun 9, 2005, 5:48:38 AM6/9/05
to cherry...@googlegroups.com
> Vim has great XML support, and I know Emcas has too, but I use Jedit
> which has a visual XML validating plugin, great stuff, works well for
> me.
> I have thought in "History"/"Changelog"/"What's New" on the appendix and
> not on preface. On Preface I would expect more introductory stuff. For
> instance, on the PostgreSQL manuals, it's on the Appendix. On the Python
> documentations, it's a separate book, however.
put those topics at the end in the Appendix, I'm fine with it.
> Well, I agree and have a suggestion... I read somewhere Remi's own
> description of planning CherryPy, why did he made each decision, etc.
> That's perfect material for convincing users that CherryPy is actually
> great. Remi, can use use that ? Do you know what document I'm talking
> about ? I can't find the url anymore :(
http://pythonjournal.cognizor.com/pyj3.1/cherrypy/CherryPy2.html
This is exactly what I am talking about. We should definitely have a section
where we explain (with a certain leel of details) why we moved to this or that
direction. This will avoid question like "Bu why didn't you choose that path?"
It shows each step has been carefully thought.
> I would think that users are those who do not care about the internals,
> while developers do. Perhaps we should split in "Reference" and
> "Internals" sections ?
> And CherryPy installation (which is pretty much a python setup.py
> install, allright). We should probably pint out how to fetch a snapshot
> from SVN, too - or point the web page that shows how to do it.
> What about the FAQ and Recipes ?
>
> I think the most important step now is having a good definition of the
> topis to be written. If we do a mess here, the whole project will be a
> mess too. It will worth to spend some time on a more careful planning on
> those.
> Ok, thanks. I'll have a pretty busy weekend so don't expect much
> development from me, but I might end up finding time to the build
> script and/or the macros.
Bernard Jauregui
Jun 9, 2005, 5:48:21 AM6/9/05
to cherry...@googlegroups.com
I'm new to DocBook and am finding the information online a bit confusing.
Can anyone recommend a toolchain for Windows? I would like to contribute to
this project by reviewing, supplementing and even writing new material.
I have been experimenting with Eclipse, but have so far spent more time
learning DocBook than I have CherryPy.
Cheers
BJ
--
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.323 / Virus Database: 267.6.6 - Release Date: 08-Jun-05
Remi Delon
Jun 9, 2005, 11:56:27 AM6/9/05
to cherry...@googlegroups.com
>>Well, I agree and have a suggestion... I read somewhere Remi's own
>>description of planning CherryPy, why did he made each decision, etc.
>>That's perfect material for convincing users that CherryPy is actually
>>great. Remi, can use use that ? Do you know what document I'm talking
>>about ? I can't find the url anymore :(
>
> I think you mean that one :
> http://pythonjournal.cognizor.com/pyj3.1/cherrypy/CherryPy2.html
Sure, you can copy stuff from that article, but the article is quite old
>>description of planning CherryPy, why did he made each decision, etc.
>>That's perfect material for convincing users that CherryPy is actually
>>great. Remi, can use use that ? Do you know what document I'm talking
>>about ? I can't find the url anymore :(
>
> I think you mean that one :
> http://pythonjournal.cognizor.com/pyj3.1/cherrypy/CherryPy2.html
and a lot of things don't hold true anymore ...
>>I think the most important step now is having a good definition of the
>>topis to be written. If we do a mess here, the whole project will be a
>>mess too. It will worth to spend some time on a more careful planning on
>>those.
>
> I totally agree. We shouldn't write anything before having a clear tree in mind.
For the Subversion layout, I think the docs should be under
cherrypy/docs. I think it's best if the docs stay really close to the
code in Subversion, this way docs follow the same workflow as the code
(versions, branches, merges, ...)
As for subversion users, I'll just add people who want to contribute to
the docus as they ask (as long as they've shown that they know what
they're doing :-) )
Remi.
Steve Howe
Jun 9, 2005, 2:58:15 PM6/9/05
to Sylvain Hellegouarch
Hello Sylvain,
Thursday, June 9, 2005, 6:48:38 AM, you wrote:
>> Vim has great XML support, and I know Emcas has too, but I use Jedit
>> which has a visual XML validating plugin, great stuff, works well for
>> me.
> I usually work with emacs for all my devel.
>> I have thought in "History"/"Changelog"/"What's New" on the appendix and
>> not on preface. On Preface I would expect more introductory stuff. For
>> instance, on the PostgreSQL manuals, it's on the Appendix. On the Python
>> documentations, it's a separate book, however.
> That's a good point. I'm not to strict on that one so if it makes more sens to
> put those topics at the end in the Appendix, I'm fine with it.
>> Well, I agree and have a suggestion... I read somewhere Remi's own
>> description of planning CherryPy, why did he made each decision, etc.
>> That's perfect material for convincing users that CherryPy is actually
>> great. Remi, can use use that ? Do you know what document I'm talking
>> about ? I can't find the url anymore :(
> I think you mean that one :
> http://pythonjournal.cognizor.com/pyj3.1/cherrypy/CherryPy2.html
Yes, that one.
> This is exactly what I am talking about. We should definitely have a section
> where we explain (with a certain leel of details) why we moved to this or that
> direction. This will avoid question like "Bu why didn't you choose that path?"
> It shows each step has been carefully thought.
My idea was to make people understand that CheerryPy is really nice, but
this is another argument, too... anyway the comments "why didn't you do
this, why didn't you do that" will always be there...
> I'd rather have them splitted from the main doc.
That's another idea. Will we move them to different books ? Or keep them
all in the wiki ? I'd prefer to have them in separate books...
Thursday, June 9, 2005, 6:48:38 AM, you wrote:
>> Vim has great XML support, and I know Emcas has too, but I use Jedit
>> which has a visual XML validating plugin, great stuff, works well for
>> me.
> I usually work with emacs for all my devel.
>> I have thought in "History"/"Changelog"/"What's New" on the appendix and
>> not on preface. On Preface I would expect more introductory stuff. For
>> instance, on the PostgreSQL manuals, it's on the Appendix. On the Python
>> documentations, it's a separate book, however.
> That's a good point. I'm not to strict on that one so if it makes more sens to
> put those topics at the end in the Appendix, I'm fine with it.
>> Well, I agree and have a suggestion... I read somewhere Remi's own
>> description of planning CherryPy, why did he made each decision, etc.
>> That's perfect material for convincing users that CherryPy is actually
>> great. Remi, can use use that ? Do you know what document I'm talking
>> about ? I can't find the url anymore :(
> I think you mean that one :
> http://pythonjournal.cognizor.com/pyj3.1/cherrypy/CherryPy2.html
> This is exactly what I am talking about. We should definitely have a section
> where we explain (with a certain leel of details) why we moved to this or that
> direction. This will avoid question like "Bu why didn't you choose that path?"
> It shows each step has been carefully thought.
this is another argument, too... anyway the comments "why didn't you do
this, why didn't you do that" will always be there...
> I'd rather have them splitted from the main doc.
all in the wiki ? I'd prefer to have them in separate books...
Steve Howe
Jun 9, 2005, 3:01:30 PM6/9/05
to Remi Delon
Hello Remi,
Thursday, June 9, 2005, 12:56:27 PM, you wrote:
> Well, the current tree looks pretty good to me ...
Perhaps the up to second level, yes... but there is almost nothing
defined for the most important parts: Reference and Internals.
> For the Subversion layout, I think the docs should be under
> cherrypy/docs. I think it's best if the docs stay really close to the
> code in Subversion, this way docs follow the same workflow as the code
> (versions, branches, merges, ...)
Ok, not a problem for me, specially if it makes easier for you to admin.
> As for subversion users, I'll just add people who want to contribute to
> the docus as they ask (as long as they've shown that they know what
> they're doing :-) )
Ok, indeed...
Thursday, June 9, 2005, 12:56:27 PM, you wrote:
> Well, the current tree looks pretty good to me ...
defined for the most important parts: Reference and Internals.
> For the Subversion layout, I think the docs should be under
> cherrypy/docs. I think it's best if the docs stay really close to the
> code in Subversion, this way docs follow the same workflow as the code
> (versions, branches, merges, ...)
> As for subversion users, I'll just add people who want to contribute to
> the docus as they ask (as long as they've shown that they know what
> they're doing :-) )
Sylvain Hellegouarch
Jun 11, 2005, 10:02:36 AM6/11/05
to cherry...@googlegroups.com
Hi guys,
Review the documentation structure please:
http://www.cherrypy.org/wiki/DocProject
Once it's OK for everyone, we will set it up the docbook document tree from what
Steve already did. Then we will add it to the SVN trunk.
Thanks
Review the documentation structure please:
http://www.cherrypy.org/wiki/DocProject
Once it's OK for everyone, we will set it up the docbook document tree from what
Steve already did. Then we will add it to the SVN trunk.
Thanks
Reply all
Reply to author
Forward
0 new messages