Re: [RFC PATCH 2/3] docs: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR

[Jan Beulich <jbeulich@xxxxxxxx>]

On 21.08.2023 18:54, Nicola Vetrini wrote:
> To be able to check for the existence of the necessary subsections in
> the documentation for MISRA C:2012 Dir 4.1, ECLAIR needs to have a source
> file that is built.
> 
> This file is generated from 'C-runtime-failures.rst' in docs/misra
> and the configuration is updated accordingly.
> 
> Signed-off-by: Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx>
> ---
>  docs/Makefile       |  7 ++++++-
>  docs/misra/Makefile | 36 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 42 insertions(+), 1 deletion(-)
>  create mode 100644 docs/misra/Makefile
> 
> diff --git a/docs/Makefile b/docs/Makefile
> index 966a104490ac..ff991a0c3ca2 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -43,7 +43,7 @@ DOC_PDF  := $(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y)) \
>  all: build
>  
>  .PHONY: build
> -build: html txt pdf man-pages figs
> +build: html txt pdf man-pages figs misra
>  
>  .PHONY: sphinx-html
>  sphinx-html:
> @@ -66,9 +66,14 @@ endif
>  .PHONY: pdf
>  pdf: $(DOC_PDF)
>  
> +.PHONY: misra
> +misra:
> +     $(MAKE) -C misra
> +
>  .PHONY: clean
>  clean: clean-man-pages
>       $(MAKE) -C figs clean
> +     $(MAKE) -C misra clean
>       rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~
>       rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core
>       rm -rf html txt pdf sphinx/html
> diff --git a/docs/misra/Makefile b/docs/misra/Makefile
> new file mode 100644
> index 000000000000..f62cd936bfcc
> --- /dev/null
> +++ b/docs/misra/Makefile
> @@ -0,0 +1,36 @@
> +XEN_ROOT=$(CURDIR)/../..
> +include $(XEN_ROOT)/Config.mk
> +-include $(XEN_ROOT)/config/Docs.mk

Why do you include this? I can't spot what you consume from there. Also,
why the leading -? _If_ you need something from there, surely you always
need it (and hence you require ./configure to have been run up front)?

> +
> +

Nit (style): No double blank lines please.

> +TARGETS := $(addprefix C-runtime-failures,.c .o)

Does the .c really need listing here?

> +all: $(TARGETS)
> +
> +define MISRA_HEADER
> +/*
> +
> +endef
> +
> +define MISRA_FOOTER
> +
> +*/
> +
> +endef
> +export MISRA_HEADER
> +export MISRA_FOOTER

Style-wise I would say: Either you put each export immediately after its
define, or you merge both into a single line.

> +C-runtime-failures.c: C-runtime-failures.rst
> +# sed is used in place of cat to prevent occurrences of '*/'
> +# in the .rst from breaking the compilation
> +     ( \
> +       echo "$${MISRA_HEADER}"; \
> +       sed -e 's|*/|*//*|' $<; \
> +       echo "$${MISRA_FOOTER}" \
> +     ) > $@

The rule of thumb is to generate into a temporary file (then you also
don't need to wrap everything in parentheses [or braces]), and then
use mv to produce the final output. This escapes anomalies with failed
or interrupted commands.

Jan