TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Re: Does Anyone here use Confluence for Documentation?
Subject:Re: Does Anyone here use Confluence for Documentation? From:Lou Quillio <public -at- quillio -dot- com> To:"A.H." <isaac840 -at- yahoo -dot- com> Date:Tue, 27 Jun 2006 14:40:03 -0400
A.H. wrote:
> We now have to convert our CSS styles into
> confluence styles. Normally you would do this with
> user-created macros, but they dont work within the
> html macro.
Need some clarification on what you'd like to achieve. A Wiki page
is already an HTML page, so you can't fully embed a second HTML page
within it.
You could possibly embed the contents of an HTML page's <body>
element within a Wiki page, wrapped in the provided Wiki macro.
You'd end-up with a "Mini Me" of the HTML page, contained within a
Wiki's page's chrome and controls. You'd lose anything in the
HTML's <head> element, including any <script> elements -- but those
can be moved within the <body> element
If that's acceptable, I'd do it this way:
1. Copy-paste the HTML page's <body> element and its
contents into a Wiki page, using the Wiki's text-
mode editor.
2. Wrap the HTML block in the Wiki's {html} macro tags.
3. Change the opening and closing <body> elements to a
<div> with a unique ID, e.g. <div id="body_embed"></div>
4. Make a duplicate of the stylesheet you use for the
HTML pages, and rename it.
5. Edit the duplicate stylesheet, pre-pending each
selector with the ID you chose in Step 3, thereby
making them _contextual_ selectors. For example, if
you have a selector like this
p {
margin: .5em 0 1em;
font: normal 12pt/1.3 Verdana, Geneva, sans;
}
Change it to this:
#body_embed p {
margin: .5em 0 1em;
font: normal 12pt/1.3 Verdana, Geneva, sans;
}
6. Edit your Wiki's theme, adding a link to your special-
purpose stylesheet after any other linked stylesheets.
Now we have a set of styles that'll only be applied to elements
contained within the ID "body_embed" -- which will only occur when
you're using this embedding technique. They'll be ignored otherwise.
We've linked this stylesheet last so that it's dominant in the cascade.
Three more things:
7. Links to any media files (<img>, <object>, etc., plus
any linked background images in the CSS) will need to
be adjusted, or duplicate files placed at the same
relative path vis-à-vis the Wiki pages.
8. Some of the CSS selectors may not be germane to the
HTML page when embedded this way (it's not a page any
more, rather an HTML blob, rendered within another
page's context). Depending on how tight your HTML
and CSS are, some CSS clean-up may be necessary. I'd
do that by commenting-out any CSS selectors that don't
make sense in the Wiki context, rather than deleting
them.
9. Create a Wiki page that documents your procedure, and
add comments to the re-worked stylesheet explaining
what it's all about and where it's progenitor can be
found.
Now, this may not be what you want to achieve, or should be trying
to achieve.
If the idea is to place the HTML under the Wiki's version control,
it may make more sense to create a Wiki page corresponding to each
HTML page, and include a code block with the HTML source, a link to
the HTML page itself, and perhaps a screenshot.
This latter method lends itself to creating additional Wiki pages
that document your HTML markup standards and conventions, the
document tree structure, Web server configuration, and anything else
a maintainer would need to know.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
