avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Berin Loritsch" <blorit...@apache.org>
Subject Xdocs DTD (was RE: Small reorg of excalibur site)
Date Fri, 19 Jul 2002 02:43:58 GMT
>From the jakarta-site2 source code:

    <author email="jon@latchkey.com">Jon S. Stevens</author>
    <author email="husted@apache.org">Ted Husted</author>
    <title>Contacting Us</title>

  <section name="Contacting Us About ...">
<h3>Product Support</h3>

If you have questions or comments about the software or documentation on
this site, 
please subscribe to the appropriate mailing list: 

<a href="./mail.html">Mailing lists</a>

<h3>Security Issues</h3>
<img src="/images/jon-security.jpg" alt="jon-security.jpg" width="201"
height="330" />
<!-- cut short -->


Now, this may be an abuse of anakia's DTD, but it is what I consider
exemplary of anakia documentation.  Here is what I don't like:

1) <h3/>  What is with starting with the header 3 tag?  Probably the
   documentation should have a nested <section> but it is not there.

2) <a href="...."/>  The current DTD has better and richer linking
   semantics.  For instance, without knowledge of HTML, we can easily
   represent forcing a new page to open, declare an anchor, or link
   to a document.  Instead of all the different types of <a/> tags,
   we have these:
   <fork/> <link/> <anchor/>

3) <img/>  I like declaring what the image is for.  Is it an icon?
   Is it a figure/illustration?  Our current DTD let's us make that
   distinction, and we treat them differently:
   <icon/> <figure/>

4) Is there any notion of special blocks of text?  For instance we
   currently have <warn/> <note/> so that we can specially render
   those blocks of text to call attention to them.

5) This is something that needs to change in both document formats.
   I would like to autogenerate the project/book.xml for a group of
   files so that we don't have to manually edit the doc if it exists.

Tell me if I am mistaken, and you can point me in the direction of
the official DTD online?  I don't want hap hazard docs.

> From: Peter Donald [mailto:peter@apache.org] 
> Sent: Thursday, July 18, 2002 7:02 PM
> To: Avalon Developers List
> Subject: Re: Small reorg of excalibur site
> On Friday 19 July 2002 03:53, Berin Loritsch wrote:
> > Like I said, I got the stuff working.  In another thread I said I 
> > don't really care if we use Anakia or Cocoon to do the generation. 
> > That really doesn't concern me one way or the other.  I am 
> saying that 
> > I don't want <div/> tags in my XML.  I want to use a DTD that we #1 
> > already agreed upon, and #2 represents the semantic intent of the 
> > document better.
> >
> > I *know* Anakia can work with the current DTD.  If it 
> can't, then we 
> > can supply a stylesheet to make the transformation at build time. 
> > Either way I don't really care how it gets done.  I don't want an 
> > unorganized and broken DTD.
> Which is interesting to say the least. You know what the 
> differences between 
> anakias and cocoons dtd ...
> s1 --> section
> s2 --> subsection
> person --> author
> @title --> @name
> Yet cocoons one represents the semantic content of the 
> document better .... 
> hmmm
> -- 
> Cheers,
> Peter Donald
> *------------------------------------------------------*
> | "Common sense is the collection of prejudices        |
> |  acquired by age 18. " -Albert Einstein              |
> *------------------------------------------------------* 
> --
> To unsubscribe, e-mail:   
> <mailto:avalon-dev-> unsubscribe@jakarta.apache.org>
> For 
> additional commands, 
> e-mail: <mailto:avalon-dev-help@jakarta.apache.org>

To unsubscribe, e-mail:   <mailto:avalon-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-dev-help@jakarta.apache.org>

View raw message