Preparing opensolaris.org Content for Migration to XWiki
The content on opensolaris.org will be migrated to XWiki on Monday, October 26, 2009. Refer to the Site Feature Mappings page for details about what will change as a result of the migration.
Automated content conversion is provided, and test conversions will happen every Monday, Wednesday, and Friday throughout August, September and October. These test conversions allow you to see your content on the XWiki beta site and see the results of changes you make on opensolaris.org.
The following list of instructions and information includes changes you can make to your content on opensolaris.org prior to the final content migration in October and steps you can or might need to make after the final content migration,
If you find problems with your content migration, please file bugs at defect.opensolaris.org in the category Development | Website and under the 'site-xwiki' component. Be sure to provide as much detail as possible, including URLs to pertinent pages and actual HTML or TML code that isn't working. Before filing a new bug, please refer to the current list of open bugs.
PRE-MIGRATION
Hidden content is not migrated
If a page has a link
to something which is hidden, and it is expected to be migrated, it
needs to either be un-hidden, or moved elsewhere and link to it updated.
Page content not migrating at all
Some invalid HTML causes the CSS.pm Perl module (used by the html2wiki converter) to fail in such a way that no content for a page is migrated.
One example: Using 'strong' as a style property. Constructs such as <font size="3" style="strong"> will cause such a failure. In this situation, the construct should be changed to two instructions: <font size="3"> <b>.
Tables
Tables are often malformed, especially in HTML, and malformed tables do not migrate well. The problem is that most browsers will render such malformed HTML reasonably well, so you need to use another tool to
verify it, for example, a w3 validator.
Make sure tables are correctly formed. Additionally, do not
use XWiki syntax 2.0 characters as textual delimiters within a table.
RE: pipe character ("|")
You can use this in a table if you escape it. The XWiki escape character is the tilde (""). So using ~| should work.
RE: column span and row span
XWiki doesn't recognize the HTML concepts of column span and row span. So the 'colspan' and 'rowspan' options will not work.
RE: bulleted lists
There is a way to do this in an XWiki table, but it has to be done using XWiki markup syntax. There is no way to change the HTML to migrate correctly. If you want to use this construct, use the following within the table cell:
RE: empty table cells
Empty HTML table cells (<td></td>
) contain nothing to translate so they don't migrate well and tend to mess up table formatting. An easy solution is to insert a space in that cell. That tells the <i>html2wiki</i> tool that the cell is not empty and an empty cell migrates with formatting intact:
Broken links
Make sure links are correct, including those to attachments. Also, re-target
relative links (i.e. links containing ../) to use the absolute path. They don't migrate well
because the page hierarchy is different in XWiki.
Fixing links also extends to links to hidden pages, or files attached to hidden
pages, on the old opensolaris.org web site.
Links within <code> tags
For example:
will be visible in the migrated page as;
i.e. the XWiki link syntax is reproduced verbatim in the page content
because the migration code has (correctly) produced this markup;
Place the <code> tags inside the anchor tag, e.g.
or remove the <code> tags altogether.
The use of <code> tags within <pre> tags
The use of <code> tags within <pre> tags doesn't migrate to XWiki.
The content migration script deals with this scenario automatically as of Oct 2, 2009. If you have pages that use <code> tags within <pre> tags, you may also simply remove the <code> tags. The text should migrate over in a gray box as designated by the <pre> tags.
Link texts that are URLs do not respect the link target
The migration process does not alter link text, but should remap link targets to their new locations. However, in XWiki, link text which is a fully qualified URL is used as the link target, overriding the link target in the original document. This means that if your link text is a site URL (i.e. under http://opensolaris.org/os/), the text and link will both be broken after migration.
As a workaround, simply change the link text not to be a URL. For example, if you have in TML
change it to
If you have in HTML
change it to
Check your image tags: <img .... />
There are instances of malformed image tags that do not migrate properly because they contain an incorrect character:
The left caret before the closing "/>" is incorrect.
The correct syntax for the <img> tag is as follows:
Copy data from pages that won't migrate
A set of pages that were programmatically provided by the original portal application do not migrate to XWiki. The list of such pages is in the "Special Features" table on the <site features page>:
- articles
- blogs
- news
- announcements
- events
- discussions
If you have data on these pages, you can copy it to new pages within your collective now, and the new pages will migrate.
If the data is automatically generated (blogs, announcements), you'll need to wait until after the migration to set up RSS feeds on the new pages.
If the data is small, e.g., the pointer to the Jive forum if your collective has one, it can also be put somewhere on an existing page.
If one of the programmatically-generated pages has child pages, do the following:
- Create a new parent page for the top-level page and copy content to it.
- Reassign the child pages to the new parent page via the drop down menu at the bottom of their content edit boxes in edit mode.
Note that you can also wait until after the transition date to create new pages on the new site.
POST-MIGRATION
Workaround for XWiki editor bug
Sometimes on XWiki, when switching to the XWiki editor from the WYSIWYG editor, you may see a blank page and/or this error message in red: "Exception while parsing HTML". Use the following workaround: Check the URL in the browser window. Make sure the text following the ? is only "editor=wiki". If that is the text already there, re-type some or all of the text. The XWiki markup should then be displayed.
This is a bug in XWiki, and we're not sure when it will be fixed.
Empty File pages
If you have a Files page and it looks empty when it shouldn't be, do the following; Move your cursor over 'Show' in the XWiki nav bar at the top of the page. The pull-down menu will include an item called 'Attachments'. Click on that. And the attachments on the Files page will be listed.
Attachments with an underscore in the file name
XWiki removes '_' characters from file names. The migration process should take account of this, but may fail to modify all attachment links.
Double-check links to attached files and correct where necessary.
Page anchors
XWiki implements page anchors differently than TML or HTML, so a straight migration isn't possible.
The XWiki TableOfContents macro can be useful if all that is needed is page anchors to section titles, otherwise the anchors can be manually added post migration, for example if a page has a section heading.
Installing
which when rendered to HTML by XWiki has an id tag of 'HInstalling', and so may be linked to thus;
Missing attachments
Some attachments may fail to get uploaded as part of the automated content migration.
Manually attach the missing file to the appropriate XWiki page. Note
that in some cases, links to the attachment may also be broken, which will also require manual intervention.
For example, images which links to a larger version of themselves;
and the larger image is not attached to the page. To remedy, attach the file and change the link to
Escaped Double Dash
Double dashes ("--") are XWiki syntax for strike out so the migration process escapes these with a tilde (""). Unfortunately, the escape character is treated literally inside 'verbatim' blocks (<pre> </pre> in html and in XWiki) which might cause unwanted text on XWiki pages after the migration.
If you use double dashes, check your pages and if needed, remove the extraneous tilde ("") in cases where double dashes are used inside verbatim blocks.
Formatting within <pre> tags
tags translate to XWiki as verbatim blocks. Formatting is translated but won't result formatting within the <pre> blocks. For example, if text is bold within a <pre> block, that will translate as:
showing up within the grey box.
After the transition, <pre> blocks will need to be checked and any formatting fixed on the XWiki page.
Embedded media
Original information:
Media (flash, video etc) which were originally presented with an <OBJECT> tag will not migrate.
Upload the necessary files and add a link to what was the embedded media;
This doesn't embed the media, but at least it is available to the user, assuming browser support.
UPDATE:
The use of embedded media will be supported, but the website team will probably need to do manual work on XWiki pages after the migration as opposed to being able to change things on opensolaris.org before the migration. This work will probably include use of a custom macro.
More detail will be communicated when we have finalized how this will be handled, but be assured that this will be addressed post-migration and that existing videos on opensolaris.org will be preserved.