Re: [Xen-devel] "Hello Xen Project" Book.

[Lars Kurth <lars.kurth.xen@xxxxxxxxx>]

Hi Mohsen,

> On 15 Mar 2017, at 09:50, Mohsen <mohsen1365b@xxxxxxxxx> wrote:
> 
> Dear Xen Project community members,
> 
> I have written a Xen book recently (pdf attached) which is aimed at teaching 
> Xen newbies. I would like to make the book available to the Xen Project under 
> a CC-BY-SA-3.0 license. Ideally, I would like to publish the content on the 
> Xen Project wiki in an editable form, such that others can contribute and 
> build on it and it stays up-to-date. I also noticed that the Xen Wiki has the 
> https://www.mediawiki.org/wiki/Extension:Collection extension, which should 
> make it possible to create a PDF, ODF or DocBook from the pages for those who 
> want a manual rather than wiki pages.

Thank you for doing this. As far as I can tell the fact that you published the 
book under CC-BY-SA-3.0 would make it possible to move the content to the wiki. 

> I had a conversation with Lars to check whether this is possible and he 
> believes it is. He suggests that first we upload the book as pdf to the wiki 
> and as a second step, agree an information architecture and then convert the 
> book to mark-down. There are a number of conversion tools which should get us 
> there some of the way, with a bit of cleanup and beautification needed after 
> the initial import. I can make the source available in a format that makes 
> conversion to markdown easier.

We do need to find a way to convert the content into markdown format though, 
which may be quite a bit of work.

I have done this before for html pages, converting them into docman markdown. I 
have not checked whether there are online or command line tools which do that 
for mediawiki markdown. In any case, the conversion is fundamentally doable, 
although it will be somewhat tedious to do this. If anyone has more experience, 
please share and advise what the best way forward is.

The main problem that I faced when doing something similar were tables, figures 
and other more advanced formatting. Much of this may get lost or "corrupted" in 
some way and will have to be re-introduced post conversion.  

@Mohsen: as far as I recall, you used Word or LibreOffice to create the book? 
Is that correct? If so, it should be possible to save it in html, which would 
ensure that figures and so on are saved in some sensible way. We would probably 
need to find a temporary location where to store this. And we can start 
experimenting a little and maybe provide a quick guide on how to do this.

As for the information architecture, I was thinking about a structure such as 
...

https://wiki.xenproject.org/wiki/<wikibook> 
https://wiki.xenproject.org/wiki/<wikibook>/title_and_credits 
https://wiki.xenproject.org/wiki/<wikibook>/<chapter> 
https://wiki.xenproject.org/wiki/<wikibook>/<chapter>/<article> 
... a separate article for each article in the book, such as "Virtualization 
and Security". As a first step, we would probably keep the original chapter 
structure. 

This would then look something like ...
https://wiki.xenproject.org/wiki/HelloXenProject
https://wiki.xenproject.org/wiki/HelloXenProject/0/Title
https://wiki.xenproject.org/wiki/HelloXenProject/0/Credits
https://wiki.xenproject.org/wiki/HelloXenProject/0/Licence
https://wiki.xenproject.org/wiki/HelloXenProject/1-Intro
https://wiki.xenproject.org/wiki/HelloXenProject/1-Intro/History
https://wiki.xenproject.org/wiki/HelloXenProject/1-Intro/TypesOfVirtualization

We may need some other extensible numbering scheme, which would make it easy to 
create PDF's with https://www.mediawiki.org/wiki/Extension:Collection - again, 
this is something I don't have experience with.

> What do people think? Is this a good idea? Would anyone be willing to help? I 
> am not very familiar with Markdown and would need someone else to help with 
> the wikification of the book. Lars already volunteered to help.

I will definitely help, but this would be an activity, which could easily be 
distributed. So help from others would be very highly appreciated.

Best Regards
Lars


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel