From: Stuart Henderson <stu@spacehopper.org>
Subject: Re: databases/sqlite3-tcl: Better documentation
To: Stuart Cassoff <exokoide@yahoo.ca>
Cc: OpenBSD Ports <ports@openbsd.org>
Date: Sat, 29 Nov 2025 12:15:18 +0000

On 2025/11/29 06:47, Stuart Cassoff wrote:
> The default documentation installed by databases/sqlite3-tcl is a tiny man 
> page with instructions to go to the sqlite.org site to read the real docs.
> Most unsatisfying.
> 
> This pack o' madness downloads the html doc and the css for it, and
> massages them together into a nice document available to the end user.

This doesn't handle the situation when upstream change the contents of
those files. If you want to include the docs, fetching the (versioned)
zip from upstream would be better, also this would then match the sqlite
version packaged. e.g.

SITES.doc =             https://sqlite.org/2025/
DISTFILES.doc =         sqlite-doc-351000.zip

The sed looks rather fragile for updates, if I were doing this I'd just
copy html/css and images/sqlite*banner.svg (from ${WRKDIR}/sqlite-doc-*/)
without modifying, the results look ok to me and I don't think the broken
hrefs are a problem.

> 
> Hope it's not too much,
> 
> 
> Stu
> 
> 
> 
> diff -Nurp /usr/ports/databases/sqlite3-tcl/Makefile ./Makefile
> --- /usr/ports/databases/sqlite3-tcl/Makefile	Wed Nov 19 15:31:24 2025
> +++ ./Makefile	Sat Nov 29 06:40:28 2025
> @@ -4,6 +4,7 @@ V =			3.51.0
>  
>  DISTNAME =		sqlite${V}
>  PKGNAME =		sqlite3-tcl-${V}
> +REVISION =		0
>  
>  CATEGORIES =		databases
>  HOMEPAGE =		https://cyqlite.sourceforge.io/cgi-bin/sqlite/home
> @@ -15,9 +16,13 @@ PERMIT_PACKAGE =	Yes
>  WANTLIB =		pthread
>  
>  SITES =			${SITE_SOURCEFORGE:=tcl/}
> +SITES.d =		https://sqlite.org/
>  
>  DISTFILES =		tclsqlite{sqlite}${V}${EXTRACT_SUFX}
> +DISTFILES.d =		${DOC_HTML} tclsqlite{sqlite}.css
>  
> +EXTRACT_ONLY =		tclsqlite${V}${EXTRACT_SUFX}
> +
>  MODULES =		lang/tcl
>  MODTCL_VERSION =	8.6
>  
> @@ -48,13 +53,37 @@ CFLAGS +=		-USQLITE_ENABLE_OFFSET_SQL_FUNC \
>  			-USQLITE_UNTESTABLE \
>  			-USQLITE_USE_ALLOCA
>  
> +INSTALL_TARGET =	all install-binaries install-libraries
>  TEST_TARGET =		test
>  
>  SUBST_VARS =		VER
>  
>  VER =			${V:S/.//g}
>  
> +DOC_HTML = 		tclsqlite.html
> +DOC_CSS = 		tclsqlite.css
> +
>  pre-configure:
>  	@${MODTCL_TCLSH_ADJ} ${WRKSRC}/compat/sqlite3/spaceanal.tcl
> +
> +post-build:
> +	@cd ${WRKBUILD} && \
> +	cp ${DISTDIR}/${DOC_HTML} ${DISTDIR}/${DOC_CSS} . && \
> +	sed \
> +	  -e 's!^<link href="sqlite.css" rel="stylesheet">$$!<style>!' \
> +	  -e '/^<style>$$/r ${DOC_CSS}' \
> +	  -e '//a\'"`printf '\n</style>'`" \
> +	  -e '/^<a href="index.html">$$/,/^<\/script>$$/d' \
> +	  -e '/^<div class=nosearch>$$/d' \
> +	  -e 's!^</p>\(<table border="0" cellpadding="10" width="100%">\)$$!\1!' \
> +	  -e 's!^..*This page was last updated on..*$$!</body></html>!' \
> +	  -e '/^<details class="fancy_toc">$$/i\'"`printf '\n%s' \
> +	       '<a href="https://sqlite.org/tclsqlite.html">View this document at sqlite.org</a><br>'`" \
> +	< ${DOC_HTML} > ${DOC_HTML}.new
> +
> +post-install:
> +	${INSTALL_DATA_DIR} ${PREFIX}/share/doc/sqlite3-tcl
> +	${INSTALL_DATA} ${WRKBUILD}/${DOC_HTML}.new \
> +		${PREFIX}/share/doc/sqlite3-tcl/${DOC_HTML}
>  
>  .include <bsd.port.mk>
> diff -Nurp /usr/ports/databases/sqlite3-tcl/distinfo ./distinfo
> --- /usr/ports/databases/sqlite3-tcl/distinfo	Wed Nov 19 15:31:24 2025
> +++ ./distinfo	Sat Nov 29 06:40:44 2025
> @@ -1,2 +1,6 @@
> +SHA256 (tclsqlite.css) = JzwMqxnJ8kYU6DfpOD4/pco6TiogRXp6EFTAYA3H6ys=
> +SHA256 (tclsqlite.html) = qStLFn7U7N6x3QUrbKvCUyuFA7+LMj1r4nJgi+qWu98=
>  SHA256 (tclsqlite3.51.0.tar.gz) = 42ysC7hUoPZx02PIDr9Zd/oQh6apm1RrCneUpEL5Y+4=
> +SIZE (tclsqlite.css) = 6868
> +SIZE (tclsqlite.html) = 59335
>  SIZE (tclsqlite3.51.0.tar.gz) = 3068895
> diff -Nurp /usr/ports/databases/sqlite3-tcl/pkg/PLIST ./pkg/PLIST
> --- /usr/ports/databases/sqlite3-tcl/pkg/PLIST	Wed Nov 19 15:31:24 2025
> +++ ./pkg/PLIST	Fri Nov 14 15:56:27 2025
> @@ -2,6 +2,7 @@
>  lib/tcl/sqlite3/
>  @so lib/tcl/sqlite3/libsqlite${VER}.so
>  lib/tcl/sqlite3/pkgIndex.tcl
> -@man man/mann/sqlite3.n
> +share/doc/sqlite3-tcl/
> +share/doc/sqlite3-tcl/tclsqlite.html
>  share/examples/sqlite3-tcl/
>  share/examples/sqlite3-tcl/sqlite3_analyzer
>