xml build system

[Joshua Slive <jo...@slive.ca>]

OK.  It's time to get this problem solved.

At the moment, the new xml system is an obstacle to proper doc maintenance
rather than an aid.  This needs to be fixed pronto.  I had hoped to remain
XSLT-software agnostic and just let people use what they like, but this is
not working for two reasons:

1. We need a simple system so that people with no xslt knowledge can still
write docs.

2. We need a system that doesn't do stupid things like reorder the
attributes every time we update.

For these reasons, I think we need to settle now on a "recommended" build
system including xslt software.  Then we need to get that system installed
on cvs.apache.org so that people who don't want to configure it for
themselves can use that system.  We should still try to make our
stylesheets work in a variety of different parsers if we can, but once we
get a "default" system setup, we will veto any changes that break it. (In
retrospect, I probably should have vetoed Patrik's stylesheet changes that
broke the original build.sh/Ant/Xalan-J system, but I think it is too late
now.)

So, what should the recommended software be?  I am fine with Xalan-C++, as
long as we can get it setup on cvs.apache.org (Freebsd).  Patrik, would
you mind looking into getting Xalan-C++ compiled on cvs.apache.org and
writing up a simple set of instructions for people who need to build the
docs on that machine (along the lines of "cvs co httpd-2.0/docs/manual; cd
httpd-2.0/docs/manual/style; make; cd ../mod; cvs commit") along with a
similar set for people who want to build on their local machines.  You can
mail root@apache.org for things that need root permissions, but try not to
bug them until you have something that you know will work.

Joshua


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: xml build system

[Rich Bowen <rb...@rcbowen.com>]

On Wed, 8 May 2002, Justin Erenkrantz wrote:

> On Wed, May 08, 2002 at 07:28:37AM -0400, Rich Bowen wrote:
> > Agreed, but if most of the developers were to use an XML browser, the
> > conversion could be done, say, once a week, by someone with the
> > know-how, rather than having to have all of the individuals involved
> > know how to do it.
>
> The rationale for standardizing on a specific XML toolset is
> so that the conversions in the repository don't consistently
> flip-flop.
>
> Right now, if everyone were to use their own transformation
> tools and versions, the diffs in the repository would be
> horrendous.
>
> I would back the rationale for updating the HTML at the same
> time as the XML so that our website could be properly
> updated when the docs change.  -- justin

OK, this is a very good point, and I had not thought of that. I guess we
can presume that everyone with commit access has the necessary skills,
and access to tools, to do this. I just wish that we could put something
in a cvs checkin script to do this for us. For example, on my cvs
server, in $CSVROOT/commitinfo, I run a Perl syntax check on all .pm and
.pl files that get committed - basically a perl -cw - and reject commits
that don't pass. Using a similar mechanism, could we not run a XML->HTML
conversion on every commit of a xml file, and then guarantee that the
same tools are being used every time? Is there any reason *not* to do
this?

-- 
Rich Bowen - rbowen@rcbowen.com
http://kenya.rcbowen.com/


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: xml build system

[Justin Erenkrantz <je...@apache.org>]

On Wed, May 08, 2002 at 07:28:37AM -0400, Rich Bowen wrote:
> Agreed, but if most of the developers were to use an XML browser, the
> conversion could be done, say, once a week, by someone with the
> know-how, rather than having to have all of the individuals involved
> know how to do it.

The rationale for standardizing on a specific XML toolset is
so that the conversions in the repository don't consistently
flip-flop.

Right now, if everyone were to use their own transformation
tools and versions, the diffs in the repository would be
horrendous.  

I would back the rationale for updating the HTML at the same
time as the XML so that our website could be properly
updated when the docs change.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re[2]: xml build system

[Astrid Keßler <ke...@kess-net.de>]

> I can reliably crash mozilla 0.9.9 and 1.0RC (windows 2000) just by
> putting this in the URL bar:
> http://httpd.apache.org/docs-2.0/mod/mod_alias.xml

for information:
mozilla 1.0RC1 (Gecko/20020417) on win 2000 is doing fine with this url.

Kess


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: xml build system

[Joshua Slive <jo...@slive.ca>]

On Wed, 8 May 2002, Rich Bowen wrote:
> At the moment, I'm using 0.9.9, and not doing anything special at all. I
> have not upgraded to the latest stuff, which is supposed to be release
> candidate.

This is strange.  Are you viewing them over the local filesystem or
through a web server?  If through a web server, what mime types are you
using for the .xml and .xsl files?

I can reliably crash mozilla 0.9.9 and 1.0RC (windows 2000) just by
putting this in the URL bar:
http://httpd.apache.org/docs-2.0/mod/mod_alias.xml

Joshua.



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: xml build system

[Rich Bowen <rb...@rcbowen.com>]

On Tue, 7 May 2002, Joshua Slive wrote:

> Rich Bowen wrote:
> > On Tue, 7 May 2002, Joshua Slive wrote:
>
> >>1. We need a simple system so that people with no xslt knowledge can still
> >>write docs.
>
> > I am not clear why this is a problem. Mozilla understands the XML
> > without conversion. You can work on the XML, verify that it is is
> > correct, and commit it, all without generating HTML. I think that's a
> > better system for folks, like myself, that are either unable, or too
> > lazy, to do the conversion. Just get the latest Mozilla, and use that as
> > your converter.
>
> I agree, in general, that you don't need much XML knowledge to do the
> authoring, and that is great.  (Although Mozilla is giving me fits,
> personally.  I can't get it to do anything other than crash hard or
> render the xml as plain text since we added the multi-lingual stuff to
> manual.xsl.  What version are you using?  Do you have any special
> tricks? MSIE 6.0, on the other hand, seems to work like a charm.)

At the moment, I'm using 0.9.9, and not doing anything special at all. I
have not upgraded to the latest stuff, which is supposed to be release
candidate.

> But the transformations do eventually (sooner rather than later) need to
> get committed to the docs as html.  And it is just way to complicated to
> make that happen at the moment.

Agreed, but if most of the developers were to use an XML browser, the
conversion could be done, say, once a week, by someone with the
know-how, rather than having to have all of the individuals involved
know how to do it.

> Perhaps I overstated the severity of the situation in a fit of
> frustration.  But I still think we need to standardize and get a good
> set of instructions.

Definately agreed. Personally, I have no clue how to do the conversion,
and have none of the necessary tools installed. I'd like to know what
the easy approved way is, and when instructions were posted earlier, I
managed to miss or ignore them.

-- 
Rich Bowen - rbowen@rcbowen.com
Author - Apache Administrator's Guide
http://www.ApacheAdmin.com/


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: xml build system

[Joshua Slive <jo...@slive.ca>]

Rich Bowen wrote:
> On Tue, 7 May 2002, Joshua Slive wrote:

>>1. We need a simple system so that people with no xslt knowledge can still
>>write docs.

> I am not clear why this is a problem. Mozilla understands the XML
> without conversion. You can work on the XML, verify that it is is
> correct, and commit it, all without generating HTML. I think that's a
> better system for folks, like myself, that are either unable, or too
> lazy, to do the conversion. Just get the latest Mozilla, and use that as
> your converter.

I agree, in general, that you don't need much XML knowledge to do the 
authoring, and that is great.  (Although Mozilla is giving me fits, 
personally.  I can't get it to do anything other than crash hard or 
render the xml as plain text since we added the multi-lingual stuff to 
manual.xsl.  What version are you using?  Do you have any special 
tricks? MSIE 6.0, on the other hand, seems to work like a charm.)

But the transformations do eventually (sooner rather than later) need to 
get committed to the docs as html.  And it is just way to complicated to 
make that happen at the moment.

Perhaps I overstated the severity of the situation in a fit of 
frustration.  But I still think we need to standardize and get a good 
set of instructions.

Joshua.





---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: xml build system

[Rich Bowen <rb...@rcbowen.com>]

On Tue, 7 May 2002, Joshua Slive wrote:

> OK.  It's time to get this problem solved.
>
> At the moment, the new xml system is an obstacle to proper doc maintenance
> rather than an aid.  This needs to be fixed pronto.  I had hoped to remain
> XSLT-software agnostic and just let people use what they like, but this is
> not working for two reasons:
>
> 1. We need a simple system so that people with no xslt knowledge can still
> write docs.

I am not clear why this is a problem. Mozilla understands the XML
without conversion. You can work on the XML, verify that it is is
correct, and commit it, all without generating HTML. I think that's a
better system for folks, like myself, that are either unable, or too
lazy, to do the conversion. Just get the latest Mozilla, and use that as
your converter.

-- 
Who can say where the road goes
Where the day flows
Only time
 --Pilgrim (Enya - A Day Without Rain)


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org