You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Stas Bekman <st...@stason.org> on 2002/05/11 14:30:52 UTC
content layout freeze
Folks, thanks to Thomas we have reshuffled a big chunk of the content.
See the updated version here:
http://perl.apache.org/preview/modperl-docs/dst_html/docs/tutorials/index.html
Please verify that we didn't lose anything while moving, and that you
are happy with how the docs are laid out now.
We want to freeze the docs movement, finalize the design and proceed
with the preview stage. that's a release candidate modperl-docs-RC1.
Thanks!
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> I'll still try to begin writing tutorials sometime. It's not really a
> matter of getting the info to the users, but getting users interested in
> the info. mod_perl is pretty daunting to learn, and it would be nice to
> make the first steps seem easy.
Absolutely! Go for it.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 13:54 19.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
> > At 12:35 19.05.2002, Stas Bekman wrote:
> >> come'n, the installation guide in the guide, does do handholding
> >> already. So does getwet.pod.
> >
> >
> > Yes, but it's pretty damn big, and some users are relucatant to
> > reading anything big.
>
>getwet is small.
Yeah, true.
>those who want the knowledge come to them magically applying zero effort
>won't be able to use mod_perl in any case. so I won't worry much here.
Yup, ok..
I'll still try to begin writing tutorials sometime. It's not really a
matter of getting the info to the users, but getting users interested in
the info. mod_perl is pretty daunting to learn, and it would be nice to
make the first steps seem easy.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 12:35 19.05.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 10:23 19.05.2002, Stas Bekman wrote:
>>>
>>>> We shouldn't carry away with newbies. After all the online docs
>>>> are mainly for those who need to use the docs on the daily
>>>> basis. If we push too much newbies stuff that stands on the way
>>>> of those who need the real docs, that would be bad. Making a
>>>> better and fatter /start is fine.
>>>
>>>
>>> Yes, that's completely agreed. While maybe not a fatter /start
>>> (which is after all more a place to show off mod_perl's
>>> conciseness than try to each something), beginners like tutorials
>>> that take you through mod_perl one step at a time, a little like
>>> what you post regularly to other sites (although I know, you just
>>> arrange the guide slightly, but it's still more inviting).
>>
>>
>> come'n, the installation guide in the guide, does do handholding
>> already. So does getwet.pod.
>
>
> Yes, but it's pretty damn big, and some users are relucatant to
> reading anything big.
getwet is small.
those who want the knowledge come to them magically applying zero effort
won't be able to use mod_perl in any case. so I won't worry much here.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 12:35 19.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 10:23 19.05.2002, Stas Bekman wrote:
>>
>>>We shouldn't carry away with newbies. After all the online docs are
>>>mainly for those who need to use the docs on the daily basis. If we push
>>>too much newbies stuff that stands on the way of those who need the real
>>>docs, that would be bad. Making a better and fatter /start is fine.
>>
>>Yes, that's completely agreed. While maybe not a fatter /start (which is
>>after all more a place to show off mod_perl's conciseness than try to
>>each something), beginners like tutorials that take you through mod_perl
>>one step at a time, a little like what you post regularly to other sites
>>(although I know, you just arrange the guide slightly, but it's still
>>more inviting).
>
>come'n, the installation guide in the guide, does do handholding already.
>So does getwet.pod.
Yes, but it's pretty damn big, and some users are relucatant to reading
anything big.
>>Which brings me to another point: we badly need Take23 or another site
>>like it. I am pretty anoyed right now because I feel that such a site
>>would have so much potential for the mod_perl community. I tried
>>contacting Matt about it, but after an "Ack. I'll set up a plan" reply, I
>>haven't heard anything from him for one month or more. I understand he's
>>busy, so I don't want to disturb him, but right now Take23 does more harm
>>than good. What do you people think? There are so many potential
>>tutorials/articles to be written on mod_perl, which don't fit into the
>>mod_perl site.
>
>Here is what Matt just said over irc:
>
><baud> argh: actually I'm getting very close to re-vamping take23. just
>give me some space.
>
>So just give Matt some space ;)
Ok.... no problem.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 10:23 19.05.2002, Stas Bekman wrote:
>
>> We shouldn't carry away with newbies. After all the online docs are
>> mainly for those who need to use the docs on the daily basis. If we
>> push too much newbies stuff that stands on the way of those who need
>> the real docs, that would be bad. Making a better and fatter /start is
>> fine.
>
>
> Yes, that's completely agreed. While maybe not a fatter /start (which is
> after all more a place to show off mod_perl's conciseness than try to
> each something), beginners like tutorials that take you through mod_perl
> one step at a time, a little like what you post regularly to other sites
> (although I know, you just arrange the guide slightly, but it's still
> more inviting).
come'n, the installation guide in the guide, does do handholding
already. So does getwet.pod.
> Which brings me to another point: we badly need Take23 or another site
> like it. I am pretty anoyed right now because I feel that such a site
> would have so much potential for the mod_perl community. I tried
> contacting Matt about it, but after an "Ack. I'll set up a plan" reply,
> I haven't heard anything from him for one month or more. I understand
> he's busy, so I don't want to disturb him, but right now Take23 does
> more harm than good. What do you people think? There are so many
> potential tutorials/articles to be written on mod_perl, which don't fit
> into the mod_perl site.
Here is what Matt just said over irc:
<baud> argh: actually I'm getting very close to re-vamping take23. just
give me some space.
So just give Matt some space ;)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 10:23 19.05.2002, Stas Bekman wrote:
>We shouldn't carry away with newbies. After all the online docs are mainly
>for those who need to use the docs on the daily basis. If we push too much
>newbies stuff that stands on the way of those who need the real docs, that
>would be bad. Making a better and fatter /start is fine.
Yes, that's completely agreed. While maybe not a fatter /start (which is
after all more a place to show off mod_perl's conciseness than try to each
something), beginners like tutorials that take you through mod_perl one
step at a time, a little like what you post regularly to other sites
(although I know, you just arrange the guide slightly, but it's still more
inviting).
Which brings me to another point: we badly need Take23 or another site like
it. I am pretty anoyed right now because I feel that such a site would have
so much potential for the mod_perl community. I tried contacting Matt about
it, but after an "Ack. I'll set up a plan" reply, I haven't heard anything
from him for one month or more. I understand he's busy, so I don't want to
disturb him, but right now Take23 does more harm than good. What do you
people think? There are so many potential tutorials/articles to be written
on mod_perl, which don't fit into the mod_perl site.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Bill Moseley wrote:
> [I had written this on May 11, but lost it in my draft folder... The
> Changes mail Stas sent reminded me.]
>
> At 08:30 PM 05/11/02 +0800, Stas Bekman wrote:
>
>>Folks, thanks to Thomas we have reshuffled a big chunk of the content.
>>See the updated version here:
>>http://perl.apache.org/preview/modperl-docs/dst_html/docs/tutorials/index.h
>
> tml
>
> My comment (acting like a new user, since I've been out of the loop all
> week), is that those doesn't really seem like "Tutorials". I'm not sure
> what I'd call them, though.
Why not, Bill? We might get the Jeffrey Baker's DBI performance tutorial
as well soon.
What's the better name?
> Also, the layout makes it look like the "Changes" link is suppose to be a
> tutorial, too, especially since there's only three entries in that table of
> contents.
Hence I wanted to change this.
> BTW, when I go to the main Documentation link, I feel a little overwhelmed.
> For the newbie it's just a click on the User Guide -> Getwet to a good
> overview, but still I wish there was more of an introduction right there as
> the first link. I suppose "What is mod_perl?" takes care of that.
>
> It's hard to describe. Maybe there just needs to be more of an into, or
> better descriptions for the links on the Documentation index. Yes, better
> descriptions are needed. Imagine you know nothing of mod_perl, you read
> the What is mod_per? and then you click on the Documentation menu item.
> It's hard to know where to go next.
We shouldn't carry away with newbies. After all the online docs are
mainly for those who need to use the docs on the daily basis. If we push
too much newbies stuff that stands on the way of those who need the real
docs, that would be bad. Making a better and fatter /start is fine.
The src/docs/index_top.html should be changed to say something like:
If you are after mod_perl 1.x, read 1.x stuff and general docs. For 2.x
users it's 2.x stuff and general docs. Also see the Tutorials and off
site info.
You are welcome to make it sound nicer, but it must very consise and
short, because this is a 'work' area where any text gets on your way,
when you know what you want.
> I'll try to work on the descriptions next week.
Cool!
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Bill Moseley <mo...@hank.org>.
[I had written this on May 11, but lost it in my draft folder... The
Changes mail Stas sent reminded me.]
At 08:30 PM 05/11/02 +0800, Stas Bekman wrote:
>Folks, thanks to Thomas we have reshuffled a big chunk of the content.
>See the updated version here:
>http://perl.apache.org/preview/modperl-docs/dst_html/docs/tutorials/index.h
tml
My comment (acting like a new user, since I've been out of the loop all
week), is that those doesn't really seem like "Tutorials". I'm not sure
what I'd call them, though.
Also, the layout makes it look like the "Changes" link is suppose to be a
tutorial, too, especially since there's only three entries in that table of
contents.
BTW, when I go to the main Documentation link, I feel a little overwhelmed.
For the newbie it's just a click on the User Guide -> Getwet to a good
overview, but still I wish there was more of an introduction right there as
the first link. I suppose "What is mod_perl?" takes care of that.
It's hard to describe. Maybe there just needs to be more of an into, or
better descriptions for the links on the Documentation index. Yes, better
descriptions are needed. Imagine you know nothing of mod_perl, you read
the What is mod_per? and then you click on the Documentation menu item.
It's hard to know where to go next.
I'll try to work on the descriptions next week.
--
Bill Moseley
mailto:moseley@hank.org
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 08:00 14.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 18:48 12.05.2002, Stas Bekman wrote:
>>
>>>I thought of:
>>>
>>>guide/index.html:
>>>-----------------
>>>Part II: OS-specific information
>>>
>>> Win32
>>> OSX
>>> ...
>>>
>>>each pointing to the docset of its own. So all you need to do is
>>>
>>>1. mv docs/1.0/win32 docs/1.0/guide/win32
>>>
>>>2. remove it from docs/1.0/config.cfg and put it into
>>>docs/1.0/guide/config.cfg
>>>
>>>3. find . -type f -exec perl pi -e 's|win32::|guide::win32::|' {} \;
>
>After thinking some more I've realized that this doesn't solve anything.
>Since the os specific docsets are nested (and aren't a core part of the
>"guide" docset) they aren't becoming a part of the top level PDF. So they
>are going to be separate in any case. I guess in that case docs/1.0/os is
>better than, as suggested by Per Einar in first place.
>
>Unless you have better ideas.
>
>Another related question: Should each platform specific docs go into
>separate docsets, so each can be downloaded as a separate PDF. Or putting
>them all into one docset, with the overhead of having all the OSs in one doc.
>
>I think they should be separate docsets.
+1 on all of that.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 18:48 12.05.2002, Stas Bekman wrote:
>
>> I thought of:
>>
>> guide/index.html:
>> -----------------
>> Part II: OS-specific information
>>
>> Win32
>> OSX
>> ...
>>
>> each pointing to the docset of its own. So all you need to do is
>>
>> 1. mv docs/1.0/win32 docs/1.0/guide/win32
>>
>> 2. remove it from docs/1.0/config.cfg and put it into
>> docs/1.0/guide/config.cfg
>>
>> 3. find . -type f -exec perl pi -e 's|win32::|guide::win32::|' {} \;
>>
>> cet tout
>
>
> You'll still need a little work on your french but I'm +1 for this :)
>
sorry must be c'est tout :) ...followed by bonne nuit :)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 18:48 12.05.2002, Stas Bekman wrote:
>
>> I thought of:
>>
>> guide/index.html:
>> -----------------
>> Part II: OS-specific information
>>
>> Win32
>> OSX
>> ...
>>
>> each pointing to the docset of its own. So all you need to do is
>>
>> 1. mv docs/1.0/win32 docs/1.0/guide/win32
>>
>> 2. remove it from docs/1.0/config.cfg and put it into
>> docs/1.0/guide/config.cfg
>>
>> 3. find . -type f -exec perl pi -e 's|win32::|guide::win32::|' {} \;
After thinking some more I've realized that this doesn't solve anything.
Since the os specific docsets are nested (and aren't a core part of the
"guide" docset) they aren't becoming a part of the top level PDF. So
they are going to be separate in any case. I guess in that case
docs/1.0/os is better than, as suggested by Per Einar in first place.
Unless you have better ideas.
Another related question: Should each platform specific docs go into
separate docsets, so each can be downloaded as a separate PDF. Or
putting them all into one docset, with the overhead of having all the
OSs in one doc.
I think they should be separate docsets.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 18:48 12.05.2002, Stas Bekman wrote:
>I thought of:
>
>guide/index.html:
>-----------------
>Part II: OS-specific information
>
> Win32
> OSX
> ...
>
>each pointing to the docset of its own. So all you need to do is
>
>1. mv docs/1.0/win32 docs/1.0/guide/win32
>
>2. remove it from docs/1.0/config.cfg and put it into
>docs/1.0/guide/config.cfg
>
>3. find . -type f -exec perl pi -e 's|win32::|guide::win32::|' {} \;
>
>cet tout
You'll still need a little work on your french but I'm +1 for this :)
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 17:59 12.05.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 16:18 12.05.2002, Stas Bekman wrote:
>>>
>>>>> Well, I think we just do as I said there. Replace "Win32" with
>>>>> "Operating System specific details", put those files into that
>>>>> directory, and leave it at that. Right now, we're not doing
>>>>> anything special with the Win32 docs, and I don't think anything
>>>>> more is needed.
>>>>
>>>>
>>>>
>>>> so you simply suggest to move 1.0/win32 to 1.0/docs/guide/win32?
>>>
>>> No, I'm saying to move 1.0/win32 to 1.0/os/win32, and leave the
>>> 1.0/os/ directory ready for other OSes.
>>
>>
>> So if someone grabs the PDF of the guide, he doesn't get the OS
>> specific parts. On the other hand if we put them all in the guide,
>> then the PDF will be bloated with stuff not interesting to all. But
>> still it's better to have more than less, don't you think? I know a
>> bunch of people who simply print out the guide's PDF, bind it and give
>> to their employees to read.
>>
>> I'm in favor of having OS specific details in their own documents.
>> This will allow to have separate maintainers do their best without
>> stepping on each other toes.
>>
>> But would like to hear other opinions whether to have these
>> OS-specific chapters in the guide or in parallel to it?
>
>
> Good point. Well, in that case, we could make them a group inside the
> guide. The only problem I might see is this:
>
> Part LXXXVIII:) OS-specific information
>
> - Win32 compile
> - Win32 install
> - Win32 issues
> - Win32 foo
> - Cygwin installation
> - MacOS X instructions
>
> As the amount of Win32 information we have is quite large, that might be
> an issue. However, we could put those into just "Windows" and make them
> sub-sections of that document.
I thought of:
guide/index.html:
-----------------
Part II: OS-specific information
Win32
OSX
...
each pointing to the docset of its own. So all you need to do is
1. mv docs/1.0/win32 docs/1.0/guide/win32
2. remove it from docs/1.0/config.cfg and put it into
docs/1.0/guide/config.cfg
3. find . -type f -exec perl pi -e 's|win32::|guide::win32::|' {} \;
cet tout
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 17:59 12.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 16:18 12.05.2002, Stas Bekman wrote:
>>
>>>>Well, I think we just do as I said there. Replace "Win32" with
>>>>"Operating System specific details", put those files into that
>>>>directory, and leave it at that. Right now, we're not doing anything
>>>>special with the Win32 docs, and I don't think anything more is needed.
>>>
>>>
>>>so you simply suggest to move 1.0/win32 to 1.0/docs/guide/win32?
>>No, I'm saying to move 1.0/win32 to 1.0/os/win32, and leave the 1.0/os/
>>directory ready for other OSes.
>
>So if someone grabs the PDF of the guide, he doesn't get the OS specific
>parts. On the other hand if we put them all in the guide, then the PDF
>will be bloated with stuff not interesting to all. But still it's better
>to have more than less, don't you think? I know a bunch of people who
>simply print out the guide's PDF, bind it and give to their employees to read.
>
>I'm in favor of having OS specific details in their own documents. This
>will allow to have separate maintainers do their best without stepping on
>each other toes.
>
>But would like to hear other opinions whether to have these OS-specific
>chapters in the guide or in parallel to it?
Good point. Well, in that case, we could make them a group inside the
guide. The only problem I might see is this:
Part LXXXVIII:) OS-specific information
- Win32 compile
- Win32 install
- Win32 issues
- Win32 foo
- Cygwin installation
- MacOS X instructions
As the amount of Win32 information we have is quite large, that might be an
issue. However, we could put those into just "Windows" and make them
sub-sections of that document.
I'd be ok with this.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 16:18 12.05.2002, Stas Bekman wrote:
>
>>> Well, I think we just do as I said there. Replace "Win32" with
>>> "Operating System specific details", put those files into that
>>> directory, and leave it at that. Right now, we're not doing anything
>>> special with the Win32 docs, and I don't think anything more is needed.
>>
>>
>> so you simply suggest to move 1.0/win32 to 1.0/docs/guide/win32?
>
> No, I'm saying to move 1.0/win32 to 1.0/os/win32, and leave the 1.0/os/
> directory ready for other OSes.
So if someone grabs the PDF of the guide, he doesn't get the OS specific
parts. On the other hand if we put them all in the guide, then the PDF
will be bloated with stuff not interesting to all. But still it's better
to have more than less, don't you think? I know a bunch of people who
simply print out the guide's PDF, bind it and give to their employees to
read.
I'm in favor of having OS specific details in their own documents. This
will allow to have separate maintainers do their best without stepping
on each other toes.
But would like to hear other opinions whether to have these OS-specific
chapters in the guide or in parallel to it?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 16:18 12.05.2002, Stas Bekman wrote:
>>Well, I think we just do as I said there. Replace "Win32" with "Operating
>>System specific details", put those files into that directory, and leave
>>it at that. Right now, we're not doing anything special with the Win32
>>docs, and I don't think anything more is needed.
>
>so you simply suggest to move 1.0/win32 to 1.0/docs/guide/win32?
No, I'm saying to move 1.0/win32 to 1.0/os/win32, and leave the 1.0/os/
directory ready for other OSes.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 14:08 12.05.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 12:47 12.05.2002, Stas Bekman wrote:
>>>
>>>> Per Einar Ellefsen wrote:
>>>>
>>>>> in docs/1.0/os/
>>>>> then..
>>>>> -> win32/
>>>>> -> osx/
>>>>> -> cygwin/
>>>>> And docs/1.0/os/config.cfg:
>>>>> group => 'Win32 platforms',
>>>>> chapters => [win32/blah, win32/blah],
>>>>> group => 'MacOS X information',
>>>>> chapters => [osx/blah],
>>>>> group => 'Cygwin toolkit',
>>>>> chapters => [cygwin/blah ],
>>>>
>>>>
>>>>
>>>> you should have started with this example :)
>>>>
>>>> What will be the win32/blah, win32/blah?
>>>>
>>>> win32/install.pod, win32/config.pod, etc?
>>>
>>>
>>> yes.
>>>
>>>> so at the guide/install.pod's top we will say:
>>>>
>>>> In addition to this document please read your OS specific doc:
>>>> win32 =>
>>>> cygwin =>
>>>>
>>>> and from each of these docs we will link back to the main doc?
>>>>
>>>> and in guide/config.pod's top we will say:
>>>>
>>>> In addition to this document please read the OS specific doc:
>>>> win32 =>
>>>> cygwin =>
>>>
>>>
>>> You don't seem to like this, do you?
>>
>>
>> No, no. Where did you see me saying that I don't like it? I'm just
>> asking about the rest of the details? Since I want to see the whole
>> picture.
>
>
> Well, I think we just do as I said there. Replace "Win32" with
> "Operating System specific details", put those files into that
> directory, and leave it at that. Right now, we're not doing anything
> special with the Win32 docs, and I don't think anything more is needed.
so you simply suggest to move 1.0/win32 to 1.0/docs/guide/win32?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 14:08 12.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 12:47 12.05.2002, Stas Bekman wrote:
>>
>>>Per Einar Ellefsen wrote:
>>>
>>>>in docs/1.0/os/
>>>>then..
>>>> -> win32/
>>>> -> osx/
>>>> -> cygwin/
>>>>And docs/1.0/os/config.cfg:
>>>> group => 'Win32 platforms',
>>>> chapters => [win32/blah, win32/blah],
>>>> group => 'MacOS X information',
>>>> chapters => [osx/blah],
>>>> group => 'Cygwin toolkit',
>>>> chapters => [cygwin/blah ],
>>>
>>>
>>>you should have started with this example :)
>>>
>>>What will be the win32/blah, win32/blah?
>>>
>>>win32/install.pod, win32/config.pod, etc?
>>
>>yes.
>>
>>>so at the guide/install.pod's top we will say:
>>>
>>>In addition to this document please read your OS specific doc:
>>>win32 =>
>>>cygwin =>
>>>
>>>and from each of these docs we will link back to the main doc?
>>>
>>>and in guide/config.pod's top we will say:
>>>
>>>In addition to this document please read the OS specific doc:
>>>win32 =>
>>>cygwin =>
>>
>>You don't seem to like this, do you?
>
>No, no. Where did you see me saying that I don't like it? I'm just asking
>about the rest of the details? Since I want to see the whole picture.
Well, I think we just do as I said there. Replace "Win32" with "Operating
System specific details", put those files into that directory, and leave it
at that. Right now, we're not doing anything special with the Win32 docs,
and I don't think anything more is needed.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 12:47 12.05.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> in docs/1.0/os/
>>> then..
>>> -> win32/
>>> -> osx/
>>> -> cygwin/
>>> And docs/1.0/os/config.cfg:
>>> group => 'Win32 platforms',
>>> chapters => [win32/blah, win32/blah],
>>> group => 'MacOS X information',
>>> chapters => [osx/blah],
>>> group => 'Cygwin toolkit',
>>> chapters => [cygwin/blah ],
>>
>>
>> you should have started with this example :)
>>
>> What will be the win32/blah, win32/blah?
>>
>> win32/install.pod, win32/config.pod, etc?
>
>
> yes.
>
>> so at the guide/install.pod's top we will say:
>>
>> In addition to this document please read your OS specific doc:
>> win32 =>
>> cygwin =>
>>
>> and from each of these docs we will link back to the main doc?
>>
>> and in guide/config.pod's top we will say:
>>
>> In addition to this document please read the OS specific doc:
>> win32 =>
>> cygwin =>
>
>
> You don't seem to like this, do you?
No, no. Where did you see me saying that I don't like it? I'm just
asking about the rest of the details? Since I want to see the whole picture.
> :) I'm so sure we need to
> explicitly refer back to them. Most of these are only installation notes
> (except for some more elaborate information in Win32), and any user
> looking for answers will find these right away, while for others, they
> aren't of much value.
>
> Anyway, if you think your solution is better, go ahead and present it
> more specifically. I just didn't want to change things too much, but
> leave room for more information.
>
>
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 12:47 12.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>
>>in docs/1.0/os/
>>then..
>> -> win32/
>> -> osx/
>> -> cygwin/
>>And docs/1.0/os/config.cfg:
>> group => 'Win32 platforms',
>> chapters => [win32/blah, win32/blah],
>> group => 'MacOS X information',
>> chapters => [osx/blah],
>> group => 'Cygwin toolkit',
>> chapters => [cygwin/blah ],
>
>you should have started with this example :)
>
>What will be the win32/blah, win32/blah?
>
>win32/install.pod, win32/config.pod, etc?
yes.
>so at the guide/install.pod's top we will say:
>
>In addition to this document please read your OS specific doc:
>win32 =>
>cygwin =>
>
>and from each of these docs we will link back to the main doc?
>
>and in guide/config.pod's top we will say:
>
>In addition to this document please read the OS specific doc:
>win32 =>
>cygwin =>
You don't seem to like this, do you? :) I'm so sure we need to explicitly
refer back to them. Most of these are only installation notes (except for
some more elaborate information in Win32), and any user looking for answers
will find these right away, while for others, they aren't of much value.
Anyway, if you think your solution is better, go ahead and present it more
specifically. I just didn't want to change things too much, but leave room
for more information.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> in docs/1.0/os/
> then..
> -> win32/
> -> osx/
> -> cygwin/
> And docs/1.0/os/config.cfg:
>
> group => 'Win32 platforms',
> chapters => [win32/blah, win32/blah],
> group => 'MacOS X information',
> chapters => [osx/blah],
> group => 'Cygwin toolkit',
> chapters => [cygwin/blah ],
you should have started with this example :)
What will be the win32/blah, win32/blah?
win32/install.pod, win32/config.pod, etc?
so at the guide/install.pod's top we will say:
In addition to this document please read your OS specific doc:
win32 =>
cygwin =>
and from each of these docs we will link back to the main doc?
and in guide/config.pod's top we will say:
In addition to this document please read the OS specific doc:
win32 =>
cygwin =>
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 11:14 12.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 09:57 12.05.2002, Stas Bekman wrote:
>>
>>>Per Einar Ellefsen wrote:
>>>
>>>>Hmm, I think that for 1.x we only need an os-specific section. Then we
>>>>just make "groups" inside that instead of even more different docsets.
>>>>We won't have too much information, but it'll be too much to stick into
>>>>the "User's guide" (which is more than big enough already).
>>>
>>>
>>>I don't understand you, Per Einar. You say that we make the section (not
>>>separate docs), but then you say it'll be too big (which is exactly my
>>>concern). Look at the win32, the docs are relatively big, no?
>>
>>:) I never make sense, do I? No, what I was meaning was that we make the
>>OS-specific parts a different sections (effectively replacing the Win32
>>part we have now). It'll be of ok size. However, we do not want to stick
>>this into the user's guide (see, I'm already getting accuswomted to the
>>change :) because those sections (which would number some 5-6 files)
>>would just fill up an already too big guide.
>
>I still don't understand where do you suggest to physically put them,
>please use real dir- and filenames as you describe your suggestion.
:)
in docs/1.0/os/
then..
-> win32/
-> osx/
-> cygwin/
And docs/1.0/os/config.cfg:
group => 'Win32 platforms',
chapters => [win32/blah, win32/blah],
group => 'MacOS X information',
chapters => [osx/blah],
group => 'Cygwin toolkit',
chapters => [cygwin/blah ],
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 09:57 12.05.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> Hmm, I think that for 1.x we only need an os-specific section. Then
>>> we just make "groups" inside that instead of even more different
>>> docsets. We won't have too much information, but it'll be too much to
>>> stick into the "User's guide" (which is more than big enough already).
>>
>>
>> I don't understand you, Per Einar. You say that we make the section
>> (not separate docs), but then you say it'll be too big (which is
>> exactly my concern). Look at the win32, the docs are relatively big, no?
>
>
> :) I never make sense, do I? No, what I was meaning was that we make the
> OS-specific parts a different sections (effectively replacing the Win32
> part we have now). It'll be of ok size. However, we do not want to stick
> this into the user's guide (see, I'm already getting accuswomted to the
> change :) because those sections (which would number some 5-6 files)
> would just fill up an already too big guide.
I still don't understand where do you suggest to physically put them,
please use real dir- and filenames as you describe your suggestion.
> I think of the guide as the information anyone must read. The
> OS-specific parts would only be an addition to that, sort of some
> reference material.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 09:57 12.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>Hmm, I think that for 1.x we only need an os-specific section. Then we
>>just make "groups" inside that instead of even more different docsets. We
>>won't have too much information, but it'll be too much to stick into the
>>"User's guide" (which is more than big enough already).
>
>I don't understand you, Per Einar. You say that we make the section (not
>separate docs), but then you say it'll be too big (which is exactly my
>concern). Look at the win32, the docs are relatively big, no?
:) I never make sense, do I? No, what I was meaning was that we make the
OS-specific parts a different sections (effectively replacing the Win32
part we have now). It'll be of ok size. However, we do not want to stick
this into the user's guide (see, I'm already getting accuswomted to the
change :) because those sections (which would number some 5-6 files) would
just fill up an already too big guide.
I think of the guide as the information anyone must read. The OS-specific
parts would only be an addition to that, sort of some reference material.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 06:35 12.05.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> Haven't found any problems yet, but I have one suggestion: instead of
>>> having a Win32 section under 1.xx, let's make it an "OS-specific
>>> instructions" section, so we could put MacOS/Cygwin/foo instructions
>>> there. If I ever get mod_perl 1.x to work on Cygwin, I'll try and
>>> write up some stuff, and I think we have enough working installations
>>> for MacOS X to get some help for that too.
>>
>>
>> Yes, we weren't sure how to do that the best. On one side it's nice to
>> have everything in one doc to minimize dups. But if each OS specific
>> part grows big a separate doc makes more sense. I think win32 docs are
>> big. That's said we could move them out of win32/ and put under
>> guide/, e.g. install_win32.pod, config_win32.pod, etc.
>>
>> We have the same issue with 2.0 stuff, but here is easier: we have
>> 2.0/install/install.pod (for generic stuff), platform specific stuff
>> can go into 2.0/install/win32.pod, etc. What do you think?
>
>
> Hmm, I think that for 1.x we only need an os-specific section. Then we
> just make "groups" inside that instead of even more different docsets.
> We won't have too much information, but it'll be too much to stick into
> the "User's guide" (which is more than big enough already).
I don't understand you, Per Einar. You say that we make the section (not
separate docs), but then you say it'll be too big (which is exactly my
concern). Look at the win32, the docs are relatively big, no?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 06:35 12.05.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>Haven't found any problems yet, but I have one suggestion: instead of
>>having a Win32 section under 1.xx, let's make it an "OS-specific
>>instructions" section, so we could put MacOS/Cygwin/foo instructions
>>there. If I ever get mod_perl 1.x to work on Cygwin, I'll try and write
>>up some stuff, and I think we have enough working installations for MacOS
>>X to get some help for that too.
>
>Yes, we weren't sure how to do that the best. On one side it's nice to
>have everything in one doc to minimize dups. But if each OS specific part
>grows big a separate doc makes more sense. I think win32 docs are big.
>That's said we could move them out of win32/ and put under guide/, e.g.
>install_win32.pod, config_win32.pod, etc.
>
>We have the same issue with 2.0 stuff, but here is easier: we have
>2.0/install/install.pod (for generic stuff), platform specific stuff can
>go into 2.0/install/win32.pod, etc. What do you think?
Hmm, I think that for 1.x we only need an os-specific section. Then we just
make "groups" inside that instead of even more different docsets. We won't
have too much information, but it'll be too much to stick into the "User's
guide" (which is more than big enough already).
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 14:30 11.05.2002, Stas Bekman wrote:
>
>> Folks, thanks to Thomas we have reshuffled a big chunk of the content.
>> See the updated version here:
>> http://perl.apache.org/preview/modperl-docs/dst_html/docs/tutorials/index.html
>>
>>
>> Please verify that we didn't lose anything while moving, and that you
>> are happy with how the docs are laid out now.
>>
>> We want to freeze the docs movement, finalize the design and proceed
>> with the preview stage. that's a release candidate modperl-docs-RC1.
>
>
> Haven't found any problems yet, but I have one suggestion: instead of
> having a Win32 section under 1.xx, let's make it an "OS-specific
> instructions" section, so we could put MacOS/Cygwin/foo instructions
> there. If I ever get mod_perl 1.x to work on Cygwin, I'll try and write
> up some stuff, and I think we have enough working installations for
> MacOS X to get some help for that too.
Yes, we weren't sure how to do that the best. On one side it's nice to
have everything in one doc to minimize dups. But if each OS specific
part grows big a separate doc makes more sense. I think win32 docs are
big. That's said we could move them out of win32/ and put under guide/,
e.g. install_win32.pod, config_win32.pod, etc.
We have the same issue with 2.0 stuff, but here is easier: we have
2.0/install/install.pod (for generic stuff), platform specific stuff can
go into 2.0/install/win32.pod, etc. What do you think?
BTW, the new docs are all nested in a separate dirs because we expect to
have code and images at some point for certain chapters, so it makes
sense to have them separated this way. We have done this for our book
and it works very well.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: content layout freeze
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 14:30 11.05.2002, Stas Bekman wrote:
>Folks, thanks to Thomas we have reshuffled a big chunk of the content. See
>the updated version here:
>http://perl.apache.org/preview/modperl-docs/dst_html/docs/tutorials/index.html
>
>Please verify that we didn't lose anything while moving, and that you are
>happy with how the docs are laid out now.
>
>We want to freeze the docs movement, finalize the design and proceed with
>the preview stage. that's a release candidate modperl-docs-RC1.
Haven't found any problems yet, but I have one suggestion: instead of
having a Win32 section under 1.xx, let's make it an "OS-specific
instructions" section, so we could put MacOS/Cygwin/foo instructions there.
If I ever get mod_perl 1.x to work on Cygwin, I'll try and write up some
stuff, and I think we have enough working installations for MacOS X to get
some help for that too.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org