clean-up for DUG XML

[Karsten Wade]

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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20070225/9c134e86/attachment.bin