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

Tue Sep 4 16:35:40 UTC 2018

On Sat, Aug 25, 2018 at 08:11:39AM +0200, Uli Schlachter wrote:
> 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?

Yeah I've only interacted with gtkdoc as part of the release process,
never really dug into it.  But the code in the Makefile looks
like it builds indexes and stuff.  I also noted the comments that
nothing should break, guess I'm just skeptical; maybe it'd be easiest to
land the patch and just see what breaks on the website (guessing it'll
be pretty obvious), but I'll check those links out (thanks) and dig a
bit more.  I don't want to expend a huge amount of time on it but maybe
if it does regress, there's a simple fix.

Thanks!
Bryce

> 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