Re: update lang/fennel; move man pages to a -docs subpackage
Hi Omar, Omar Polo wrote on Tue, Sep 19, 2023 at 02:30:08PM +0200: > I have to note that one could end up installing only the -docs > package, is it a concern? If a user explicitely says "pkg_add fennel-docs" without saying "pkg_add fennel", sure, they only get the documentation installed. But that's what they asked for, so i don't see a problem there. Occasionally, it might even be useful, for example when a user on a very slow network connection wants to look at the documentation before deciding whether they really want to download the code (and the other dependencies like lua). Maybe not the usual case - when you want to study documentation, you usually also want to play around a bit with the program - but clearly not harmful. It certainly won't be the only package containing documentation only and no code. Consider, for example, books/man-pages-posix. Yours, Ingo
Re: update lang/fennel; move man pages to a -docs subpackage
On 2023/09/19 12:38:52 +0100, Stuart Henderson wrote:
> On 2023/09/19 11:32, Ingo Schwarze wrote:
> > Hi Omar,
> >
> > Omar Polo wrote on Tue, Sep 19, 2023 at 10:10:44AM +0200:
> >
> > > However, I disliked to ship the same set of man pages four times, so
> > > here's an attempt to move them to a -docs subpackage. (thanks sthen@
> > > for pointing me at www/squid)
> >
> > I wouldn't consider saving the diskspace for three manual pages the
> > main benefit, even though that hardly hurts, either. It seems more
> > important that your approach of making a subpackage prevents apropos(1)
> > from listing multiple pages and making the user wonder whether they
> > differ, possibly wasting their time running diff(1).
> >
> > This is even likely to become worse in the near future when man(1)
> > starts warning that there are multiple manual pages of the same name
> > in the same section.
> >
> > However, *if* you expect that the pages are likely to actually
> > become different in the future, that might be a reason against
> > making this subpackage. Then again, if that happens, it would
> > also be an option to merge them back in after it happens.
>
> They won't; the different flavours are merely building with different
> versions of lua, the manuals are unaffected.
Currently they don't change and I don't expect them to change in the
future.
> > > Note that RUN_DEPENDS-docs is needed otherwise (via lua.port.mk and
> > > global RUN_DEPENDS) it ends up depending on lang/lua,${FLAVOR} and
> > > that will break subsequent build (the plist register the deps on one
> > > flavor, when building the next one the plist would differ)
> >
> > Again, i don't think these technical considerations are the only
> > reason for RUN_DEPENDS-docs. I general, i stongly feel that if
> > you say "pkg_add food", that should absolutely install all the
> > documentation for the "foo" daemon. I mean, how is the user
> > supposed to use it if there is no documentation? We want sane
> > defaults, and installing software without documentation is not
> > exactly sane. Why should we send the user on a wild goose chase
> > to search for a "foo" documentation package after they alraedy
> > said they want food?
> >
> > I certainly don't want to emulate the bad habit of some Linux
> > distros to not install documentation unless the user goes an extra
> > mile specifically asking for it.
Completely agree.
> Explicitly setting RUN_DEPENDS-docs to makes sense,
> but I think we should also have "RUN_DEPENDS-main += lang/fennel,-docs".
There is already a RUN_DEPENDS-main += lang/fennel,-docs, so nevermind
which flavor(s) you install the -docs subpackage will always be
installed as dependency.
It was at the top together with the FULLPKGNAME/PATH bits, so easy to
miss. I've moved it in a more usual position near the end.
I have to note that one could end up installing only the -docs
package, is it a concern?
> Otherwise the ports aspects look correct to me.
>
> > > However, I'm not sure I'm overthinking it and just rename the three
> > > new manpages to fennel-${V}-XYZ instead of doing a subpackage would be
> > > preferred.
> >
> > I did not audit this ports-wise, but i do like your general idea.
> > It doesn't feel like overengineering to me, there appear to be actual
> > benefits from the user perspective.
>
> Agreed.
>
> > > +SITES = https://git.sr.ht/~technomancy/fennel/archive/
>
> btw, I think this could probably change to DIST_TUPLES if wanted.
right, while we're here it also further semplifies the makefile.
Ingo, Sthen, thanks!
Index: Makefile
===
RCS file: /home/cvs/ports/lang/fennel/Makefile,v
retrieving revision 1.2
diff -u -p -r1.2 Makefile
--- Makefile26 Dec 2022 11:05:59 - 1.2
+++ Makefile19 Sep 2023 12:17:07 -
@@ -1,8 +1,14 @@
-COMMENT = Lisp dialect that runs on Lua ${MODLUA_VERSION}
+COMMENT-main = Lisp dialect that runs on Lua ${MODLUA_VERSION}
+COMMENT-docs = Documentation for fennel
-V =1.2.1
-PKGNAME = fennel-$V
-FULLPKGNAME = fennel-${FLAVOR}-${V}
+V =1.3.1
+DIST_TUPLE = srht technomancy fennel $V .
+FULLPKGPATH-main = lang/fennel,-main,${FLAVOR}
+FULLPKGNAME-main = fennel-${FLAVOR}-${V}
+
+# -docs isn't flavoured, so overwrite its default name/path
+FULLPKGNAME-docs = fennel-docs-$V
+FULLPKGPATH-docs = ${PKGPATH},-docs
CATEGORIES = lang
@@ -13,9 +19,7 @@ MAINTAINER = Omar Polo
# MIT
PERMIT_PACKAGE = Yes
-MASTER_SITES = https://git.sr.ht/~technomancy/fennel/archive/
-
-DISTFILES =fennel-{}$V${EXTRACT_SUFX}
+MULTI_PACKAGES = -main -docs
MODULES = lang/lua
@@ -29,13 +33,14 @@ ALL_TARGET =build
MAKE_FLAGS += LUA=${MODLUA_BIN} \
LUA_VERSION=${MODLUA_VERSION} \
LUA_LIB_DIR=${MODLUA_LIBDIR}
-FAKE_FLAGS += PREFIX=${TRUEPREFIX}
+FAKE_FLAGS += PREFIX=${TRUEPREFIX} \
+
Re: update lang/fennel; move man pages to a -docs subpackage
On 2023/09/19 11:32, Ingo Schwarze wrote:
> Hi Omar,
>
> Omar Polo wrote on Tue, Sep 19, 2023 at 10:10:44AM +0200:
>
> > The update itself is straightforward and all tests are passing.
> > However, upstream added three more man pages (for a total of four now)
> > which would get shipped in all of four fennel flavors (lua5[1-3]).
> >
> > Now, this is practice works, i.e. even if you have installed all the
> > flavors `man fennel-api' works and since all the manpages are
> > identical it's not really important if mandoc chooses fennel-5.1-api
> > or fennel-5.4-api.
> >
> > However, I disliked to ship the same set of man pages four times, so
> > here's an attempt to move them to a -docs subpackage. (thanks sthen@
> > for pointing me at www/squid)
>
> I wouldn't consider saving the diskspace for three manual pages the
> main benefit, even though that hardly hurts, either. It seems more
> important that your approach of making a subpackage prevents apropos(1)
> from listing multiple pages and making the user wonder whether they
> differ, possibly wasting their time running diff(1).
>
> This is even likely to become worse in the near future when man(1)
> starts warning that there are multiple manual pages of the same name
> in the same section.
>
> However, *if* you expect that the pages are likely to actually
> become different in the future, that might be a reason against
> making this subpackage. Then again, if that happens, it would
> also be an option to merge them back in after it happens.
They won't; the different flavours are merely building with different
versions of lua, the manuals are unaffected.
> > Note that RUN_DEPENDS-docs is needed otherwise (via lua.port.mk and
> > global RUN_DEPENDS) it ends up depending on lang/lua,${FLAVOR} and
> > that will break subsequent build (the plist register the deps on one
> > flavor, when building the next one the plist would differ)
>
> Again, i don't think these technical considerations are the only
> reason for RUN_DEPENDS-docs. I general, i stongly feel that if
> you say "pkg_add food", that should absolutely install all the
> documentation for the "foo" daemon. I mean, how is the user
> supposed to use it if there is no documentation? We want sane
> defaults, and installing software without documentation is not
> exactly sane. Why should we send the user on a wild goose chase
> to search for a "foo" documentation package after they alraedy
> said they want food?
>
> I certainly don't want to emulate the bad habit of some Linux
> distros to not install documentation unless the user goes an extra
> mile specifically asking for it.
Explicitly setting RUN_DEPENDS-docs to makes sense,
but I think we should also have "RUN_DEPENDS-main += lang/fennel,-docs".
Otherwise the ports aspects look correct to me.
> > However, I'm not sure I'm overthinking it and just rename the three
> > new manpages to fennel-${V}-XYZ instead of doing a subpackage would be
> > preferred.
>
> I did not audit this ports-wise, but i do like your general idea.
> It doesn't feel like overengineering to me, there appear to be actual
> benefits from the user perspective.
Agreed.
> > +SITES = https://git.sr.ht/~technomancy/fennel/archive/
btw, I think this could probably change to DIST_TUPLES if wanted.
Re: update lang/fennel; move man pages to a -docs subpackage
Hi Omar,
Omar Polo wrote on Tue, Sep 19, 2023 at 10:10:44AM +0200:
> The update itself is straightforward and all tests are passing.
> However, upstream added three more man pages (for a total of four now)
> which would get shipped in all of four fennel flavors (lua5[1-3]).
>
> Now, this is practice works, i.e. even if you have installed all the
> flavors `man fennel-api' works and since all the manpages are
> identical it's not really important if mandoc chooses fennel-5.1-api
> or fennel-5.4-api.
>
> However, I disliked to ship the same set of man pages four times, so
> here's an attempt to move them to a -docs subpackage. (thanks sthen@
> for pointing me at www/squid)
I wouldn't consider saving the diskspace for three manual pages the
main benefit, even though that hardly hurts, either. It seems more
important that your approach of making a subpackage prevents apropos(1)
from listing multiple pages and making the user wonder whether they
differ, possibly wasting their time running diff(1).
This is even likely to become worse in the near future when man(1)
starts warning that there are multiple manual pages of the same name
in the same section.
However, *if* you expect that the pages are likely to actually
become different in the future, that might be a reason against
making this subpackage. Then again, if that happens, it would
also be an option to merge them back in after it happens.
> Note that RUN_DEPENDS-docs is needed otherwise (via lua.port.mk and
> global RUN_DEPENDS) it ends up depending on lang/lua,${FLAVOR} and
> that will break subsequent build (the plist register the deps on one
> flavor, when building the next one the plist would differ)
Again, i don't think these technical considerations are the only
reason for RUN_DEPENDS-docs. I general, i stongly feel that if
you say "pkg_add food", that should absolutely install all the
documentation for the "foo" daemon. I mean, how is the user
supposed to use it if there is no documentation? We want sane
defaults, and installing software without documentation is not
exactly sane. Why should we send the user on a wild goose chase
to search for a "foo" documentation package after they alraedy
said they want food?
I certainly don't want to emulate the bad habit of some Linux
distros to not install documentation unless the user goes an extra
mile specifically asking for it.
> However, I'm not sure I'm overthinking it and just rename the three
> new manpages to fennel-${V}-XYZ instead of doing a subpackage would be
> preferred.
I did not audit this ports-wise, but i do like your general idea.
It doesn't feel like overengineering to me, there appear to be actual
benefits from the user perspective.
Yours,
Ingo
update lang/fennel; move man pages to a -docs subpackage
The update itself is straightforward and all tests are passing.
However, upstream added three more man pages (for a total of four now)
which would get shipped in all of four fennel flavors (lua5[1-3]).
Now, this is practice works, i.e. even if you have installed all the
flavors `man fennel-api' works and since all the manpages are
identical it's not really important if mandoc chooses fennel-5.1-api
or fennel-5.4-api.
However, I disliked to ship the same set of man pages four times, so
here's an attempt to move them to a -docs subpackage. (thanks sthen@
for pointing me at www/squid)
Note that RUN_DEPENDS-docs is needed otherwise (via lua.port.mk and
global RUN_DEPENDS) it ends up depending on lang/lua,${FLAVOR} and
that will break subsequent build (the plist register the deps on one
flavor, when building the next one the plist would differ)
However, I'm not sure I'm overthinking it and just rename the three
new manpages to fennel-${V}-XYZ instead of doing a subpackage would be
preferred.
Index: Makefile
===
RCS file: /home/cvs/ports/lang/fennel/Makefile,v
retrieving revision 1.2
diff -u -p -r1.2 Makefile
--- Makefile26 Dec 2022 11:05:59 - 1.2
+++ Makefile18 Sep 2023 15:52:07 -
@@ -1,8 +1,16 @@
-COMMENT = Lisp dialect that runs on Lua ${MODLUA_VERSION}
+COMMENT-main = Lisp dialect that runs on Lua ${MODLUA_VERSION}
+COMMENT-docs = Documentation for fennel
-V =1.2.1
+V =1.3.1
PKGNAME = fennel-$V
-FULLPKGNAME = fennel-${FLAVOR}-${V}
+FULLPKGPATH-main = lang/fennel,-main,${FLAVOR}
+FULLPKGNAME-main = fennel-${FLAVOR}-${V}
+
+# -docs isn't flavoured, so overwrite its default name/path
+FULLPKGNAME-docs = fennel-docs-$V
+FULLPKGPATH-docs = ${PKGPATH},-docs
+RUN_DEPENDS-main+= lang/fennel,-docs
+RUN_DEPENDS-docs =
CATEGORIES = lang
@@ -13,7 +21,9 @@ MAINTAINER = Omar Polo
# MIT
PERMIT_PACKAGE = Yes
-MASTER_SITES = https://git.sr.ht/~technomancy/fennel/archive/
+MULTI_PACKAGES = -main -docs
+
+SITES =https://git.sr.ht/~technomancy/fennel/archive/
DISTFILES =fennel-{}$V${EXTRACT_SUFX}
@@ -29,13 +39,13 @@ ALL_TARGET =build
MAKE_FLAGS += LUA=${MODLUA_BIN} \
LUA_VERSION=${MODLUA_VERSION} \
LUA_LIB_DIR=${MODLUA_LIBDIR}
-FAKE_FLAGS += PREFIX=${TRUEPREFIX}
+FAKE_FLAGS += PREFIX=${TRUEPREFIX} \
+ MAN_DIR=${PREFIX}
WRKDIST = ${WRKDIR}/${PKGNAME}
post-install:
chmod +x ${PREFIX}/bin/fennel
cd ${PREFIX}/bin && mv fennel fennel-${MODLUA_VERSION}
- cd ${PREFIX}/man/man1 && mv fennel.1 fennel-${MODLUA_VERSION}.1
.include
Index: distinfo
===
RCS file: /home/cvs/ports/lang/fennel/distinfo,v
retrieving revision 1.1.1.1
diff -u -p -r1.1.1.1 distinfo
--- distinfo24 Dec 2022 08:57:07 - 1.1.1.1
+++ distinfo18 Sep 2023 11:20:49 -
@@ -1,2 +1,2 @@
-SHA256 (fennel-1.2.1.tar.gz) = ZlSq23ZZu/iNOHkZA5JXPhrjkIfqr1CE6V9F246CrVE=
-SIZE (fennel-1.2.1.tar.gz) = 271590
+SHA256 (fennel-1.3.1.tar.gz) = gz2Qt+me3Uh0A/Uf38PLsmO/lltyqRS7u7AVbGEy1GU=
+SIZE (fennel-1.3.1.tar.gz) = 293564
Index: pkg/DESCR
===
RCS file: pkg/DESCR
diff -N pkg/DESCR
--- pkg/DESCR 24 Dec 2022 08:57:07 - 1.1.1.1
+++ /dev/null 1 Jan 1970 00:00:00 -
@@ -1,16 +0,0 @@
-Fennel is a programming language that brings together the speed,
-simplicity, and reach of Lua with the flexibility of a lisp syntax and
-macro system.
-
- - Full Lua compatibility: Easily call any Lua function or library from
- Fennel and vice-versa.
-
- - Zero overhead: Compiled code should be just as efficient as
- hand-written Lua.
-
- - Compile-time macros: Ship compiled code with no runtime dependency on
- Fennel.
-
- - Embeddable: Fennel is a one-file library as well as an executable.
- Embed it in other programs to support runtime extensibility and
- interactive development.
Index: pkg/DESCR-docs
===
RCS file: pkg/DESCR-docs
diff -N pkg/DESCR-docs
--- /dev/null 1 Jan 1970 00:00:00 -
+++ pkg/DESCR-docs 19 Sep 2023 08:09:09 -
@@ -0,0 +1 @@
+Manual pages for fennel.
Index: pkg/DESCR-main
===
RCS file: pkg/DESCR-main
diff -N pkg/DESCR-main
--- /dev/null 1 Jan 1970 00:00:00 -
+++ pkg/DESCR-main 24 Dec 2022 08:57:07 -
@@ -0,0 +1,16 @@
+Fennel is a programming language that brings together the speed,
+simplicity, and reach of Lua with the flexibility of a lisp syntax and
+macro system.
+
+ - Full Lua compatibility: Easily call any Lua function or library from
+ Fennel and vice-versa.
+
+ - Zero overhead: Compiled code should be just as efficient as
+ hand-written Lua.
+
+ - Compile-time macros: Ship compiled code with
