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

[Wei Liu <wei.liu2@xxxxxxxxxx>]

On Mon, Aug 24, 2015 at 11:52:34PM +0100, 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

% Revision X

> >> +
> >> +\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.

Or use a table for revision history at the beginning? I personally think
using a table is clearer than several paragraphs.

Don't want to bikeshed how it should look like. We can always change the
template if necessary.

Wei.

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

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