Re: [Xen-devel] [PATCH for-4.6 1/2] docs: Template for feature documents

[Juergen Gross <xen@xxxxxxxxx>]

On 08/25/2015 12:52 AM, Andrew Cooper wrote:
> On 24/08/2015 20:27, Juergen Gross wrote:
> > On 08/24/2015 07:37 PM, Andrew Cooper wrote:
> > > Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
> > > ---
> > >    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
> In the longterm, I would expect that information to be visible via `git
> log`.
>
> Having said that, it probably is useful to have a summary of history
> available in the written document.
>
> How about a #History section at the bottom?  That can at least include
> "document written" as a starting point and subsequent major changes in
> short form.
Sure, I'm fine with this.

Juergen


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