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

Discussion:

Bryce Harrington

2018-08-24 17:17:03 UTC

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)
- 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 \

--
2.17.1
--
cairo mailing list
***@cairographics.org
https://lists.cairographics.org/mailman/listi

Uli Schlachter

2018-08-25 06:11:39 UTC

Permalink

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

Post by Bryce Harrington
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

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

Post by Bryce Harrington
- cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
- touch tmpl-build.stamp
-
-tmpl.stamp: tmpl-build.stamp
-
-
-
#### 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
##############
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
--
cairo mailing list
***@cairographics.org
https://lists.cairographics.org

Bryce Harrington

2018-09-04 16:35:40 UTC

Permalink

Post by 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?

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

Post by Uli Schlachter
Cheers & sorry,
Uli

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

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

--
cairo mailing list
***@cairographics.org
https://lists.cairograph

Bryce Harrington

2018-09-14 20:01:25 UTC

Permalink

Post by Bryce Harrington

Yeah, the links are simply removing the functionality, essentially the
same as what I've done. I think I'll go ahead with the plan of landing
this for now, and getting another snapshot release out, and then keep an
eye out for regressions.

I don't know how much time is worth expending on this; if we want to
move to meson I suspect much of this will need to be scrapped and redone
anyway. But if anyone does have time and interest to find if there are
cleaner solutions, it'd be appreciated.

Bryce

Post by Bryce Harrington

Post by Uli Schlachter
Cheers & sorry,
Uli

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

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

--
cairo mailing list
https://lists.cairographics.org/mailman/listinfo/cairo

--
cairo mailing list
***@cairographics.org
http

Adrian Johnson

2018-09-22 06:24:05 UTC

Permalink

Post by Bryce Harrington
I don't know how much time is worth expending on this; if we want to
move to meson I suspect much of this will need to be scrapped and redone
anyway. But if anyone does have time and interest to find if there are
cleaner solutions, it'd be appreciated.

I have a cairo meson build if you want to use it. I was using meson for
cairo development as found the autotools build time unsatisfactory,
particularly on cygwin.

--
cairo mailing list
***@cairographics.org
https://lists.cairographics.org/mailman/listinfo/cair

Continue reading on narkive:

Search results for '[cairo] [RFC] [PATCH cairo] doc: Drop tmpl support' (Questions and Answers)

replies

who likes president Bush??

started 2008-01-31 10:02:32 UTC

polls & surveys