forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: import of xml.apache.org main site into forrest
Date Wed, 05 Jun 2002 12:26:36 GMT
Steven Noels wrote:
> 
> Hi all,
> 
> some mysterious motivational wind was blowing in my direction this
> evening, and I went haywire after my last visit to the ugly
> xml.apache.org main site.
> 
> Result:
> 
> - I've run all docs in the {xml-site}/sources/xml-site through the new
> docv10->docv11 translation stylesheet, tweaked the result manually, and
> imported the result of this into
> {xml-forrest}/src/documentation/content/xdocs/xml-site/
> - I rewrote the website.xml that came with it to our book.xml syntax,
> and added a link to the xml-site directory in our main book.xml

Don't want to rain on the party, but are you sure that xml-site/sources
contains the *uptodate* sources from all the various projects? I'm
pretty sure it doesn't.

This you do it to actually generate the xml.apache.org site or just as a
test?

> If all goes well, we have a draft version of the main xml.apache.org
> site at www.krysalis.org/forrest/xml-site/ after forrestbot has done its
> job.
> 
> What has this 3 hour exercise taught me:
> 
> - if the state of the other projects xml source files is comparable with
> those of the main site, we will need some thorough editorial review
> after migrating projects to forrest - people have been rather creative
> with the elements allowed by the old v10 DTD - using section-level
> elements instead of lists, inserting non-breakable spaces for table-like
> layout, <br>'s inside list items to mimick definition lists, etc... I
> haven't done much to solve these issues - so there's plenty of work for
> the editorially challenged amongst us :-)

Well, this is the reason why I'm scared from the use of more complex
DTDs and the lack of multi-channel output: People tend to 'tweak' the
markup based on the visual results, not the other way around.
 
> - we need to do something with the 'link' situation. Joerg, David et al,
> let's prepare a vote on this and resolve this thing. Now.

Done.

> - Please have a look at
> http://cvs.apache.org/viewcvs.cgi/xml-site/sources/website.xml?rev=1.27&
> content-type=text/vnd.viewcvs-markup which is the 'old' book.xml as has
> been used by the now defunct stylebook. I see <hidden> and <external>
> and I find these quite interesting. Your ideas?

I don't see the need for 'hidden' and the book.dtd shows that 'external'
is already in place (even if I don't see the need for it).
 
> - Previous xdocs didn't require an authors element being filled in - how
> will be solve this? Making authors optional again?

Yes, I wanted to raise this point earlier: there is no need to 'require'
a document to have an author. For example, I dislike the fact that even
the 'license.html' file has an author on top. It might lead to think
that the person is the author of the content of the page, rather than
the person who assembled the page from the content authored by other
people.

In those situations, it's much better to leave it out of the page.
 
> - Auto-generation of mini TOC's - should this be parametrizable? TOCs
> are generated now if sections exist within sections in a document, which
> was good for the forrest docs so far, but suboptimal for the content
> imported from the main site. On the other hand, these imported docs have
> been abusing the DTD to obtain certain visual effects, IMNSHO - so we
> could fix the docs, too.

I was going to patch this on my local copy removing the 'isfaq'
parameter (which semantically sucks!) and adding a 'minitoc' parameter.

Now, I believe the best place for 'behavioral skinning' controls should
be the book.xml file, which is sort of a high level site map (not in the
cocoon's sense of the term, but in the original 'map of the site' sense)

So, depending on the document, it's up to who links the documento to the
book to indicate whether or not this document should have particular
skinning behaviors associated. Examples might be:

 1) minitoc yes/no
 2) printable version yes/no
 3) multipage yes/no
 4) ???

allowing us to set those behaviors in a single location and separating
the concern from the document author simplifis the editor's job of
providing the best visual coherence and usability for the entire doco
corpus.

> - The bert skin - in general, I think the body text is a point (or two)
> too big - there isn't too much text on a screen. Bert, can we fix this?
> I know I can change the settings of my browser, but I believe the
> default font-size is 12pt, which is simply too big, showing too little
> content on a 1024*768 screen.

I agree.
 
> Please review the result of this little transition exercise and post
> other issues you come across with.

I'm offline so I don't have access (yet) to what you did, but I have a
few comments since I spent yesterday afternoon making myself up-to-date
with Forrest.

Things to note:

 1) the navigation path on top of the page is static. I mean, when you
change page, the path doesn't change. We *must* fix this before making
Forrest go live.

 2) the tabs are fake as well. this is another big showstopper.

 3) there is no DTD for .xgump and this makes the changes and toto DTDs
obsolete. Having a complete DTD for xgump and removing the obsoleted
DTDs is another showstopper.

 4) the javadoc DTD is unused and it doesn't seem that nobody is
interested in making it work for Forrest ATM. I propose to move it in
the scratchpad area.

Expect more things as I go along.
 
-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



Mime
View raw message