[cairo] [RFC] [PATCH cairo] doc: Drop tmpl support

[Uli Schlachter]

Hi,

Well... thanks for taking a look, but sorry, I have never interacted
with gtkdoc in any way. A quick Google search lead me to

https://github.com/felixonmars/archlinux-community/commit/dff49ea7a08b6a3c8b21d6c4771051f1431fccf8

and

https://gitlab.gnome.org/GNOME/gtk-doc/commit/46df4354abed5724697fd5e39630c5bbc6637cc4

neither of which is really helpful. The best information is in

https://gitlab.gnome.org/GNOME/gtk-doc/commit/46df4354abed5724697fd5e39630c5bbc6637cc4#2cab36722f4ba2911d461a424bcb995df066860f_264_264

which claims... I don't know, that nothing should actually break?

You write below that this "probably regresses" something. Is there any
indiciation of this? The link above says "If you have never changed file
in tmpl by hand, please remove the directory", which I interpret as
"nothing should actually change, right?

Cheers & sorry,
Uli

On 24.08.2018 19:17, Bryce Harrington wrote:
> Fix distcheck by dropping use of the now-obsolete gtkdoc-mktmpl.
> 
> In preparation for the upcoming 1.16 release, I've made a few changes to
> get distcheck to pass.  I also updated it to run on Ubuntu 18.04, but
> found that on newer distros distcheck won't run due to missing
> gtkdoc-mktmpl, which has been deprecated upstream for some time.  The
> patch below disables everything that references it, and enables
> distcheck to finish successfully.
> 
> Unfortunately, this probably regresses portions of our document
> generation, and thus will need some reimplementation work.  Anyone got
> time to investigate a better solution for this?
> 
> ---
>  build/Makefile.am.gtk-doc | 25 ++++---------------------
>  doc/public/Makefile.am    |  3 ---
>  2 files changed, 4 insertions(+), 24 deletions(-)
> 
> diff --git a/build/Makefile.am.gtk-doc b/build/Makefile.am.gtk-doc
> index d3fb686a7..56aa4957d 100644
> --- a/build/Makefile.am.gtk-doc
> +++ b/build/Makefile.am.gtk-doc
> @@ -42,8 +42,8 @@ EXTRA_DIST += 				\
>  	$(DOC_MODULE)-sections.txt	\
>  	$(DOC_MODULE)-overrides.txt
>  
> -DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
> -	   $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp
> +DOC_STAMPS=scan-build.stamp sgml-build.stamp html-build.stamp \
> +	   $(srcdir)/sgml.stamp $(srcdir)/html.stamp
>  
>  SCANOBJ_FILES = 		 \
>  	$(DOC_MODULE).args 	 \
> @@ -88,26 +88,11 @@ scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) $(EXTRA_HFILES)
>  $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
>  	@true
>  
> -#### templates ####
> -
> -tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
> -	@echo 'gtk-doc: Rebuilding template files'
> -	@-chmod -R u+w $(srcdir)

Urgh. I'm glad this has to go. O.o

> -	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
> -	touch tmpl-build.stamp
> -
> -tmpl.stamp: tmpl-build.stamp
> -	@true
> -
> -tmpl/*.sgml:
> -	@true
> -
> -
>  #### xml ####
>  
>  # gtkdoc-mkdb is broken and requires a --root-dir=$(srcdir) option
>  # The _srcdir diversion is fragile but works for make check; make distcheck
> -sgml-build.stamp: tmpl.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files)
> +sgml-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(expand_content_files)
>  	@echo 'gtk-doc: Building XML'
>  	@-chmod -R u+w $(srcdir)
>  	_srcdir="`pwd`/$(DOC_SOURCE_DIR)"; \
> @@ -127,7 +112,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
>  	cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
>  	test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
>  	@echo 'gtk-doc: Fixing cross-references'
> -	cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
> +	cd $(srcdir) && gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
>  	touch html-build.stamp
>  
>  ##############
> @@ -176,10 +161,8 @@ dist-check-gtkdoc:
>  endif
>  
>  dist-hook: dist-check-gtkdoc dist-hook-local
> -	mkdir $(distdir)/tmpl
>  	mkdir $(distdir)/xml
>  	mkdir $(distdir)/html
> -	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
>  	-cp $(srcdir)/xml/*.xml $(distdir)/xml
>  	cp $(srcdir)/html/* $(distdir)/html
>  	-cp $(srcdir)/$(DOC_MODULE).types $(distdir)/
> diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am
> index 11f9e7b72..33bccabb7 100644
> --- a/doc/public/Makefile.am
> +++ b/doc/public/Makefile.am
> @@ -30,9 +30,6 @@ IGNORE_HFILES= \
>  # Extra options to supply to gtkdoc-mkdb
>  MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=cairo
>  
> -# Extra options to supply to gtkdoc-mktmpl
> -MKTMPL_OPTIONS=
> -
>  # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
>  content_files =	\
>  	language-bindings.xml \
> 


-- 
“Cold. Cold. Cold. Cold. Cold. Cold. Cold. Cold. Cold. Cold.” – Anna