Moving peardoc to XSLT

Hello all,


Most of you which ever tried to compile peardoc know that
the dsssl stylesheets are a pain to setup and get running.
Since we all want more documentation and have it easy to
write documentation, we need to do something.

The first thing that needs to be done is dropping the DSSSL
stylesheets in favor of XSLT. It has several advantages:
- XSLT is faster than DSSSL (citation needed)
- I know nobody in PEAR that is familiar customizing the
current dsssl stylesheets
- There are some PEAR devs that know XSLT
- XSLT is more easy to setup
- phpdoc, php-gtk-doc and Livedocs use XSLT, too
- Switching to XSLT would bring us livedocs
- We could finally customize the looks of the manual on the
webpage and make it more user friendly. See http
://www.markwiesemann.eu/tmp/pear-manual4.png and the
discussion in http://news.php
.net/php.pear.doc/9704 (click the references to get more
shots)


Since I currently am working on my diploma thesis, someone
else would need to take the lead in this project. The
following tasks are to be done:
- Check out phpdoc and see if we can use its system with as
few changes as possible
- Contact phpdoc people and ask them how to start best
- Contact livedoc gsoc people and ask what we need to do to
be livedoc-compatible
- When all info is collected, make peardoc's build system to
use xslt and support different sheets
- Create XSLT sheets for the website, maybe modify the
standard html xslt for offline docs


Having customized php-gtk-doc in a great deal, I have
experience in editing XSLT. You can count on my help once
this stage is reached.

peardoc bug entry: http://pear
.php.net/bugs/bug.php?id=10843
Livedocs gsoc project: http://de3.php.net/ideas
.php and http://wiki.phpdoc.i
nfo/LiveDocs


Further ideas are also welcome!

-- 
Christian Weiske

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

On 6/1/07, Christian Weiske <cweiskecweiske.de> wrote:
> Hello all,
>
>
> Most of you which ever tried to compile peardoc know
that the dsssl stylesheets are a pain to setup and get
running.
> Since we all want more documentation and have it easy
to write documentation, we need to do something.
>
> The first thing that needs to be done is dropping the
DSSSL stylesheets in favor of XSLT. It has several
advantages:
> - XSLT is faster than DSSSL (citation needed)
> - I know nobody in PEAR that is familiar customizing
the current dsssl stylesheets
> - There are some PEAR devs that know XSLT
> - XSLT is more easy to setup
> - phpdoc, php-gtk-doc and Livedocs use XSLT, too
> - Switching to XSLT would bring us livedocs

Thats not true. livedocs has (almost) nothing to do with
either DSSSSSSL or XSL.


> - We could finally customize the looks of the manual on
the webpage and make it more user friendly. See http
://www.markwiesemann.eu/tmp/pear-manual4.png and the
discussion in http://news.php
.net/php.pear.doc/9704 (click the references to get more
shots)
>
>
> Since I currently am working on my diploma thesis,
someone else would need to take the lead in this project.
The following tasks are to be done:
> - Check out phpdoc and see if we can use its system
with as few changes as possible
> - Contact phpdoc people and ask them how to start best
> - Contact livedoc gsoc people and ask what we need to
do to be livedoc-compatible
> - When all info is collected, make peardoc's build
system to use xslt and support different sheets
> - Create XSLT sheets for the website, maybe modify the
standard html xslt for offline docs
>
>
> Having customized php-gtk-doc in a great deal, I have
experience in editing XSLT. You can count on my help once
this stage is reached.
>
> peardoc bug entry: http://pear
.php.net/bugs/bug.php?id=10843
> Livedocs gsoc project: http://de3.php.net/ideas
.php and http://wiki.phpdoc.i
nfo/LiveDocs

Greg and I talked about this couple of months ago (moving to
XSL) and
I am willing to take weekend in porting phpdoc-xsl to
peardoc if you
really really wants this... but I don't think its really
worth the
effort.
I will be working on livedocs for the next few months and I
would much
rather spend time on peardoc+livedocs than xsl

-Hannes

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

Hi Christian,

I think that is a great idea. For what its worth, I've just
posted Nexista
as a pear package on google's code project. I mention this
as nexista has
some useful xsl tools you may want to review.

I will likely setup a nexista channel in the future, but
first I'll need to
conform to PEAR's coding standards. 

Albert

On 6/1/07, Christian Weiske <cweiskecweiske.de> wrote:
>
> Hello all,
>
>
> Most of you which ever tried to compile peardoc know
that the dsssl
> stylesheets are a pain to setup and get running.
> Since we all want more documentation and have it easy
to write
> documentation, we need to do something.
>
> The first thing that needs to be done is dropping the
DSSSL stylesheets in
> favor of XSLT. It has several advantages:
> - XSLT is faster than DSSSL (citation needed)
> - I know nobody in PEAR that is familiar customizing
the current dsssl
> stylesheets
> - There are some PEAR devs that know XSLT
> - XSLT is more easy to setup
> - phpdoc, php-gtk-doc and Livedocs use XSLT, too
> - Switching to XSLT would bring us livedocs
> - We could finally customize the looks of the manual on
the webpage and
> make it more user friendly. See
> http
://www.markwiesemann.eu/tmp/pear-manual4.png and the
discussion in
> http://news.php
.net/php.pear.doc/9704 (click the references to get
more
> shots)
>
>
> Since I currently am working on my diploma thesis,
someone else would need
> to take the lead in this project. The following tasks
are to be done:
> - Check out phpdoc and see if we can use its system
with as few changes as
> possible
> - Contact phpdoc people and ask them how to start best
> - Contact livedoc gsoc people and ask what we need to
do to be
> livedoc-compatible
> - When all info is collected, make peardoc's build
system to use xslt and
> support different sheets
> - Create XSLT sheets for the website, maybe modify the
standard html xslt
> for offline docs
>
>
> Having customized php-gtk-doc in a great deal, I have
experience in
> editing XSLT. You can count on my help once this stage
is reached.
>
> peardoc bug entry: http://pear
.php.net/bugs/bug.php?id=10843
> Livedocs gsoc project: http://de3.php.net/ideas
.php and
> http://wiki.phpdoc.i
nfo/LiveDocs
>
>
> Further ideas are also welcome!
>
> --
> Christian Weiske
>
> --
> PEAR Development Mailing List (http://pear.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub
.php
>
>


-- 
My Blogs:
http://www.docunext.com/

http://www.albertlash.com/

Hannes Magnusson wrote:
> Greg and I talked about this couple of months ago
(moving to XSL) and
> I am willing to take weekend in porting phpdoc-xsl to
peardoc if you
> really really wants this... but I don't think its
really worth the
> effort.
> I will be working on livedocs for the next few months
and I would much
> rather spend time on peardoc+livedocs than xsl

Then having peardoc+livedocs makes more sense.

Arnaud.

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

Hannes,

> > - Switching to XSLT would bring us livedocs
> Thats not true. livedocs has (almost) nothing to do
with either DSSSSSSL or XSL.
Then I was wrongly informed. In php-gtk-doc I did the
livedocs with xslt, and we have a method to generated only
one single page only - also via xslt. I thought your
livedocs would be similar, but it seems I'm wrong here.

> I will be working on livedocs for the next few months
and I would much
> rather spend time on peardoc+livedocs than xsl
The main problem, that nobody is able to actually change
DSSSL sheets, remains and that means that we cannot deeply
influence pear's documentation on the website. Only xsl will
resolve that issue in my opinion.


Christian

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

On 6/1/07, Christian Weiske <cweiskecweiske.de> wrote:
> Hannes,
>
> > > - Switching to XSLT would bring us livedocs
> > Thats not true. livedocs has (almost) nothing to
do with either DSSSSSSL or XSL.
> Then I was wrongly informed. In php-gtk-doc I did the
livedocs with xslt, and we have a method to generated only
one single page only - also via xslt. I thought your
livedocs would be similar, but it seems I'm wrong here.

You generated "single pages" probably with
xsltproc using the xsl
stylesheets (xsltproc --stringparam rootid
<insert-id-here>
<xslt-stylesheet> <root.xml.file>, i.e. xsltproc
--stringparam rootid
function.strpos phpbook/phpboo-xsl/phpweb.xsl manual.xml to
generate
the strpos() manual page).

With livedocs you'll just hit http://localhost/strpos
in your browser and tata.

>
> > I will be working on livedocs for the next few
months and I would much
> > rather spend time on peardoc+livedocs than xsl
> The main problem, that nobody is able to actually
change DSSSL sheets, remains and that means that we cannot
deeply influence pear's documentation on the website. Only
xsl will resolve that issue in my opinion.

Indeed, which is why I moved phpdoc to use xsl few months
ago (well,
the main reason was actually I got fed up waiting more than
24hours
for a dsssl build..).

Anyway. If you really want to move to xsl and then again to
livedocs
in few months I'll make it happen, but I do recommend
waiting for
livedocs (unless there are major changes you want to
implement into
the docs _now_).

-Hannes

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

Hannes,


> You generated "single pages" probably with
xsltproc using the xsl
> stylesheets (xsltproc --stringparam rootid
<insert-id-here>
Yes. Wrapped in a catchall php script, you have live docs



> > The main problem, that nobody is able to actually
change DSSSL sheets, remains and that means that we cannot
deeply influence pear's documentation on the website. Only
xsl will resolve that issue in my opinion.
> Anyway. If you really want to move to xsl and then
again to livedocs
> in few months I'll make it happen, but I do recommend
waiting for
> livedocs (unless there are major changes you want to
implement into
> the docs _now_).

We have quite some ideas waiting in the pipe, but nobody had
the skill to implement them. With xsl, they are possible and
would be done now or tomorrow.

-- 
Christian

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

Christian Weiske wrote:

> We have quite some ideas waiting in the pipe, but
nobody had the skill
> to implement them. With xsl, they are possible and
would be done now
> or tomorrow.

Can you please elaborate what XSL would make possible for us
that is
currently not possible?

In the referenced post from me [1] there is a "no"
missing and a "a" too
much; my sentence should begin with "Switching to XSLT
would bring us no
benefit in this regard [...]". And BTW, the things
mentioned in that
thread are already visible in the online manual.

[1] http://news.php
.net/php.pear.doc/9704 

Regards,
Mark

-- 
http://www.markwiesemann.
eu

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

On 6/1/07, Hannes Magnusson <hannes.magnussongmail.com> wrote:
>
> Indeed, which is why I moved phpdoc to use xsl few
months ago (well,
> the main reason was actually I got fed up waiting more
than 24hours
> for a dsssl build..).


Is the "phpdoc" being mentioned in this thread
actually PhpDocumentor, or is
it something else?
-- 
CRB

Let me introduce you to my very own DMCA-protected
encryption key:
BC 1B 64 4A 8D DE 49 E8 C3 7D CC EE 1A AD EE F5
(compliments of Freedom-to-Tinker http://www.f
reedom-to-tinker.com/?p=1155)

On 6/1/07, Chuck Burgess <demon.genegmail.com> wrote:
>
> On 6/1/07, Hannes Magnusson <hannes.magnussongmail.com> wrote:
> >
> > Indeed, which is why I moved phpdoc to use xsl few
months ago (well,
> > the main reason was actually I got fed up waiting
more than 24hours
> > for a dsssl build..).
>
>
> Is the "phpdoc" being mentioned in this
thread actually PhpDocumentor, or
> is
> it something else?


It's the php manual, i.e. the php doc stuff, php doc team.
etc.

- Helgi