(updating to match current wiki formatting realities and how it converts using mw-render) |
(bit of re-org cruft) |
||
Line 64: | Line 64: | ||
<pre> | <pre> | ||
Was ''two-ticks'' (<code>''two-ticks''</code>) in wiki | Was ''two-ticks'' (<code>''two-ticks''</code>) in wiki | ||
\=> <emphasis> => <application>, <guibutton>, <keycap>, <keycode>, <keycombo>, | \=> <emphasis> => <application>, <guibutton>, <keycap>, <keycode>, <keycombo>, |
Revision as of 18:47, 9 October 2008
Wiki2XML
Useful References
http://fedoraproject.org/wiki/DocsProject/WorkFlow#WikitoDocBookXML
Converting from Wiki to XML in MoinMoin
Before Conversion
The document needs to follow these lengthy but accurate guidelines:
- http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki
- http://fedoraproject.org/wiki/WikiEditing#Linking
- http://fedoraproject.org/wiki/WikiEditing#Lists
- http://fedoraproject.org/wiki/WikiEditing#Tables
- http://fedoraproject.org/wiki/WikiEditing#Notes,_Tips,_and_Other_Admonitions
- http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms
- http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
- http://fedoraproject.org/wiki/DocsProject/StyleGuide
Converting to XML
1. Page must first follow guidelines in [#Before_Conversion] 1. Go to the page you want to convert 1. In the right-side navigation choose More Actions: > Render as Docbook 1. Note the format of the URL; this format can be used with wget, e.g.: wget http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Introduction?action=format&mimetype=xml/docbook
- That is the basis of a script for getting all the pages
1. Save the rendered page in the proper place as a file with the same name as the wiki page: /path/to/guide-name/devel/en_US/Introduction.xml
1. The XML files need a standard book structure, including a Makefile, a source-language directory such as en_US where the XML files live, and the special file en_US/rpm-info.xml
. The entities file en_US/doc-entities.xml
is optional; if you don't know what it does, you don't need it.
- These all live in
module-name/devel/
1. Once an XML file, the file itself needs numerous changes to make it do the following:
- Match actual DocBook XML 4.4 requirements
- Build using Fedora Docs toolchain
- Fit into an <article> or <book> structure
1. Loop through the document file by file or with any kind of script covered in DocsProject/Tools/Wiki2XML . Follow the clean-up techniques described below in [#Clean-up_DocBook_XML:Clean-up DocBook XML] .
Clean-up DocBook XML
To make sure your XML is formatted according to DocsProject standards, use:
for i in *.xml; do xmlformat -f <location of docs-common-folder>/bin/xmlformat-fdp.conf $i > tmpfile && mv tmpfile $i; done
Processing DocBook Pages
Follow this process guideline with each XML file:
1. Open the file in a full-featured text editor
1. Ensure the XML file has the proper header, with proper chapters or sections
1. Search through the file for each of the markup output types covered in [#Wiki_markup_output_to_XML,_mapped_to_DocBook_XML Wiki markup output to XML, mapped to DocBook XML] ; that is, do the following:
1. Search for each instance of <emphasis> and replace it with the proper DocBook contextual markup
1. Search for each instance of <emphasis role='strong'> and replace it with the proper DocBook contextual markup
1. Search for each instance of and replace it with the proper DocBook contextual markup
Wiki markup output to XML, mapped to DocBook XML
Was ''two-ticks'' (<code>''two-ticks''</code>) in wiki
\=> <emphasis> => <application>, <guibutton>, <keycap>, <keycode>, <keycombo>,
<firstterm>, <menuchoice>, <guimenu>, <guisubmenu>,
<guimenuitem>, <guilabel>, <guibutton>, <guiicon>, <glossterm>
Was '''three-ticks''' (<code>'''three-ticks'''</code>) in Wiki
\=> <emphasis> => <application>
Was <code></code> in wiki
\=> <programlisting> => <command>, <filename>, <classname>
<programlisting format="linespecific"> => <command>, <filename>, <classname>
Was <pre /> block in wiki
\=> <programlisting> block
Was <something_replaceable> in wiki
\=> <something_replaceable> => <replaceable>something</replaceable>
guibutton, key*
Remove the "[] " and "+", these are handled by the XSL/CSS.
Example Usage
The following examples show very short <para> (paragraph) elements as examples.
To indicate a selection from a graphical menu in DocBook XML, retag like this:
<para>From the main menu, select <menuchoice>
<guimenu>System</guimenu>
<guisubmenu>Administration</guisubmenu>
<guimenuitem>Display</guimenuitem>
</menuchoice>.</para>
You do not need to put the > symbol in, that is handled by the XSL or CSS.
key*
To indicate a key combination in DocBook XML, retag like this:
<para>To reboot, hit <keycombo>
<keycap>Ctrl</keycap>
<keycap>Alt</keycap>
<keycap>Delete</keycap>
</keycombo>.</para>
screen
To show multiline commands, break out a single important command line, or show a section of a configuration file or output in DocBook XML, retag like this:
<para>Run the following commands:</para>
<screen><![CDATA[rpm -qa 'kernel' > /tmp/kernels1.txt
]rpm -qa 'kernel*' > /tmp/kernels2.txt
diff -u /tmp/kernels?.txt ></screen>
Notice that the <![CDATA[ ... ] >
content allows you type anything verbatim between the markers. This means you don't have to change special characters like < > &
into their XML character entity equivalents. This simplifies the process somewhat, but you can't use any XML tags between the <![CDATA[ ... ] >
markers, of course. Avoid putting in extra space such as line breaks.
ulink (URLs)
To make a link to a URL:
Visit my page at <ulink url="http://example.com/mypage.html" />.
It's best not to hyperlink other text because in some formats people may have a hard time finding the actual URL. Edit judiciously.