Converting docs to XHTML

[Joshua Slive <sl...@finance.commerce.ubc.ca>]

There is a proposal outstanding on the apache-docs list to convert the
docs to XHTML.  The reasons for this are:

1. The docs are currently in HTML3.2 and there are some basic HTML
features that can't be used because they won't validate under this DTD.

2. If we are going to move to another DTD, we might as well move all the
way to the leading edge and go to XHTML.

I am bringing this up here, because I want to make sure that this will not
put a barrier in the way of developers properly documenting their work.
XHTML is very similar to HTML, but it is a little less forgiving in terms
of unclosed tags, case, etc.  If this conversion would adversly affect
your ability to document your work, please speak up now.

Discussion should go to apache-docs@apache.org.

Joshua.

Re: Converting docs to XHTML

[Tony Finch <do...@dotat.at>]

Joshua Slive <sl...@finance.commerce.ubc.ca> wrote:
>
>For this to work, someone would need to invest a significant chunk of time
>in developing the format, and making sure that tools were available
>to convert it to other formats.

Don't bother -- use DocBook instead: the tools are already available
and they are widely used.

Tony.
-- 
f.a.n.finch     dot@dotat.at     fanf@covalent.net     Chad for President!

Re: Converting docs to XHTML

[Joshua Slive <sl...@finance.commerce.ubc.ca>]

I'm not sure how much DocBook gains us.  I can see the following benefits:
- easy conversion to non-html formats (like print)
- conformaty with other open-source projects.

Besides that, I don't see the advantage over XHTML.

If I were to imagine the ultimate format, it would be XML that was
specifically structured for our needs.  For example, a module doc could
look like

<module>
<module-name>mod_access</module_name>
<module-source-name>mod_access.c</module_name>
<summary>blah blah</summary>

<directive>
<directive-name>Allow</directive-name>
<directive-syntax>blah blah</directive>
...
</directive>

...
</module>

(I make no claim that this is actually XML.)

Re: Converting docs to XHTML

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

Guille -bisho- wrote:
> 
> >There is a proposal outstanding on the apache-docs list to convert the
> >docs to XHTML.  The reasons for this are:
> [...]
> 
> And why not go directly to XML???

Because writing XML by hand sucks, and the existing XML development
tools suck worse.

I write in POD, because it allows me to write content without having to
stop every 12 seconds to think about formatting. Writing in just about
any "markup language" is icky, because it hinders the flow of content.
Using WYSIWYG tools is icky, because it invariably produces bad *ML.

One needs to pick somethat is a moderate middle ground - something that
has a manageable way to write content, so that there is not such a high
barrier to entry that you drive off all your authors. It's going to hard
enough to get a decent pod2xhtml converter without going to XML.

Yes, I can be educated, and I can write HTML (or *ML) if necessary. But
I'd rather not. I enjoy writing. I hate formatting and markup languages.
It's not a natural part of writing. Since that part is, however, a
necessary evil, I'd like to limit how evil it is. XML would push it past
my evil tolerance.

Of, course, that's just my $0.02, and may not count for much. If XML has
any real benefits, I can be persuaded. XML has, for a long time, struck
me as something that "everyone" thinks is wonderful, but in actual
practice does not have any real benefits.

Rich
-- 
Author: Apache Server Unleashed - www.apacheunleashed.com
Director of Web Application Development - http://www.cre8tivegroup.com/

Re: Converting docs to XHTML

[Joshua Slive <sl...@finance.commerce.ubc.ca>]

On Fri, 1 Dec 2000, Guille -bisho- wrote:

> >There is a proposal outstanding on the apache-docs list to convert the
> >docs to XHTML.  The reasons for this are:
> [...]
> 
> And why not go directly to XML???
> 

I have no objection to that.  It may be a good idea.  However, it is not
something that should be done ad-hoc or in a hurry.  Certainly, the
version distributed with Apache and to the mirrors would need to be in
HTML, since we need something that can be read with the base webserver on
pretty much any browser.

For this to work, someone would need to invest a significant chunk of time
in developing the format, and making sure that tools were available
to convert it to other formats.

In any case, converting to XHTML is probably a good first step in
converting to more generic XML.

Joshua.

Re: Converting docs to XHTML

[Guille -bisho- <bi...@eurielec.etsit.upm.es>]

>There is a proposal outstanding on the apache-docs list to convert the
>docs to XHTML.  The reasons for this are:
[...]

And why not go directly to XML???

All the apache docs usually follows the same structure, so it would be easy to
define a set of tags for each function:

<type>Module</type>
<name>rnnrngrg lkngngsln </name>
<params></params>
...

Later it would be really easy to convert the buch od XML into any kind of
document, XTML, PDF and so on, and selecting only certain information.

Also searches will be really better because in XML you clasify the
information, in spite of show it up.

-- 
     \|||||||/    Guillermo Pérez Pérez
     < o   o >      - bisho@onirica.com
      \  L  /       - bisho@eurielec.etsit.upm.es
 -oOOo-------oOOo-
 Onírica: Análisis, diseño e implantación de soluciones informáticas
          http://www.onirica.com

Re: Converting docs to XHTML

[Greg Stein <gs...@lyra.org>]

On Wed, Nov 29, 2000 at 11:44:04AM -0800, Joshua Slive wrote:
> 
> There is a proposal outstanding on the apache-docs list to convert the
> docs to XHTML.  The reasons for this are:

+1

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/

Re: Converting docs to XHTML

[Greg Stein <gs...@lyra.org>]

On Wed, Nov 29, 2000 at 11:44:04AM -0800, Joshua Slive wrote:
> 
> There is a proposal outstanding on the apache-docs list to convert the
> docs to XHTML.  The reasons for this are:

+1

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/