Hannes Magnusson | 1 Jun 11:37 2007
Picon

Re: Moving peardoc to XSLT

On 6/1/07, Christian Weiske <cweiske <at> cweiske.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
>
(Continue reading)

Arnaud Limbourg | 1 Jun 11:45 2007

Re: Moving peardoc to XSLT

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

Christian Weiske | 1 Jun 11:57 2007
Picon

Re: Moving peardoc to XSLT

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

Hannes Magnusson | 1 Jun 12:54 2007
Picon

Re: Moving peardoc to XSLT

On 6/1/07, Christian Weiske <cweiske <at> cweiske.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_).
(Continue reading)

Christian Weiske | 1 Jun 13:12 2007
Picon

Re: Moving peardoc to XSLT

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

Mark Wiesemann | 1 Jun 13:18 2007
Picon
Picon

Re: Moving peardoc to XSLT

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

Christian Weiske | 1 Jun 22:05 2007
Picon

Re: Moving peardoc to XSLT

Mark,

> 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 [...]".
Then I misunderstood you.

> Can you please elaborate what XSL would make possible for us that is
> currently not possible?
We could put the stuff we're doing with php right now (linking package page and this toc generation) into
manual generation itself, but performance isn't the issue now.
We also could automatically link <classname>, <function> and <method> tags to their appropriate API
documentation pages.

Btw, I didn't see that it already works because
http://pear.php.net/manual/en/package.system.folders.php
and
http://pear.php.net/manual/en/package.system.windrives.windrives.system-windrives.php
don't link the package page, and the classname is still there in the method list.

Another suggestion:
The "Download documentation" should be below and separated by a <hr/> from package info and api doc links.

So if nobody else beside me thinks xslt would be nice, we should bury this idea.

-- 
Christian

--

-- 
PEAR Development Mailing List (http://pear.php.net/)
(Continue reading)

Mark Wiesemann | 1 Jun 22:15 2007
Picon
Picon

Re: Moving peardoc to XSLT

Hi Christian,

Christian Weiske wrote:
> We could put the stuff we're doing with php right now (linking package
> page and this toc generation) into manual generation itself, but
> performance isn't the issue now. We also could automatically link
> <classname>, <function> and <method> tags to their appropriate API
> documentation pages.

The first thing isn't really an issue currently, the second thing should
be possible with Livedocs.

> Btw, I didn't see that it already works because
> http://pear.php.net/manual/en/package.system.folders.php
> and
> http://pear.php.net/manual/en/package.system.windrives.windrives.system-windrives.php
> don't link the package page, and the classname is still there in the
> method list.

That's because you're not following the standard scheme for the IDs. It
should be e.g. "package.system.system-folders". (Otherwise the package
name detection fails, and neither the two links will be added, nor the
package name will be removed, nor will the "file a bug report" link on
the bottom point to the package's bug report form.)

> Another suggestion:
> The "Download documentation" should be below and separated by a <hr/>
> from package info and api doc links.

Good point, I've changed it in CVS.
(Continue reading)

Chuck Burgess | 1 Jun 15:59 2007
Picon

Re: Moving peardoc to XSLT

On 6/1/07, Hannes Magnusson <hannes.magnusson <at> gmail.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.freedom-to-tinker.com/?p=1155)
Picon

Re: Moving peardoc to XSLT

On 6/1/07, Chuck Burgess <demon.gene <at> gmail.com> wrote:
>
> On 6/1/07, Hannes Magnusson <hannes.magnusson <at> gmail.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
Mark Wiesemann | 1 Jun 16:13 2007
Picon
Picon

Re: Moving peardoc to XSLT

Hi Chuck,

Chuck Burgess wrote:
> On 6/1/07, Hannes Magnusson <hannes.magnusson <at> gmail.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?

No, it is the name of the CVS module for the PHP manual.

Regards,
Mark

-- 
http://www.markwiesemann.eu

--

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


Gmane