UserGuide and Tutorial - call for comment

Hi all,

One week ago, I've asked Gregory Beaver to re-read the draft
of P_PFM 
(1.6.x / 1.5.x) User Guide - Tutorial I wrote in DocBook
format.

No answer until now! I hope you got all my mails Greg.

I plan to publish it on my web server[1] Sunday 12 Nov, and
I hope to 
have some readers and of course some comments about
contents.

1. Clear or NOT
2. Missing stuff
3. Anything else ...

Don't forget, that user-doc is made for you. If you want to
have a cool 
and easy readable, it's up to you to decide.
Once, and only once action: send me comments. All are
welcome !

regards
Laurent Laville


[1] http://pear.laurent-laville.org/PEAR_PackageFileManager

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On Fri Nov 10, 2006 at 05:4533PM +0100, Laurent Laville
wrote:
> One week ago, I've asked Gregory Beaver to re-read the
draft of P_PFM 
> (1.6.x / 1.5.x) User Guide - Tutorial I wrote in
DocBook format.
> 
> No answer until now! I hope you got all my mails Greg.
> 
> I plan to publish it on my web server[1] Sunday 12 Nov,
and I hope to 
> have some readers and of course some comments about
contents.

Why don't you publish it right now?  People interested in
looking at it
(including me) will probably forget about it until Sunday.

- Martin

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Laurent,

> 1. Clear or NOT
> 2. Missing stuff
> 3. Anything else ...

> can manage the new package.xml 2.0 format introduce
with PEAR 1.4.0
introduce/d/

The requested URL
/pear/PEAR_PackageFileManager/docs/TDG/en/index.html
was not found on this server.

You do use images for the buttons like "Edit". In
docbook, there should
be tags for this.


The docs/explanation are nice.

-- 
Regards/MfG,
Christian Weiske

Martin Jansen a écrit :
> On Fri Nov 10, 2006 at 05:4533PM +0100, Laurent Laville
wrote:
>   
>> One week ago, I've asked Gregory Beaver to re-read
the draft of P_PFM 
>> (1.6.x / 1.5.x) User Guide - Tutorial I wrote in
DocBook format.
>>
>> No answer until now! I hope you got all my mails
Greg.
>>
>> I plan to publish it on my web server[1] Sunday 12
Nov, and I hope to 
>> have some readers and of course some comments about
contents.
>>     
>
> Why don't you publish it right now?  People interested
in looking at it
> (including me) will probably forget about it until
Sunday.
>
> - Martin
>
>
>   
Available now Martin ! Just uploaded the copy one week old.
Probably more to add / fix, but I'll wait first comments
before

Laurent

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Laurent Laville wrote:
> Martin Jansen a écrit :
>> On Fri Nov 10, 2006 at 05:4533PM +0100, Laurent
Laville wrote:
>>  
>>> One week ago, I've asked Gregory Beaver to
re-read the draft of P_PFM
>>> (1.6.x / 1.5.x) User Guide - Tutorial I wrote
in DocBook format.
>>>
>>> No answer until now! I hope you got all my
mails Greg.
>>>
>>> I plan to publish it on my web server[1] Sunday
12 Nov, and I hope to
>>> have some readers and of course some comments
about contents.
>>>     
>>
>> Why don't you publish it right now?  People
interested in looking at it
>> (including me) will probably forget about it until
Sunday.
>>
>> - Martin
>>
>>
>>   
> Available now Martin ! Just uploaded the copy one week
old.
> Probably more to add / fix, but I'll wait first
comments before
> 
> Laurent

Hi Laurent,

Greg is still on the road I think hence his lack of answers.

Arnaud.

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Laurent Laville wrote:
> Hi all,
> 
> One week ago, I've asked Gregory Beaver to re-read the
draft of P_PFM
> (1.6.x / 1.5.x) User Guide - Tutorial I wrote in
DocBook format.
> 
> No answer until now! I hope you got all my mails Greg.
> 
> I plan to publish it on my web server[1] Sunday 12 Nov,
and I hope to
> have some readers and of course some comments about
contents.
> 
> 1. Clear or NOT
> 2. Missing stuff
> 3. Anything else ...
> 
> Don't forget, that user-doc is made for you. If you
want to have a cool
> and easy readable, it's up to you to decide.
> Once, and only once action: send me comments. All are
welcome !
> 
> regards
> Laurent Laville
> 
> 
> [1] http://pear.laurent-laville.org/PEAR_PackageFileManager

Hi Laurent,

Do you plan to move this over to pear.php.net's docbook
docs, or keep it
on your server?  Up until now, I assumed it would be merged
with PEAR's
docs, but it looks like you're intending to have this as a
standalone
docbook book, correct me if I'm wrong.

I've found a number of minor English typos that I would
rather directly
fix in CVS than have you do the work.

Thanks,
Greg

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On Fri Nov 10, 2006 at 05:4533PM +0100, Laurent Laville
wrote:
> I plan to publish it on my web server[1] Sunday 12 Nov,
and I hope to 
> have some readers and of course some comments about
contents.
> 
> 1. Clear or NOT
> 2. Missing stuff
> 3. Anything else ...
> 
> Don't forget, that user-doc is made for you. If you
want to have a cool 
> and easy readable, it's up to you to decide.
> Once, and only once action: send me comments. All are
welcome !

I think this is pretty good, but what do you think
explaining what the 8
pages (package, release, maintainers, ...) are good for? 
I'd probably
put something like

    "The package tab is for setting the general
information about the
     package."

in front of the "This screen is divided into n
parts." text.  Similar
for the other sections.

I agree with Greg that having this in peardoc is a good
idea.

- Martin

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Martin Jansen a écrit :
  > I think this is pretty good, but what do you think
explaining what the 8
> pages (package, release, maintainers, ...) are good
for?  I'd probably
> put something like
> 
>     "The package tab is for setting the general
information about the
>      package."
> 
> in front of the "This screen is divided into n
parts." text.  Similar
> for the other sections.

I've begun to write an "API short tour". Is it
what you suppose to see, 
as explain ?

http://www.laurent-laville.org/
pear/PEAR_PackageFileManager/docs/TDG/en/ch05.html


It's just a sample. Of course if you're agree, I'll continue
and write 
all other API group.


NEW version (online)
http://www.laurent-laville.org
/pear/PEAR_PackageFileManager/docs/TDG/en/index.html

include now source code hilighting.

> 
> I agree with Greg that having this in peardoc is a good
idea.
> 
> - Martin

For many reasons, as I've already explained in past when I
wrote other 
manuals (in docbook format), this one will be again a
standalone 
version. No pear doc integration.

Main reason : I used all dockbook tags I want without
restriction and 
some features that are probably not supported by pear manual
architecture.

But as, like other manuals I've wrote for HTML_CSS,
HTML_Progress2, ... 
an html copy will be available with next stable release.

LAST: I plan to publish the stable release 1.6.0 with a full
user guide 
for November 21st.

If someone is not agree or want to see something else in
this manual, 
you have again 9 days.

Laurent

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Laurent Laville wrote:
> For many reasons, as I've already explained in past
when I wrote other
> manuals (in docbook format), this one will be again a
standalone
> version. No pear doc integration.
> 
> Main reason : I used all dockbook tags I want without
restriction and
> some features that are probably not supported by pear
manual architecture.
> 
> But as, like other manuals I've wrote for HTML_CSS,
HTML_Progress2, ...
> an html copy will be available with next stable
release.
> 
> LAST: I plan to publish the stable release 1.6.0 with a
full user guide
> for November 21st.
> 
> If someone is not agree or want to see something else
in this manual,
> you have again 9 days.

Hi Laurent,

I can't support this decision.  There are hundreds of
grammar errors in
the documentation you've written, and more than one factual
error.

I don't see any good reason to avoid the PEAR manual.  The
thing is
already in docbook!  It wouldn't take long to tweak it to
fix any
compatibility issues encountered.  Most important, it cannot
be
translated or edited by anyone else as long as it it outside
of CVS.

HOWEVER, I understand and appreciate the effort you've put
into this,
and if you choose to publish the manual as an independent
HTML document,
I won't stop you.  I have, however, removed myself as a
developer from
PEAR_PackageFileManager (marking as inactive) as I don't
agree with the
majority of your recent decisions, and also don't have the
time to do
anything about it.  I hope you can understand my feeling on
this issue.

Greg

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On Mon Nov 13, 2006 at 11:4108AM -0600, Greg Beaver wrote:
> Laurent Laville wrote:
> > For many reasons, as I've already explained in
past when I wrote other
> > manuals (in docbook format), this one will be
again a standalone
> > version. No pear doc integration.
> > 
> > Main reason : I used all dockbook tags I want
without restriction and
> > some features that are probably not supported by
pear manual architecture.
> > 
> > But as, like other manuals I've wrote for
HTML_CSS, HTML_Progress2, ...
> > an html copy will be available with next stable
release.
> > 
> > LAST: I plan to publish the stable release 1.6.0
with a full user guide
> > for November 21st.
> > 
> > If someone is not agree or want to see something
else in this manual,
> > you have again 9 days.
> 
> I can't support this decision.  There are hundreds of
grammar errors in
> the documentation you've written, and more than one
factual error.

I think we can sort of live with the grammar errors and a
lot of people
can easily fix them.  (If we get that thing into CVS
*grin*.)  But it
would be good if you told details about the factual error
(unless
Laurent already knows about it), because most people won't
likely notice
that one.

> I don't see any good reason to avoid the PEAR manual. 
The thing is
> already in docbook!  It wouldn't take long to tweak it
to fix any
> compatibility issues encountered.  Most important, it
cannot be
> translated or edited by anyone else as long as it it
outside of CVS.

Laurent, if you need help in merging the documentation into
the manual,
just drop a note.  It would be sad to see this fail because
of technical
reasons.

- Martin

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php