[doc] Derby web site doc formats

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

[doc] Derby web site doc formats

Jean T. Anderson
An off topic thread is included down below and the most recent post
brings up the issue of doc formats for the web site.

I think the derby web site should support a bunch of file formats. Some
suggestions are here, but the list isn't complete:

http://incubator.apache.org/derby/papers/index.html#How+to+Contribute+Papers

What are other formats are easy for folks to work with and should be
promoted?

How about tips for making a doc easily integrated with the forrest site?
For example, I've noticed that the following html things foil forrest's
attempt to generate a doc with site navigation:

  1) Inclusion of a table of contents because forrest itself wants to
generate the table of contents.
  2) If the first section doesn't start with an <h1>....</h1> heading,
you'll get a blank page.
  3) I've never gotten forrest to generate a coherent page from an MS
word-generated html file.

Whenever I've encountered a problem, I have simply included the file as
raw html (without the forrest navigation). But if there's a way to
integrate them better, I'm open to suggestion -- and open especially to
the assistance of volunteers to get them well integrated!


  -jean




-------- Original Message --------
Subject: Re: [RESULT] [VOTE] accept derby client contribution
Date: Mon, 02 May 2005 15:10:58 -0500
From: scott hutinger <[hidden email]>
Reply-To: Derby Development <[hidden email]>
To: Derby Development <[hidden email]>
References: <[hidden email]>
<[hidden email]> <[hidden email]>

I agree with Susan and Jean,

One should be able to send docs in html or xml if they want.  I don't
think a lot of people want to mess with xml.  The other option, is using
OpenOffice, and letting forrest convert the OpenOffice document,
although I think if many options are used, some of the doc may be a bit
modified from original.  Of course, a lot of other formats exist.

Possibly the docs should be updated on how to send in documents.  I
don't think a lot of people want to mess with the XML stuff, and the
import thing is the content, not the type of document.  Some people just
don't have time to figure out the xml syntax forrest uses.

Possibly a list of preferred formats should be created.  I don't think
it's a good idea to force one document style on people.

scott

Satheesh Bandaram wrote:

>I am OK with formatting it. If forrest option is preferred, I can look
>into that. I thought Jean was suggesting putting it up in HTML format?
>
>Satheesh
>
>Susan Cline wrote:
>
>  
>
>>...  Okay, I'll modify the Papers tab to include a Derby Network
>>Client section and add a link to the functional spec which is in raw
>>html, unless you want to format it in forrest.xml.
>>...
>>    
>>
>
>
>Jean T. Anderson wrote:
>
>  
>
>>Susan Cline wrote:
>>
>>    
>>
>>>...  My feeling is whoever contributes a paper should take the
>>>responsibility to format it in the desired way prior to asking
>>>someone to update the site, just like patches need to be in a
>>>specific format prior to submission.
>>>...
>>>      
>>>
>>+1
>>
>>That much said, volunteers with cycles/desire to improve the format of
>>content are always welcome -- all you need do is offer and I'm sure
>>you'll have many takers.
>>
>> -jean
>>
Reply | Threaded
Open this post in threaded view
|

Re: [doc] Derby web site doc formats

Susan Cline
One other 'oddity' of forrest xml I have noticed to add to the list is not only does the first
heading need to be an <h1> </h1> set of tags, but all subsequent tags have to be
follow in order of size.  For instance, if the first set of tags is an <h1>, the second set must
be an <h2> *before* an <h3> can be rendered.
 
So this would work:
 
<h1>First heading, Biggest Size</h1>
<h2>Second heading, Second Biggest Size</h2>
<h3>Third heading, Third Biggest Size</h3>
 
But this would not:
 
<h1>First heading, Biggest Size</h1>
<h3>Second heading, Third Biggest Size</h3>
<h2>Third heading, Second Biggest Size</h2>
 
Since the <h3> set of tags is prior to the <h2> set of tags.
 
Susan

"Jean T. Anderson" <[hidden email]> wrote:
[snip]

How about tips for making a doc easily integrated with the forrest site?
For example, I've noticed that the following html things foil forrest's
attempt to generate a doc with site navigation:

1) Inclusion of a table of contents because forrest itself wants to
generate the table of contents.
2) If the first section doesn't start with an

....

heading,
you'll get a blank page.