Re: [Xen-devel] [PATCH v9 14/15] docs: libxc migration stream specification

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 15/04/15 12:46, Ian Campbell wrote:
> On Fri, 2015-04-10 at 18:16 +0100, Andrew Cooper wrote:
>> Add the specification for a new migration stream format.  The document
>> includes all the details but to summarize:
>>
>> The existing (legacy) format is dependant on the word size of the
>> toolstack.  This prevents domains from migrating from hosts running
>> 32-bit toolstacks to hosts running 64-bit toolstacks (and vice-versa).
>>
>> The legacy format lacks any version information making it difficult to
>> extend in compatible way.
>>
>> The new format has a header (the image header) with version information,
>> a domain header with basic information of the domain and a stream of
>> records for the image data.
>>
>> The format will be used for future domain types (such as on ARM).
>>
>> The specification is pandoc format (an extended markdown format) and the
>> documentation build system is extended to support pandoc format documents.
>>
>> Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
> I've read this before so I don't think I'll read it again, so I'll take
> it on trust that it represents the code and that you've run a spell
> checker over it (;-)).
>
> Some things relating to: 
>> +pdf/%.pdf txt/%.txt html/%.html: %.pandoc
>> +       $(INSTALL_DIR) $(@D)
>> +       pandoc --number-sections --toc --standalone $< --output $@
> docs/Makefile seems to handle pandc not being available via pdf targets
> already, although it's not clear if that will affect this rule, but it
> certainly doesn't look to do anything for txt or html sections.

The rules are somewhat special.  This rule doesn't collide with any
existing ones.  It covers building stuff from .pandoc, whereas the other
rule covers building .pdf from .markdown

>
> IOW what happens if pandoc isn't installed?

Good question - I will need to fix that.

>
> The existing code also seems to incorrectly not use the $(PANDOC)
> variable which configure helpfully provides.

Oops - that was me in 869d9ca2 where I also introduced the ./configure
side of things.

>
> Is pandoc a superset of markdown? Would it be worth feeding .markdown
> docs to it in preference?

Yes, and that is a longterm plan I have.  IMO, pandoc makes far nicer
documents than markdown.

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