I just committed some changes to the desktop-user-guide XML, removing
some cruft from the conversion. The diff should be sane when viewed
through fedora-docs-commits because I did this:
1. ran xmlformat on the files
2. committed those formatted files
3. made changes
4. ran xmlformat again
5. committed those changes
We may want to turn on the xmlformat for all files now, so we aren't
having to think about this. IIRC, we have a hook to allow us to have
xmlformat run on files as they are checked in, before the commit lands
in CVS.
I have a small list of other changes that need to be worked on. There
are two sections -- changes that have to be made to make it build and
work right, and changes that need to be made if we are doing a complete
conversion.
With the release notes, we sometimes opt not to change the XML to the
correct tags, because XML is an interim format. With a full conversion,
we want to convert e.g. <emphasis role="bold"> into one of the tags that
is supposed to correspond to:
http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms
For example, if the Wiki usage was '''Firefox''', the output to
XML
becomes <emphasis role="bold">Firefox</emphasis>, and it needs to
be
changed manually to <application>Firefox</application>.
In Emacs, I would put my cursor somewhere on the <emphasis...> tag, then
do 'C-c ='. In the status bar at the bottom appears "Change emphasis
to"; type "app[tab]", it fills out "application", and pressing
[Enter]
changes the tag to <application>.
Here is the list of changes that I captured; there are surely more:
n. Convert all <article> => <chapter>
n. Give IDs to <sections>
n. Clean up <ulink> URIs => <xref>
n. Remove <anchor> (redundant)
- note that the ID is often present because it is linked to; use
where needed in the nearest <section> etc., then search for the
anchor text in the XML to find everywhere that links to this
information, then fix those (ulink => xref, etc.)
n. Convert admonitions (search for <table>, /wikidata/kindofblue/img/)
n. Remove <articleinfo> and </articleinfo> from <chapter>s, including
the bogus <title>Docs/DesktopUserGuide/</title>
n. Remove footer navigation hack (last table in a page)
n. Remove CategoryDocumentation <para> at the end
n. Look for how <code> is used; it gets a line break and sometimes
<para> around it that is not appropriate.
n. <listitem> that does not surround <para> should be adjusted
<listitem>foo</listitem> =>
<listitem><para>foo</para></listitem>
For full conversion to XML:
Note: Once you have done this conversion, and bug fixes and updates
to the Wiki and/or the XML need to be manually ported to the other
format. In other words, once you distance your XML from its Wiki
roots, you cannot easily insert new Wiki content or go backward.
n. <emphasis role='bold'></emphasis> => <application> or
<keycombo>
n. <emphasis></emphasis> => <guimenu>, <firstterm>, etc.
n. <code></code> => <code>, <computeroutput>,
<userinput>, <screen>,
etc.
n. Create <keycombo> (search for [)
n. <citetitle> for FIG
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. |
fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\