You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by "Morozova, Nadezhda" <na...@intel.com> on 2006/08/23 14:04:06 UTC
RE: [doc] Intrim solution
Geir,
Thanks for your effort in migrating docs to a more stable state inside
the website. I've been examining your solution, and here are my
comments:
1) Nice and quick way to import new docs into the website without
converting them into XML for internal processing. Never thought of it :)
2) Source of resulting file is not optimal because:
- Doctype declarations, metatags and head content are copied
from the imported document into the middle of the
resulting HTML code
- <body> of the page HTML has a nested <body> of imported
document
3) Stylesheet referenced in resulting document is applied to the whole
page, including the left navigation menu.
This last point can be workarounded easily by making minor changes in
the referenced stylesheet (I could do this and send you a patch).
However, I don't like this solution and would rather vote for a common
CSS for the whole website.
A major obstacle to having one CSS for the Harmony website is that
there's no such CSS at the moment! L&F of page content is set in the
.vsl file that Anakia uses.
I suggest that we move away from this by reducing .vsl to processing
only and move out all presentation tags into a Harmony-wide CSS. This
would help us:
- reduce file size (and consequently i-net traffic) for Harmony website:
you load only one file instead of loading the same styles for each page
- reduce effort of integrating more docs into the website: each doc
references the same stylesheet and is displayed in the same way
- simplify doc structure: no nested <body> and <meta> elements; numerous
<font> tags replaced with a hierarchical HTML tag and class structure
- clarify website functioning mechanism: distinguish processing macros
and presentation of resulting output
If the community agrees, I could try and implement this solution.
That would take a relatively significant amount of time as it would
include:
1) Editing .vsl to remove presentation info and improving structure of
resulting HTML code
2) Creating a .css and testing it to fit existing files and new ones
3) Going through all current XML files making up the website to make
adjustments in <body> content per new CSS requirements (can be done by a
script or auto-replacement but still)
All in all, this seems like a serious effort. Help most welcomed!
Best regards,
Nadya Morozova,
-----Original Message-----
From: Geir Magnusson Jr [mailto:geir@pobox.com]
Sent: Saturday, August 05, 2006 11:20 PM
To: harmony-dev@incubator.apache.org
Subject: [doc] Intrim solution ( was Re: [doc]proposal to improve and
expand website)
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
---------------------------------------------------------------------
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
Re: [doc] Intrim solution
Posted by "Geir Magnusson Jr." <ge...@pobox.com>.
Morozova, Nadezhda wrote:
> Geir,
>
> Thanks for your effort in migrating docs to a more stable state inside
> the website. I've been examining your solution, and here are my
> comments:
>
> 1) Nice and quick way to import new docs into the website without
> converting them into XML for internal processing. Never thought of it :)
>
> 2) Source of resulting file is not optimal because:
> - Doctype declarations, metatags and head content are copied
> from the imported document into the middle of the
> resulting HTML code
> - <body> of the page HTML has a nested <body> of imported
> document
Yep, but has there been any reported bad effects?
> 3) Stylesheet referenced in resulting document is applied to the whole
> page, including the left navigation menu.
Yep.
>
> This last point can be workarounded easily by making minor changes in
> the referenced stylesheet (I could do this and send you a patch).
> However, I don't like this solution and would rather vote for a common
> CSS for the whole website.
Yep!
>
> A major obstacle to having one CSS for the Harmony website is that
> there's no such CSS at the moment! L&F of page content is set in the
> .vsl file that Anakia uses.
> I suggest that we move away from this by reducing .vsl to processing
> only and move out all presentation tags into a Harmony-wide CSS. This
> would help us:
> - reduce file size (and consequently i-net traffic) for Harmony website:
> you load only one file instead of loading the same styles for each page
> - reduce effort of integrating more docs into the website: each doc
> references the same stylesheet and is displayed in the same way
> - simplify doc structure: no nested <body> and <meta> elements; numerous
> <font> tags replaced with a hierarchical HTML tag and class structure
> - clarify website functioning mechanism: distinguish processing macros
> and presentation of resulting output
>
> If the community agrees, I could try and implement this solution.
> That would take a relatively significant amount of time as it would
> include:
> 1) Editing .vsl to remove presentation info and improving structure of
> resulting HTML code
> 2) Creating a .css and testing it to fit existing files and new ones
> 3) Going through all current XML files making up the website to make
> adjustments in <body> content per new CSS requirements (can be done by a
> script or auto-replacement but still)
The last one I don't understand. Rarely is there any L&F info in the
XML - that's the point of this approach - that the document content -
the XML - is independent of the rendering.
>
> All in all, this seems like a serious effort. Help most welcomed!
>
Sounds good - I wouldn't try to bite it all off at once - I'd start with
seeing what it takes to get a basic CSS applied in the .vsl and start
looking at it from there.
Lets try to do this incrementally, so if we decide not to do it, the
investment is as small as possible.
(IOW, go for it!)
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