Home > Archive > PHP PEAR Questions and Answers > November 2004 > Re: [PEAR-QA] Package Abstracts
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
Re: [PEAR-QA] Package Abstracts
|
|
| Arnaud Limbourg 2004-11-16, 6:53 pm |
| > This is a follow up on the "Documentation" discussion (and is probably
> in the wrong list, but since the discussion started here...)
>
> After manning the booth at our LinuxWorld stand and spending a good
> amount of time hanging around the booth at IPC2k4, I would like to
> propose that we create a simple format of the "mini-documentation" of
> EACH package.
>
> This documentation would not be comprehensive, but would be well written
> and provide an overview of what each package does. A good example is
> Perl's documentation which requires the following 5 sections:
>
> Name
> Abstract
> Synopsis
> Description
> Notes and Bugs
>
> I would propose that this documentation be maintained along with the
> packages, and updated to be included and installed in the docs/ folder
> with each release.
I think this should be part of the wiki. Each package will have its own
wiki area. Those requisites could be use for the base template.
> This is a fairly big job, but I think that the effort will be well worth
> the trouble, and will give PEAR a much more user-friendly face to the
> world (and put an end to the "PEAR is poorly documented" mantra we hear
> so often).
Indeed.
Arnaud.
| |
| Helgi Žormar 2004-11-16, 6:53 pm |
| On Tue, 2004-11-16 at 20:48, Arnaud Limbourg wrote:
>
> I think this should be part of the wiki. Each package will have its own
> wiki area. Those requisites could be use for the base template.
I agree with Arnaud.
>
> Indeed.
This is a fairly big job yes, which I will most likely take upon my
self, since I've had this wiki idea stuck in my head since I and Arnaud
were looking at some apps together to being able to orginize LiveUser
much better, and we came upon http://projects.edgewall.com/trac/ which
is a great piece of software, has few drawbacks, but surly the basic
idea is great, and I'm pretty sure that when Arnaud mentioned wiki he
had something very similar as my ideas :)
Maybe I even can poke Arnaud to help with this ? (*pokes arnaud*)
Of course like said before, this is a huuuuge task, so it won't be ready
anytime soon, and hasn't been started as of now, more thought has to be
put into it, and what the wiki should be capable of and etc. i.e.
planing.
Any ideas for this people ? :)
Every idea will be considered so don't be shy! ;)
Regards
Helgi
| |
| Paul M Jones 2004-11-16, 6:53 pm |
|
On Nov 16, 2004, at 3:47 PM, Helgi =DEormar wrote:
> Of course like said before, this is a huuuuge task, so it won't be=20
> ready
> anytime soon, and hasn't been started as of now, more thought has to =
be
> put into it, and what the wiki should be capable of and etc. i.e.
> planing.
>
> Any ideas for this people ? :)
> Every idea will be considered so don't be shy! ;)
I have volunteered in the past, and will continue to do so on a=20
standing basis, to set up a YaWiki <http://yawiki.com> installation for=20=
pear.php.net. It's all PEAR all the time, except for using Savant=20
<http://phpsavant.com> as its template system and Yawp=20
<http://phpyawp.com> as its foundation, so I hope that's not a=20
deal-breaker. I did some work with Tobias Schlitt to get it up on a=20
test machine, but there have been some problems with that box.
As regards a YaWiki installation, my own opinion is that each PEAR=20
package would get its own area. That results in a lot of areas, which=20=
means the default theme would not be useful; as such, it would need a=20
modified theme for displaying all the various areas. Not hard in a=20
technical sense, but perhaps non-trivial from an organization and=20
display perspective. Authentication would be nice, but not required,=20
if only so we can know who is doing what with documentation.
So again: this is me volunteering to get a YaWiki installation going=20
on pear.php.net.
--=20
Paul M. Jones
Savant: the simple alternative to Smarty for PHP.
http://phpsavant.com/
DB_Table: build RDBMS tables and XHTML forms in one PHP class.
http://wiki.ciaweb.net/yawiki/index.php?area=3DDB_Table
Yawiki: a collaborative online documentation system.
http://yawiki.com/
Yawp: a single-file foundation for PHP applications.
http://phpyawp.com/
| |
| Helgi Žormar 2004-11-16, 8:55 pm |
| On Tue, 2004-11-16 at 22:37, Paul M Jones wrote:
> On Nov 16, 2004, at 3:47 PM, Helgi Žormar wrote:
>
>
> I have volunteered in the past, and will continue to do so on a
> standing basis, to set up a YaWiki <http://yawiki.com> installation for
> pear.php.net. It's all PEAR all the time, except for using Savant
> <http://phpsavant.com> as its template system and Yawp
> <http://phpyawp.com> as its foundation, so I hope that's not a
> deal-breaker. I did some work with Tobias Schlitt to get it up on a
> test machine, but there have been some problems with that box.
We want to integrate this into pearweb thus we can't use yawiki (well
okey we don't want to use it because of the deps outside of pear,
specially because of yawp)
> As regards a YaWiki installation, my own opinion is that each PEAR
> package would get its own area. That results in a lot of areas, which
> means the default theme would not be useful; as such, it would need a
> modified theme for displaying all the various areas. Not hard in a
> technical sense, but perhaps non-trivial from an organization and
> display perspective. Authentication would be nice, but not required,
> if only so we can know who is doing what with documentation.
Authors will be able to choose if they want to use the wiki or not, thus
turning the feature on or off, at least the wiki for X package won't be
created unless the author turns the feature on for the first time.
Authentication won't be a problem, because it will be integrated into
pearweb :)
yaWiki will be probably the base of this, at least a side reference.
> So again: this is me volunteering to get a YaWiki installation going
> on pear.php.net.
Note what I said above
--
Regards
Helgi
| |
| Paul M Jones 2004-11-16, 8:55 pm |
|
On Nov 16, 2004, at 4:59 PM, Helgi =DEormar wrote:
> We want to integrate this into pearweb thus we can't use yawiki (well
> okey we don't want to use it because of the deps outside of pear,
> specially because of yawp)
Good luck then.
--=20
Paul M. Jones
Savant: the simple alternative to Smarty for PHP.
http://phpsavant.com/
DB_Table: build RDBMS tables and XHTML forms in one PHP class.
http://wiki.ciaweb.net/yawiki/index.php?area=3DDB_Table
Yawiki: your collaborative online documentation system.
http://yawiki.com/
Yawp: a single-file foundation for PHP applications.
http://phpyawp.com/
| |
| Lukas Smith 2004-11-17, 8:56 am |
| Paul M Jones wrote:
>
> On Nov 16, 2004, at 4:59 PM, Helgi Žormar wrote:
>
>
>
> Good luck then.
Well I would ponder that one for a bit.
For one the wiki can stay separated from the rest of pearweb. This was
actually something we agreed upon in amsterdam. Regardless of that
yawiki eats much more of our own dogfood than pearweb.
Finally its opensource and imho its a very good starting point. There
are some minor issues but things are getting along quite nicely and
especially the areamap and Text_Wiki basis are awesome foundations to
generate documentation.
regards,
Lukas
| |
| arnaud@limbourg.com 2004-11-17, 3:58 pm |
| I did talk with Helgi about trac (which is an amazing piece of software about
which I would not say it has drawbacks) but my main concern with writing our
own is,as helgi says, it will take a long time.
We can have a solution up in a shorter time by using yawiki. It would
not be as
fun as to develop our own solution but why bother where there are valid and
existing alternatives.
It's overkill to spend time coding when we can avoid it.
Arnaud.
----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.
| |
| Greg Beaver 2004-11-17, 3:58 pm |
| arnaud@limbourg.com wrote:
> I did talk with Helgi about trac (which is an amazing piece of software
> about
> which I would not say it has drawbacks) but my main concern with writing
> our
> own is,as helgi says, it will take a long time.
>
> We can have a solution up in a shorter time by using yawiki. It would
> not be as
> fun as to develop our own solution but why bother where there are valid and
> existing alternatives.
>
> It's overkill to spend time coding when we can avoid it.
Agreed. Paul's wiki works fine, the only thing that would have to be
changed is the basic look to match the rest of pear.php.net, and that's
just eye candy. Plus we have the author as an active developer who I'm
sure can offer pointers, if not actual code, to do the job.
Greg
| |
| Justin Patrin 2004-11-17, 3:58 pm |
| On Wed, 17 Nov 2004 11:40:58 -0500, Greg Beaver <cellog@php.net> wrote:
> arnaud@limbourg.com wrote:
>
>
>
> Agreed. Paul's wiki works fine, the only thing that would have to be
> changed is the basic look to match the rest of pear.php.net, and that's
> just eye candy. Plus we have the author as an active developer who I'm
> sure can offer pointers, if not actual code, to do the job.
>
Hear hear.
--
Justin Patrin
| |
| Martin Jansen 2004-11-18, 8:56 pm |
| On Tue Nov 16, 2004 at 10:5932PM +0000, Helgi =DEormar wrote:
> On Tue, 2004-11-16 at 22:37, Paul M Jones wrote:
=20[color=darkred]
>=20
> We want to integrate this into pearweb thus we can't use yawiki (well
> okey we don't want to use it because of the deps outside of pear,
> specially because of yawp)
Who said that? I for one would be very delighted to set up Paul's wiki
on e.g. wiki.pear.php.net - this way the wiki does not need to inherit
any code from the website, and at the same time the wiki can use the
existing user table for authentication. (Killing two birds with one
stone.)
--=20
- Martin Martin Jansen
http://martinjansen.com/
| |
| Helgi Žormar 2004-11-18, 8:56 pm |
| On Thu, 2004-11-18 at 20:43, Martin Jansen wrote:
> On Tue Nov 16, 2004 at 10:5932PM +0000, Helgi Žormar wrote:
>
> Who said that? I for one would be very delighted to set up Paul's wiki
> on e.g. wiki.pear.php.net - this way the wiki does not need to inherit
> any code from the website, and at the same time the wiki can use the
> existing user table for authentication. (Killing two birds with one
> stone.)
I'd assume if we were going to integrate it it would be kinda funky to
have 2 frameworks, i.e. Yawp and Damblan, integrate I mean not just by
placing yaWiki in some folder on the server, but well have it as you
like.
If we get some features to work with yaWiki (not doubt out that we will
be able to do so) then I'm fine with having it.
(features I mean by little things as #342 turn into a bug link and etc,
maybe even a roadmap "module" if I find the time to write such for
pearweb.)
P.S.
Little description on my idea of roadmap module before anyone starts to
ask, it would be a thing a lead has to active, then they can make a
milestone, like such:
0.4 Release_name (if wanted that is)
count of active bugs tied to that milestone
count of closed bugs tied to that milestone
- same goals or description
- etc.
Something in that direction, then also I'd add the ability for devs to
mark a bug to be done for X milestone so this stuff will work (the bug
count for each milestone)
Anyway this is only a idea, which I haven't even brought up with the web
team, but this is a part I see to be good on the wiki, but we'll see if
this gets accepted by the web team, and if this can be added to the wiki
or will just be outside it.
Comments, ideas ?
Regards
Helgi
| |
| Helgi Žormar 2004-11-18, 8:56 pm |
| On Thu, 2004-11-18 at 21:07, Paul M Jones wrote:
> Helgi Žormar wrote:
>
> Not to nitpick, but Yawp is not a framework (at least I don't think of
> it as such). I call it a "foundation" on which you can base apps of any
> sort; except for some glue-code to automate authentication and
> object-creation, it's really just a bunch of PEAR classes aggregated
> behind a static interface class plus a unform configuration file. I
> attempted to make it solution-agnostic; you can use it to write up MVC
> solutions or standalone monolithic apps.
Hmm yeah I know, misused that word, Damblan isn't either a framework in
a way.
>
>
> The Bug link thing is even easier thank you think. One example is to
> treat the word "Bug" as an interwiki keyword. In the Yawp.conf.php
> file, you would add:
>
> [yawiki]
> interwiki_site = Bug, http://pear.php.net/bugs/bug.php?id=%s
>
> Then Text_Wiki will automatically translate the text "Bug:2228" as a
> link to http://pear.php.net/bugs/bug.php?id=2228 -- no programming
> involved, just a change to the config file. :-)
I see, never was sure what those interwiki things were anyway :)
but can it do like something similar to this, #4353, and not changing
#foo into a link, i.e. kinda yes just allowing numbers through that
config ?
- Helgi
| |
| Helgi Žormar 2004-11-18, 8:56 pm |
| On Thu, 2004-11-18 at 21:21, Paul M Jones wrote:
Hi Paul
>
> Heh. :-) The idea is that you can define the names of other wikis and
> then be able to link to them without using the full URL; the
> word-plus-colon indicates the wiki name, and the part after the colon
> indicates the page. As a bonus, it turns out this marking is useful for
> all sorts of non-wiki things that can be represented as URLs: file
> links, bug links, links to "normal" sites, and so on.
>
>
>
> I think hash (pound) sign is too generic for that particular use.
> Text_Wiki already uses # in a few different ways:
>
> Using ##red|double hash marks## indicates colored text,
>
> # at the beginning of a line indicates a numbered list item,
>
> If you have [#anchorname] it's a link to an anchor on the same page,
>
> And [[# anchorname Displayed Text]] creates an anchor on the page.
>
> So adding #1234 as a link to bugs is probably not useful in this case,
> especially as # might well be used to number non-bug things. Having
> "Bug:1234" would be both obvious to the reader, and easier to implement
> (otherwise we'd need a new "bug.php" rule to look for numeric-only hash
> marks, plus corresponding rendering rules, blah blah blah).
>
> I hope that makes sense.
Well here's the problem, more often then not, people point to a
bug/feature request by saying "Look at #454", I've seen this in more
then just PEAR and more then just PHP, so I've become to look at this a
kinda standard, of course most useful is to just do bug:34 ticket:34 or
so, which btw. should also be supported :) I anyway would like to see
#443 also supported since to me it's kinda wide spread for pointing to a
bug report, and I of course am a ware of that #005500 or so could be
turned into a bug report link, when the person meant a hex, but
sometimes you can't have everything, can you :)
So I'd like to see #43534 supported, we did that with a simple and clean
preg_match for the changelogs in PEARweb, and even made it support Bug:
453 to be converted into link in just a one liner regex :)
Coming to think about it, on the wiki it self this is less important,
having this on the changelog was of course the most important :)
It's your call really.
Regards
Helgi
| |
| Justin Patrin 2004-11-18, 8:56 pm |
| On Thu, 18 Nov 2004 21:42:34 +0000, Helgi =DEormar <helgi@trance.is> wrote:
> On Thu, 2004-11-18 at 21:21, Paul M Jones wrote:
>=20
> Hi Paul
>=20
>=20
>=20
r[color=darkred]
>=20
> Well here's the problem, more often then not, people point to a
> bug/feature request by saying "Look at #454", I've seen this in more
> then just PEAR and more then just PHP, so I've become to look at this a
> kinda standard, of course most useful is to just do bug:34 ticket:34 or
> so, which btw. should also be supported :) I anyway would like to see
> #443 also supported since to me it's kinda wide spread for pointing to a
> bug report, and I of course am a ware of that #005500 or so could be
> turned into a bug report link, when the person meant a hex, but
> sometimes you can't have everything, can you :)
>=20
> So I'd like to see #43534 supported, we did that with a simple and clean
> preg_match for the changelogs in PEARweb, and even made it support Bug:
> 453 to be converted into link in just a one liner regex :)
>=20
> Coming to think about it, on the wiki it self this is less important,
> having this on the changelog was of course the most important :)
>=20
> It's your call really.
>=20
I would rather Bug #123 and Bug:123 be supported. Changing #123 to a
bug link is just too prone to error. I could easily see someone saying
"line #123".
--=20
Justin Patrin
| |
| Paul M Jones 2004-11-18, 8:56 pm |
| Helgi Žormar wrote:[color=darkred]
> On Thu, 2004-11-18 at 21:41, Justin Patrin wrote:
>
Well, I don't like "Bug #123" (it seems kind of non-wiki-ish to me) but
it would be easy to support as a filter rule without additional
rendering; on parsing (as a prefilter) convert all "Bug #nnnn" to
"Bug:nnnn" and then the follow-on interwiki parser can handle the rest.
Of course, all of this is moot until the thing actually gets set up. Am
I to understand from this extended conversation, then, that we should
get started on it? If so, I need a couple of things:
# Access to the development box (or the "live" box if we want to do it
from there)
# Access credentials to the database where the YaWiki tables will be stored
# Some input on how to theme the pages
That should be it, really.
-- pmj
|
|
|
|
|