harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geir Magnusson Jr <g...@pobox.com>
Subject [doc] Intrim solution ( was Re: [doc]proposal to improve and expand website)
Date Sat, 05 Aug 2006 19:19:30 GMT
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:alexey.a.ivanov@intel.com] 
> 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:alexey.a.ivanov@intel.com]
>> 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:nadezhda.morozova@intel.com]
>>> 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:alexey.a.ivanov@intel.com]
>>> 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:nadezhda.morozova@intel.com]
>>>> Sent: Wednesday, August 02, 2006 8:52 PM
>>>> To: harmony-dev@incubator.apache.org; geir@pobox.com
>>>> 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:geir@pobox.com]
>>>> 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: harmony-dev-unsubscribe@incubator.apache.org
>>>> For additional commands, e-mail:
> harmony-dev-help@incubator.apache.org
>>>> ---------------------------------------------------------------------
>>>> Terms of use : http://incubator.apache.org/harmony/mailing.html
>>>> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
>>>> For additional commands, e-mail:
> harmony-dev-help@incubator.apache.org
>>> --
>>> Alexey A. Ivanov
>>> Intel Middleware Product Division
>>>
>>> ---------------------------------------------------------------------
>>> Terms of use : http://incubator.apache.org/harmony/mailing.html
>>> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
>>> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
>>>
>>> ---------------------------------------------------------------------
>>> Terms of use : http://incubator.apache.org/harmony/mailing.html
>>> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
>>> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
>> ---------------------------------------------------------------------
>> Terms of use : http://incubator.apache.org/harmony/mailing.html
>> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
>> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
> 
> ---------------------------------------------------------------------
> Terms of use : http://incubator.apache.org/harmony/mailing.html
> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
> 
> ---------------------------------------------------------------------
> Terms of use : http://incubator.apache.org/harmony/mailing.html
> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
> 
> 
> 

---------------------------------------------------------------------
Terms of use : http://incubator.apache.org/harmony/mailing.html
To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
For additional commands, e-mail: harmony-dev-help@incubator.apache.org


Mime
View raw message