Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: docs@httpd.apache.org
Date: Thu, 6 Mar 2003 23:44:57 +0100
From: Jacek Prucia <jacek.prucia@acn.waw.pl>
To: docs@httpd.apache.org
Subject: Re: common docs infrastructure
Message-Id: <20030306234457.3b6426df.jacek.prucia@acn.waw.pl>
In-Reply-To: <n2m-g.1748ru3b5blrq$ndparker@news.perlig.de>
References: <20030305225735.62ac135d.jacek.prucia@acn.waw.pl>
	<n2m-g.1748ru3b5blrq$ndparker@news.perlig.de>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-2
Content-Transfer-Encoding: quoted-printable

On Thu, 6 Mar 2003 15:42:53 +0100
Andr=E9 Malo <nd@perlig.de> wrote:

> * Jacek Prucia wrote:
>=20
> > but it feels kinda wrong to start everything from scratch,
> > since we have httpd-docs subproject. A common look'n'feel for
> > documentation for all httpd subprojects -- sure sounds great.
>=20
> Of course, that would be cool. But, there are some further issues that ha=
ve=20
> to be solved. Currently the httpd-docs-2.0 repos is actually a symlink of=
=20
> httpd-2.0/docs (and will be released with httpd at all). So if/when we=20
> start with covering all httpd subprojects under a "httpd-docs", we should=
=20
> think about a more common repository structure.

Yes, but moving docs stuff outside main httpd-2.0 tree seems to be easy at
least for official releases. There is nifty release script, that does half =
of
the RM work, and it could take care of this (fetching xml's from cvs,
translating to html/PDF, moving output file to proper locations inside
httpd-2.0 tree). However, fresh httpd-2.0 checkout would have empty
docs/manual dir which kinda sucks.

> BTW: afaics, the actual=20
> subproject is httpd-test, not flood, isn't it (not sure...)?

Yes, httpd-test like I wrote in my original mail. However httpd-test is a
home for three software packages: mod_specweb, regression test for httpd and
flood. Overall activity (mails, developer commits) is way to small to have
separate subprojects, so we're all under this httpd-test umbrella.

> > 1. common.xsl is not really common... there are templates (super-menu f=
or
> > example) that are really httpd specific. So to use common.xsl for all
> > subprojects, we schould really rewrite it to be truly common. Specific
> > templates schould be in httpd.xsl and flood.xsl.
>=20
> xsl templates are by nature quite specific. As said above, the current=20
> repos is meant for httpd (has also the same branch point 2.0/2.1 etc).
> When we restructure all the stuff, let's rethink the xsl files resp. the=
=20
> places where they are stored. At this point it seems to be too early to g=
et=20
> specific with this.

Yeah, restructuring is a load of work. So for now I'll just copy common.xsl,
and tweak it a bit for flood needs. Later on, well think about a merge.

> > 2. After setting up all flood related files (ant build files,
> > stylesheets), it would be great if we could integrate them into
> > httpd-docs-build repo. That would probably mean that build.sh schould be
> > rewritten to accept project name as first argument, or something along
> > those lines.
>=20
> patches welcome ;-))

sure :)
=20
> > 3. Flood docs are really menat to be used on desktop machine. So besides
> > plain HTML (without MultiViews language extensions) a PDF file would be
> > great.
>=20
> hmm. And how to you want to distribute different languages?=20
> Language-Packages?

Yes. But to be honest flood isn't (and won't be in near future) as popular =
as
Apache web server. So I don't suspect there will be pressing need for
translation.

> This should differ from the online version anyway, where=20
> a webserver is running and content-negotiation can apply.

Yes.
=20
> Side note: there are some outstanding changes, according to=20
> content-negotitation. Type-maps, easier cross-language-switching, etc.=20
> Partially dependent on outstanding webserver patches ;-)
>=20
> > To
> > achieve this we could use Apache XML subproject -- Fop. If we could
> > develop common-fo.xsl, then httpd docs also could be transformed into P=
DF.
> > However that means build.sh schould accept another argument -- docs
> > format.
>=20
> The pdf stuff is already in progress.

Can I get my dirty hands on some tarball/repo? Maybe I could use some stuff=
 in
flood documentation.

> Although fop is not the best=20
> available PDF renderer, because it's quite limited -- for some reason it'=
s=20
> currently the choice.

Can you name a problem or two? I'm just curious. I think that fop, or at le=
ast
compatibile xml:fo engine is the best choice. LaTeX is really the best
software for such task, but it is a one hundred pound gorilla to install and
configure -- that would make building docs error prone.

> It's however, nearly ready, the last issues have to be resolved (font=20
> issues, some technical fun like unique anchor IDs etc.)
>=20
> > If anything written above seems simply too hard to achieve for some
> > reason, then fine -- we can have docs on our own. On the other hand -- =
it
> > would be great if we could at least have common look'n'feel. Please post
> > your opinions.
>=20
> Some actual suggestions about, where to store the flood docs contents and=
=20
> how to structure the httpd-docs fun would be cool.

here's quick layout:

httpd-docs/
   build.sh
   build.cmd
   target/
      httpd.xml
      flood.xml
   lib/
   style/
      common.xsl
      httpd.xsl
      flood.xsl
   httpd-1.3/
   httpd-2.0/
   flood/
   output/

This is a big oversimplification. I've skipped many files (language xsl's,
dtd's), just to ilustrate the concept. There are flaws for sure in this
layout, but I wanted to actually come up with something to start discussion.

Some notes on this layout: Yep, I think that xml files schould be placed in
subdirectories relative to build script. That way build.xml wont be transla=
ted
into build.html.en (yep... that exclude=3Dbuild/*.xml in patternset isn't
working... at least for me :). Another big change is the output dir. This
makes sense only, and only if all httpd docs are translated into xml. It su=
its
flood fine however, as we going to start with xml.

> > BTW. Since I had serious reason to post here, let me point out another
> > small issue: Why httpd-docs-build/lib dir is *so* bloated?
>=20
> Why not? ;-) All a bit of legacy stuff here. I don't have write access=20
> there. Someone else could clean up it a bit (Joshua, Erik? ;-)

It's just a suggestion. I don't see reason for all that cruft there, but I
just might be plain wrong. If there's no particular reason for all those ja=
rs
-- then let's get rid of it...

regards,
Jacek Prucia


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