Postgresql vs. MySQL page techdocs conversion - Mailing list pgsql-advocacy

Following some last-minute improvements from Chris Browne and much editing
over the weekend, I just finished converting the page at
http://developer.postgresql.org/index.php/Why_PostgreSQL_instead_of_MySQL
to the techdocs site.  As that percolates through the approval process I
guess it should get added to the "Converting from other Databases to
PostgreSQL" section, then comes the fun of figuring out how to promote it.
Except for trivial formatting differences, the content is identical on
both right now, so if you want to check out the final result you can just
look at what's on the wiki.

One thing I tweaked at the end was clearly stating the bias of the
document as a whole and that of some of the people involved, prempting the
press or bloggers from putting their own spin in that area.  As part of
that, I made some comments characterizing how I see the priorities of the
core PostgreSQL team.  I'll certainly adjust that if anyone feels I
misrepresented your position in any way.

Here are some suggestions for anyone else who intends to follow this
writing model, creating the content on the Wiki and then converting to
techdocs later (which I highly recommend because in addition to the ease
of collaboration, it's way easier than fighting with the limitations of
techdocs the whole time):

-If you use the Wikipedia "Printable version" link and then view the
source to that, that gives you something you can cut and paste to start
with.  It won't actually generate a useful document initially, trying to
create a starter page using it will just get a complaint from techdocs
about it not being valid XHTML.  Paste that into some other editor and
expect to work on it for a bit in there to do the corrections necessary
before techdocs will accept it.

-Make sure you have Javascript enabled when using the techdocs editor, it
still works without but it's painful.  Since I always browse with
Firefox+NoScript I didn't notice this at first.  Once you've done that,
note there is a little "HTML" button on the Javascript WYSIWYG editor that
lets you drill down to fix low-level HTML problems.

-All the table of contents and similar header material leading up to the
content will need to be removed, and baggage at the end of the document
after the content has to go too.

-Each place there's a header level that's included in the table of
contents, there will be some '<div class="editsection"' stuff around it
that all has to be removed.  Basicially everything from that up til the
<Hx> tag has to go.

-All of the external URLs will have 'class="external text"' and
'rel="nofollow"' tags on them that techdocs won't accept; use an editor
with search and replace to remove all of those.

-techdocs doesn't allow H1 level headings; it seems to only support H2 and
H3 ones.  It will save you much frustration if you build the initial wiki
pages accordingly (== translates to H2, === to H3).  The items I intially
had as H1 level material I replaced with H2+underline.

-Expect to make a careful pass over the document to adjust some subtle
differences in how whitespace is handled, particularly around the header
lines.  I had to remove multiple extra lines throughout.  Note the Undo
button in the Javascript editor if you accidentally remove formatting on a
header line during such editing.

It took me about two hours to do all that, but since that included
figuring out all of the above I'd expect a pre-informed conversion would
take less than an hour to complete.  Certainly I saved way more time than
that by doing all the earlier work in Wikipedia.  Because there is a fair
amount of work involved, I consider this a one-way conversion, and I only
intend to update the techdocs version of the document moving forward.

--
* Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD