m (DocsProject/Wiki2XML moved to Converting wiki to DocBook XML: Page renaming party) |
(Page renaming party) |
||
Line 141: | Line 141: | ||
It's best not to hyperlink other text because in some formats people may have a hard time finding the actual URL. Edit judiciously. | It's best not to hyperlink other text because in some formats people may have a hard time finding the actual URL. Edit judiciously. | ||
[[Category:Docs_Project_process]] |
Revision as of 02:48, 22 February 2009
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:
- Open the file in a full-featured text editor
- Ensure the XML file has the proper header, with proper chapters or sections
- Change to 'chapter' type
- Remove extraneous XML stylesheet call
- Change XML file type within the file
- book => 0
- article => chapter
- articleinfo => 0
- 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:
- Search for each instance of 'emphasis' and replace it with the proper DocBook contextual markup
- Search for each instance of 'code' and 'programlisting' and replace it with the proper DocBook contextual markup
- Search and replace empty literallayout containers
- Convert inlinemediaobject to proper admonition
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.