From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andrew Cooper Subject: Re: [RFC v2 for-4.6 0/2] In-tree feature documentation Date: Fri, 28 Aug 2015 20:06:24 +0100 Message-ID: <55E0B130.4050708@citrix.com> References: <1440499228-961-1-git-send-email-andrew.cooper3@citrix.com> <21983.9235.766205.452378@mariner.uk.xensource.com> <8E7215F6-093E-4850-BD5A-498877C047E3@gmail.com> <55E09CF6.8060302@citrix.com> <45B017AB-9E69-4DFC-A951-83A47B3D9589@gmail.com> <55E0A5E5.4050004@citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: Lars Kurth , Lars Kurth Cc: Juergen Gross , Wei Liu , Ian Campbell , "Tim (Xen.org)" , Xen-devel , Jim Fehlig , Jan Beulich , Ian Jackson List-Id: xen-devel@lists.xenproject.org On 28/08/15 19:52, Lars Kurth wrote: > > On 28/08/2015 19:18, "Andrew Cooper" 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