From mboxrd@z Thu Jan 1 00:00:00 1970 From: Juergen Gross Subject: Re: [PATCH for-4.6 1/2] docs: Template for feature documents Date: Mon, 24 Aug 2015 21:27:30 +0200 Message-ID: <55DB7022.8090306@pfupf.net> References: <1440437822-29490-1-git-send-email-andrew.cooper3@citrix.com> <1440437822-29490-2-git-send-email-andrew.cooper3@citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; Format="flowed" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1440437822-29490-2-git-send-email-andrew.cooper3@citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: Andrew Cooper , Xen-devel List-Id: xen-devel@lists.xenproject.org On 08/24/2015 07:37 PM, Andrew Cooper wrote: > Signed-off-by: Andrew Cooper > --- > docs/Makefile | 2 +- > docs/features/template.pandoc | 55 +++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 56 insertions(+), 1 deletion(-) > create mode 100644 docs/features/template.pandoc > > diff --git a/docs/Makefile b/docs/Makefile > index 272292c..5d620e5 100644 > --- a/docs/Makefile > +++ b/docs/Makefile > @@ -16,7 +16,7 @@ MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print)) > > TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print)) > > -PANDOCSRC-y := $(sort $(shell find specs -name '*.pandoc' -print)) > +PANDOCSRC-y := $(sort $(shell find features/ misc/ specs/ -name '*.pandoc' -print)) > > # Documentation targets > DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) > diff --git a/docs/features/template.pandoc b/docs/features/template.pandoc > new file mode 100644 > index 0000000..d883b82 > --- /dev/null > +++ b/docs/features/template.pandoc > @@ -0,0 +1,55 @@ > +% Template for feature documents > + > +\clearpage > + > +This is a suggested template for formatting of a Xen feature document in tree. > + > +The purpose of this document is to provide a concrete support statement for the > +feature (indicating its security status), as well as brief user and technical > +documentation. > + > +# Basics > + > +A table with an overview of the support status and applicability. > + > +---------------- ---------------------------------------------------- > + Status: e.g. **Supported**/**Tech Preview**/**Experimental** > + > +Architecture(s): e.g. x86, arm > + > + Component(s): e.g. Hypervisor, toolstack, guest > + > + Hardware: _where applicable_ > +---------------- ---------------------------------------------------- What about adding some information when the feature was introduced or some other historical stuff? Something like: Experimental in Xen 4.1 Supported in Xen 4.3 xl syntax changed in Xen 4.4 Juergen > + > +# Overview > + > +A short description the feature, similar to an abstract for a > +paper/presentation. > + > +# User information > + > +Information for a user attempting to use the feature. Should include how to > +enable the feature (is it enabled by default? If not, how to turn it on?), and > +how to interact with the feature (typically via `xl`). > + > +# Limitations > + > +Information concerning incompatibilities with other features or hardware > +combinations. > + > +# Technical information > + > +Information for a developer or power user. Should include where to look > +in-tree for detailed documents and code. > + > +# Areas for improvement > + > +List of enhancements which could be undertaken, e.g. to improve the feature > +itself, or improve interaction with other features. > + > +# Known issues > + > +List of known issues or bugs. For tech preview or experimental features, this > +section must contain the list of items needing fixing for its status to be > +upgraded. >