Category:HelloXenProjectBook: Difference between revisions

From Xen
Jump to navigationJump to search
 
(9 intermediate revisions by the same user not shown)
Line 2: Line 2:
This book was originally contributed by Mohsen Mostafa Jokar (see [http://markmail.org/thread/2p34bqkugkjhicwp e-mail thread that includes a PDF]) with the intention to become a book that others can contribute to and evolve over time.
This book was originally contributed by Mohsen Mostafa Jokar (see [http://markmail.org/thread/2p34bqkugkjhicwp e-mail thread that includes a PDF]) with the intention to become a book that others can contribute to and evolve over time.


== Converting chapters ==
== Improving chapters ==
We originally converted all the chapters from a PDF file to wiki markup. '''There are some areas where the formatting could be better and where you can help!''' Check out [[Book/HelloXenProject/Instructions_for_Improvement]].
=== 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 ===
== Adding new chapters ==
Over time, you may want to add new chapters. If you do so and you want to create a chapter that fits between say chapter 1 and 2, then add chapter 1a, 1b, etc.
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 "•" and "• " (sometimes in different sizes). You may need to replace "•" 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>
<pre>
⚫
Book/HelloXenProject/1-Chapter
[[Image:|top]]
⚫
Book/HelloXenProject/1a-Chapter (this would be the chapter you are adding)

Book/HelloXenProject/2-Chapter
==== Figure 2: ... ====
</pre>
</pre>
This will help ensure they stay in alphabetical order. You will also have to update [[Book/HelloXenProject/0-Contents]] and [[Book/HelloXenProject/0-Credits_and_Title#Subsequent_Contributions|Subsequent_Contributions]]
To fix this you can use search and replace to get something like
⚫
== Printing the Book ==
<pre>[[Image:|top|Figure 2: ... ]]</pre>
Go to [[Special:Book]], select '''Start Book Creator''', then '''Add This Category to your Book''', then '''Show Book'''. Remove pages that you don't want (e.g. [[Book/HelloXenProject/Instructions for Improvement‎ ]]), provide a '''title''' and '''subtitle''' (the process fails if you do not do each). You may also want to choose '''one column''' instead of two. Then go to '''Download as PDF'''. Note that there could be formatting issues, due to tables too large, etc. (see [[Book/HelloXenProject/Instructions_for_Improvement]]). I tested the preview on [http://pediapress.com/ pediapress.com] and it works up to the end of the preview.
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 ====

Latest revision as of 11:41, 18 April 2017

Credits

This book was originally contributed by Mohsen Mostafa Jokar (see e-mail thread that includes a PDF) with the intention to become a book that others can contribute to and evolve over time.

Improving chapters

We originally converted all the chapters from a PDF file to wiki markup. There are some areas where the formatting could be better and where you can help! Check out Book/HelloXenProject/Instructions_for_Improvement.

Adding new chapters

Over time, you may want to add new chapters. If you do so and you want to create a chapter that fits between say chapter 1 and 2, then add chapter 1a, 1b, etc. 

Book/HelloXenProject/1-Chapter
Book/HelloXenProject/1a-Chapter (this would be the chapter you are adding)
Book/HelloXenProject/2-Chapter

This will help ensure they stay in alphabetical order. You will also have to update Book/HelloXenProject/0-Contents and Subsequent_Contributions

Printing the Book

Go to Special:Book, select Start Book Creator, then Add This Category to your Book, then Show Book. Remove pages that you don't want (e.g. Book/HelloXenProject/Instructions for Improvement‎ ), provide a title and subtitle (the process fails if you do not do each). You may also want to choose one column instead of two. Then go to Download as PDF. Note that there could be formatting issues, due to tables too large, etc. (see Book/HelloXenProject/Instructions_for_Improvement). I tested the preview on pediapress.com and it works up to the end of the preview.

Retrieved from "https://wiki.xenproject.org/index.php?title=Category:HelloXenProjectBook&oldid=17878"