As a placeholder, I threw together a way to take the html docs that were being contributed and get them to render as part of the website.
So right now, I think all the doc contributions in JIRA have been integrated into the website. I just pushed it out to the staging machine, and it will be live w/in a few hours (I forget the sync schedule). Anyway, it looks ok. You'll see that I incorporated the css, which makes our menu on the LHS look odd. I suppose we should just create a site-wide stylesheet and use that? geir Morozova, Nadezhda wrote: > Alexey, > > Thanks for your help and interest. > Yes, I have thought of this conversion. In fact, I have tried one - see > email I have just sent with an XML I've produced. > I did all the replacements manually, but having a script with regular > expressions search-and-replace mechanism would be just great. > As I see, to convert an HTML doc (I am primary thinking of classlib and > drlvm docs just now), we'll need to: > > 1. Run a code sweeper to ensure XML markup validity, like changing <br> > to <br />. Same for <img>, <li> (optional closing tag is often omitted) > and some others. > > 2. Run a script or do a number of manual replacements to fix <hx> > headings, redundant fonts, and change linking. In HTML, it's done by > having an anchor and referencing its name. for the website, I've noticed > that this model works, but because the anchor is after the <section> > declaration, clicking the link takes you to the text of the section - > without showing the section title. To avoid that, I've removed anchors > from <section> and <subsection> and referenced the element names > directly. This actually works simpler, but requires editing during > conversion. > > 3. Apply a stylesheet and test doc L&F. > I am not proficient enough to do it at this stage :( all I can do is > ensure styles coded inside the Anakia transformation engine appear ok :) > > It would be great if you helped me with this. > > > > Best regards, > Nadya Morozova, > > > -----Original Message----- > From: Ivanov, Alexey A [mailto:[EMAIL PROTECTED] > Sent: Thursday, August 03, 2006 2:59 PM > To: harmony-dev@incubator.apache.org > Subject: RE: [doc]proposal to improve and expand website > > Nadezhda, > > I've looked through the structure of site directory, and I think there > should be no problem in converting the docs into XML whatever the > formatting is. (I must say that I studied the XSL transformation rather > than the Anakia one. But both of them should give the same result.) > > As far as I understand the <hX> tags are to be converted to <section> > and <subsection>, all other tags may be left without any change. Also > the header (<meta>, <title>) information needs converting. > > I think there should be a way to link in additional CSS style sheet to > preserve the original formatting. And CSS style sheets might need > adjusting because of the change in the resulting HTML document > structure, but it shouldn't be too complex though. > > I can try to convert one of the docs. Shall I try? > And there may be a way to automate the conversion using a script. > > > Any other thoughts? > > > Regards, > -- > Alexey A. Ivanov > Intel Middleware Product Division > > >> -----Original Message----- >> From: Ivanov, Alexey A [mailto:[EMAIL PROTECTED] >> Sent: Thursday, August 03, 2006 12:54 PM >> To: harmony-dev@incubator.apache.org >> Subject: RE: [doc]proposal to improve and expand website >> >> Nadezhda, >> >> Thank you for your explanation. I've never looked at the internals. >> I'll look through it before making any suggestions. >> >> I hope I'll be able to help here. >> >> Regards, >> -- >> Alexey A. Ivanov >> Intel Middleware Product Division >> >> >>> -----Original Message----- >>> From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] >>> Sent: Thursday, August 03, 2006 12:14 PM >>> To: harmony-dev@incubator.apache.org >>> Subject: RE: [doc]proposal to improve and expand website >>> >>> Alexey, >>> >>> If you look into the structure of the Harmony website, you'll see that >>> permanent pages are originally written in XML, then built with Ant >> using >>> Anakia for XML>HTML transformation into normal HTML. So, the source > XML >>> files are stored in xdocs/ and resulting HTML files in docs/. This is >>> described in README.txt in harmony/standard/site/. >>> >>> So far, external materials on classlib packages were placed in HTML in >>> docs/externals directory as a read-only copy from repository. >>> Now, as I understood Geir, the number of useful materials that are >>> relatively stable grows (5 classlib docs + several drlvm docs) and >>> placing them all in externals/ does not seem reasonable any more. So, >>> Geir has suggested, and Tim Ellison has agreed that we need to > transfer >>> the external HTML files to the XML format and make them part of site >>> this way. >>> >>> The issue is the volume of this task. For a short HTML doc, you can >>> transfer the content fairly easily: change <h> tags to <section> and >>> <subsection> and leave <p> and <ul> tags as they are interpreted >>> normally. However, for longer docs with a variety of CSS styles > applied >>> and various content unit used, e.g. notes, definition lists, formatted >>> tables, and so forth. For such formatting-rich documents, the HTML > >> XML >>> transfer does not appear so linear. As I understand, this will take a >>> significant amount of manual editing. Or am I missing something? >>> Your suggestions on format transformations are most welcome :) >>> >>> >>> Best regards, >>> Nadya Morozova, >>> >>> >>> -----Original Message----- >>> From: Ivanov, Alexey A [mailto:[EMAIL PROTECTED] >>> Sent: Thursday, August 03, 2006 11:25 AM >>> To: harmony-dev@incubator.apache.org >>> Subject: RE: [doc]proposal to improve and expand website >>> >>> Nadezhda, >>> >>>> -----Original Message----- >>>> From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] >>>> Sent: Wednesday, August 02, 2006 8:52 PM >>>> To: harmony-dev@incubator.apache.org; [EMAIL PROTECTED] >>>> Subject: RE: [doc]proposal to improve and expand website >>>> >>>> Geir, >>>> Let me double-check what exactly you are proposing: >>>> >>>>> I wonder if it's time we pull that stuff out of classlib/ and move >> to >>>>> the site itself... >>>> Do you mean that we do the following: >>>> 1) Move the ASN1 and REGEXP docs out of docs/externals to >>>> xdocs/subcomponents/classlib by converting them to XML? >>> What kind of XML do you mean? I just can't understand. >>> >>>> 2) Move the html docs packaged with classlib donations (JNDI DNS, > AWT, >>>> JAVA2D) to the same directory with conversion involved? >>>> >>>> I'd also recommend that we do the same for stable VM docs, like >>> DevGuide >>>> and Getting Started. >>>> >>>> Now, the idea of integrating the docs into the site is just fine with >>>> me. >>>> >>>> However, the docs are very HTML-driven now, so you can't just >> cut&paste >>>> the HTML content with a couple of manual replacements and have a > valid >>>> XML. There're over 15 styles that cannot map to standard XML tags. >>> We'll >>> >>> What are standard XML tags? Or do you mean XHTML? >>> Or am I just missing anything? >>> >>> >>> Thank you in advance, >>> Alexey. >>> >>>> have to think of some content model and a DTD for those, probably. > And >>>> still this will mean a lot of work. >>>> So I was wondering whether it is worth the effort? What will the > major >>>> benefits of conversion be? Couldn't we just have the docs statically >> in >>>> HTML? At least for now? >>>> >>>> Best regards, >>>> Nadya Morozova, >>>> >>>> -----Original Message----- >>>> From: Geir Magnusson Jr [mailto:[EMAIL PROTECTED] >>>> Sent: Wednesday, August 02, 2006 6:32 PM >>>> To: harmony-dev@incubator.apache.org >>>> Subject: Re: [doc]proposal to improve and expand website >>>> >>>> >>>> >>>> Morozova, Nadezhda wrote: >>>> >>>>> I scanned the svn repository for classlib packages, and found a few >>>> more >>>>> that had docs with them, namely the JNDI DNS Service Provider, the >>> AWT >>>>> framework and the Java2D implementation. I could move their docs to >>>> the >>>>> externals/ directory as well. >>>>> Now, this makes multiple docs in one folder, so I thought I'd group >>>> all >>>>> classlib package docs into a classlib/ subfolder and all DRLVM docs >>>> into >>>>> the drlvm/ subfolder. Shared files, like the style sheet, could be >>>>> placed in those folders to avoid duplication. >>>> I wonder if it's time we pull that stuff out of classlib/ and move to >>>> the site itself... >>>> >>>> geir >>>> >>>> >>>> --------------------------------------------------------------------- >>>> Terms of use : http://incubator.apache.org/harmony/mailing.html >>>> To unsubscribe, e-mail: [EMAIL PROTECTED] >>>> For additional commands, e-mail: > [EMAIL PROTECTED] >>>> --------------------------------------------------------------------- >>>> Terms of use : http://incubator.apache.org/harmony/mailing.html >>>> To unsubscribe, e-mail: [EMAIL PROTECTED] >>>> For additional commands, e-mail: > [EMAIL PROTECTED] >>> -- >>> Alexey A. Ivanov >>> Intel Middleware Product Division >>> >>> --------------------------------------------------------------------- >>> Terms of use : http://incubator.apache.org/harmony/mailing.html >>> To unsubscribe, e-mail: [EMAIL PROTECTED] >>> For additional commands, e-mail: [EMAIL PROTECTED] >>> >>> --------------------------------------------------------------------- >>> Terms of use : http://incubator.apache.org/harmony/mailing.html >>> To unsubscribe, e-mail: [EMAIL PROTECTED] >>> For additional commands, e-mail: [EMAIL PROTECTED] >> --------------------------------------------------------------------- >> Terms of use : http://incubator.apache.org/harmony/mailing.html >> To unsubscribe, e-mail: [EMAIL PROTECTED] >> For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- > Terms of use : http://incubator.apache.org/harmony/mailing.html > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- > Terms of use : http://incubator.apache.org/harmony/mailing.html > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > > --------------------------------------------------------------------- Terms of use : http://incubator.apache.org/harmony/mailing.html To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
