httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacek Prucia <jacek.pru...@acn.waw.pl>
Subject Re: common docs infrastructure
Date Thu, 06 Mar 2003 22:44:57 GMT
On Thu, 6 Mar 2003 15:42:53 +0100
André Malo <nd@perlig.de> wrote:

> * Jacek Prucia wrote:
> 
> > 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.
> 
> Of course, that would be cool. But, there are some further issues that have 
> to be solved. Currently the httpd-docs-2.0 repos is actually a symlink of 
> httpd-2.0/docs (and will be released with httpd at all). So if/when we 
> start with covering all httpd subprojects under a "httpd-docs", we should 
> 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 
> 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 for
> > 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.
> 
> xsl templates are by nature quite specific. As said above, the current 
> 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 
> places where they are stored. At this point it seems to be too early to get 
> 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.
> 
> patches welcome ;-))

sure :)
 
> > 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.
> 
> hmm. And how to you want to distribute different languages? 
> 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 
> a webserver is running and content-negotiation can apply.

Yes.
 
> Side note: there are some outstanding changes, according to 
> content-negotitation. Type-maps, easier cross-language-switching, etc. 
> Partially dependent on outstanding webserver patches ;-)
> 
> > 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 PDF.
> > However that means build.sh schould accept another argument -- docs
> > format.
> 
> 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 
> available PDF renderer, because it's quite limited -- for some reason it's 
> currently the choice.

Can you name a problem or two? I'm just curious. I think that fop, or at least
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 
> issues, some technical fun like unique anchor IDs etc.)
> 
> > 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.
> 
> Some actual suggestions about, where to store the flood docs contents and 
> 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 translated
into build.html.en (yep... that exclude=build/*.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 suits
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?
> 
> Why not? ;-) All a bit of legacy stuff here. I don't have write access 
> 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 jars
-- 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


Mime
View raw message