httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <jos...@slive.ca>
Subject Re: Antwort: Re: XML format for manual pages (was Re: German translation)
Date Mon, 15 Jul 2002 20:02:42 GMT

OK.  Let me start by congratulating you on the very good work you've done.
It looks like you put a good chunk of work into this, and I think that
pretty much everything you have done is an improvement (although I could
argue with your choice of colors ;-)

On Mon, 15 Jul 2002 Michael.Schroepl@telekurs.com wrote:
> I explicitly said why I used Apache 1.3: Exactly _be-
> cause_ most of you may consider it outdated, and it
> isn't in full maintenance any more.

Sorry, I hadn't understood that in my quick reading.

> Whichever Apache version would be ported to using CSS,
> the main work would have to be identifying which logical
> concepts are to be used to construct Apache documents
> (like "this is an example" or "this is a directive")
> and then use appropriate classes inside the HTML code.

Here is were I think it becomes a problem that you are using 1.3 for your
example.  In the mod/ directory of the 2.0 docs, we have converted
entirely to xml, and in the style/ directory there is a modulesynopsis.dtd
and common.dtd that show all the logical concepts that we used, including
<example>, <directive>, <note>, <section>, etc.  With Astrid's recent
work, we also have a manualpage.dtd which should be the basis for
converting the rest of the docs to a similar format.  Even if you aren't
an xml expert (and lord knows I'm not), these things should be relatively
straightforward to understand.

It makes no sense to redo this work when it is already well underway. We
can get all the benefits of css, plus we get enforced consistency, easier
authoring, etc, by going with xml and xslt.  If you look at the xml and
html files in httpd-2.0/docs/manual/mod/, you will see that they are much
closer to what you want.  The xslt process generates well-formed html
(although not necessarily xhtml), and the docs are MUCH more consistent in
format and presentation.

In order to make better use of css, we probably need to change the xslt
quite a bit.  For example, at the moment we transform

<example><title>example 1</title>
yada yada
</example>

into a complicated table/blockquote thing.  Alternatively, we could follow
your example and transform this in the xslt to

<div class="example">
<h4 class="example">example 1</h4>
yada yada
</div>

And then use the css to do the fancy display aspects.  That is the sort of
changes I would like to see, and they should be relatively easy to do.

In addition, I think that apart from css, the new module docs could be
made to look much nicer by someone skilled in web design.

I hope that gives you a little better understanding of why I don't know
where to go with all the great work that you did.  Perhaps it would help
to get us all on the same page if you took a more detailed look at
httpd-2.0/docs/manual/style/ and httpd-2.0/docs/manual/mod/ plus
http://httpd.apache.org/docs-project/docsformat.html

Thanks.

Joshua.


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


Mime
View raw message