Difference between revisions of "Book/HelloXenProject/Instructions for Improvement"

From Xen
Line 1: Line 1:
<!--
 
=== Prerequisites ===
 
* Install a Linux distribution which contains LibreOffice's MediaWiki export function (e.g. openSUSE, Fedora, some versions of Debian)
 
* Download the the attachment from [https://lists.xenproject.org/archives/html/xen-devel/2017-04/msg01738.html]
 
 
=== Workflow ===
 
Chose the chapter that you want to convert. You can do this in one of two ways
 
* Convert the entire document and delete the portions of the generated mark-up that are not part of the chapter you want to add
 
* Use the [https://help.libreoffice.org/4.3/Writer/Working_with_Master_Documents_and_Subdocuments Working with Master Documents and Subdocuments] to split the document into subsections
 
* Run the generated markup through [http://www.unit-conversion.info/texttools/strip-tags/ www.unit-conversion.info/texttools/strip-tag] or similar, otherwise the markup will contain unnecessary html
 
* Fix up the mark-up (see below)
 
* Add images (see below)
 
* Repeat and rinse until correct
 
 
=== Preparing the generated markup ===
 
Before you create the page, copy the chapter into your favourite editor. I observed that several things tend to go wrong
 
* Some of the bulleting does not get converted correctly: you may find special characters being created such as "&bull;" and "&bull; " (sometimes in different sizes). You may need to replace "&bull;" with "* ", etc.
 
* Tables tend to be generated poorly, but ultimately they are OK. If you want them to look pretty, remove any style="..." elements (you can use replace the style strong with "") and make sure table headers start with "!". In addition you may want to add have the table begin with <pre>{| class="prettytable"</pre>
 
* Special characters such as ticks or crosses get to converted wrongly: they will end up as "x". You will have to fix these up manually. Check out [https://wiki.xenproject.org/wiki/Category:Templates] for suggestions
 
* Images tend to get generated as
 
<pre>
 
[[Image:|top]]
 
 
==== Figure 2: ... ====
 
</pre>
 
To fix this you can use search and replace to get something like
 
<pre>[[Image:|top|Figure 2: ... ]]</pre>
 
After that, replace "[[Image:|top|" with "[[Image:XXX.png|600px|none|thumb|" - this ensures that images are the same size and you can search for XXX.png
 
* Headlines do not always come across correctly. You may need to do some editing there.
 
* At the bottom of the page, add
 
<pre>[[Category:Users]] [[Category:HelloXenProjectBook]]</pre>
 
 
=== Creating the page ===
 
If you add chapter X, then create a page called
 
* <pre>Book/HelloXenProject/X-Chapter</pre> and copy the content in
 
* Go to preview and check how it looks
 
* Fix up any remaining issues
 
* Then save
 
* Go to [[Book/HelloXenProject/0-Contents]] and add the chapter. This will look something like
 
<pre>
 
[[Book/HelloXenProject/X-Chapter|Chapter title]]<br>
 
</pre>
 
* Go to [[Book/HelloXenProject/0-Credits_and_Title#Subsequent_Contributions|Subsequent_Contributions]] and add yourself as a contributor
 
 
=== Adding images ===
 
This is the hardest part:
 
* Save the chapter that you want to add as html using File.Send.Create HTML Document : this will save all images in the directory where you save it
 
* Then open the chapter from the original and rename the saved images to (X-Y.EXT) with X being the chapter number, Y being the image or figure number and EXT being the file extension (e.g. jpg)
 
* Be careful you number the images in the right order
 
* Then find all instances of <pre>Image:XXX.png</pre> and replace with the relevant <pre>Image:HelloXenProject-X-Y.EXT.png</pre> and save
 
* Now you click on each of the links and upload X-Y.EXT.png
 
* Done
 
 
-->
 
 
 
The content of the wiki page has now been converted. But there are a number if areas which could do with improvements
 
The content of the wiki page has now been converted. But there are a number if areas which could do with improvements
  +
* Empty spaces between chapters: the conversion left many <nowiki>\n</nowiki> in documents. These mean that extra empty space is added between chapters. These can be easily deleted
 
* Code or config file snippets are currently not specifically formatted or formatted in <nowiki><nowiki>...</nowiki></nowiki> blocks. The best way to do this is to use <nowiki><syntaxhighlight lang="sh">...</syntaxhighlight></nowiki> instead
 
* Code or config file snippets are currently not specifically formatted or formatted in <nowiki><nowiki>...</nowiki></nowiki> blocks. The best way to do this is to use <nowiki><syntaxhighlight lang="sh">...</syntaxhighlight></nowiki> instead
  +
* If you come across bullets like ●, replace with proper mark-up, aka: <nowiki>* </nowiki>
  +
* If you come across unnecessary <nowiki><span ...> ...</span></nowiki> blocks, feel free to remove
  +
* Feel free to fix up badly formatted tables (see [https://www.mediawiki.org/wiki/Help:Tables#class.3D.22wikitable.22 1] and use [[Table_Style_Examples|class prettytable]])
   
 
[[Category:Users]] [[Category:HelloXenProjectBook]]
 
[[Category:Users]] [[Category:HelloXenProjectBook]]

Revision as of 10:31, 18 April 2017

The content of the wiki page has now been converted. But there are a number if areas which could do with improvements

  • Empty spaces between chapters: the conversion left many \n in documents. These mean that extra empty space is added between chapters. These can be easily deleted
  • Code or config file snippets are currently not specifically formatted or formatted in <nowiki>...</nowiki> blocks. The best way to do this is to use <syntaxhighlight lang="sh">...</syntaxhighlight> instead
  • If you come across bullets like ●, replace with proper mark-up, aka: *
  • If you come across unnecessary <span ...> ...</span> blocks, feel free to remove
  • Feel free to fix up badly formatted tables (see 1 and use class prettytable)