Re: [RFC v2 for-4.6 0/2] In-tree feature documentation

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 28/08/15 19:52, Lars Kurth wrote:
>
> On 28/08/2015 19:18, "Andrew Cooper" <andrew.cooper3@citrix.com> wrote:
>
>> On 28/08/15 18:51, Lars Kurth wrote:
>>> We may need some extra tags/headings, if we were to include things such
>>> as supported limits for memory, vCPUs, ... I remember, you raised the
>>> point that some of the theoretical limits are not always tested.
>> Absolutely.  Not everyone has a server with 123TB of RAM to hand, or
>> even 16TB which is default current limit.  (For this issue, testing from
>> both Citrix and Oracle indicates a bug when more than 5TB of RAM is used.)
>>
>> Therefore, a distinction between the theoretical limit and
>> currently-tested limit is very useful.  I expect the the commercial
>> stakeholders will be in a position to routinely test at far above the
>> limit available to direct consumers of the Xen project.
>>
>> For the in-tree statement of limits, I have not put much though to how
>> to represent them yet, but I am not sure that the feature template
>> proposed in #1 will be a great fit.  I suspect we will want something a
>> little different.
> Maybe a master document for system stuff, with a slightly different format.

Possibly.  Nothing prevents us from having different types of
documentation with different expected layouts.

We can see what feels best when we get to it.

>
> I may have missed this: what kind of mark-up is being used?
> http://pandoc.org/ seems to support a few: may need to add a README with a
> couple of pointers.

http://pandoc.org/demo/example9/pandocs-markdown.html

Pandoc extends plain markdown in a number of ways commonly found
elsewhere, including the ability to insert raw LaTeX if needs be.

The eagle-eyed might have spotted a cunningly positioned \clearpage
which aids the clarity of the generated pdf file.

>
> And I am assuming some sort of index is produced when these docs are
> built: correct?

For the HTML ones, yes.  One example is:

http://xenbits.xen.org/docs/unstable/specs/libxc-migration-stream.html

Which is currently generated from a pandoc document in tree.


By default in-tree, all pandoc stuff will be rendered to pdf and html. 
I am not aware whether the pdf versions are served from xenbits, but the
html ones certainly are.

~Andrew