tech@mandoc.bsd.lv
 help / color / Atom feed
* [PATCH] Implement -v to display the current version and exit
@ 2017-01-16  8:29 Michael Stapelberg
  2017-01-17  0:37 ` Ingo Schwarze
  0 siblings, 1 reply; 5+ messages in thread
From: Michael Stapelberg @ 2017-01-16  8:29 UTC (permalink / raw)
  To: tech


[-- Attachment #1: Type: text/plain, Size: 427 bytes --]

(Re-sending this post which was automatically denied before I
subscribed to this list.)

Rationale:
When using mandoc’s output in other services (e.g. a web man viewer),
it would be beneficial to display the version of mandoc that is in
use. Currently, one cannot determine mandoc’s version in a package
management-indepent way.

Please consider merging the attached patch. Thanks!

-- 
Best regards,
Michael

[-- Attachment #2: 0001-Implement-v-to-display-the-current-version-and-exit.patch --]
[-- Type: text/x-patch, Size: 1566 bytes --]

From 6846d805786f702ff28b6b2d370330bf2c16cc46 Mon Sep 17 00:00:00 2001
From: Michael Stapelberg <stapelberg@debian.org>
Date: Wed, 11 Jan 2017 09:06:46 +0100
Subject: [PATCH] Implement -v to display the current version and exit

---
 configure | 2 ++
 main.c    | 6 +++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/configure b/configure
index adf9eb4..e80cf68 100755
--- a/configure
+++ b/configure
@@ -40,6 +40,7 @@ UTF8_LOCALE=
 CC=`printf "all:\\n\\t@echo \\\$(CC)\\n" | env -i make -sf -`
 CFLAGS="-g -W -Wall -Wmissing-prototypes -Wstrict-prototypes -Wwrite-strings"
 CFLAGS="${CFLAGS} -Wno-unused-parameter"
+CPPFLAGS="-DVERSION=\\\"\${VERSION}\\\""
 LDADD=
 LDFLAGS=
 LD_NANOSLEEP=
@@ -438,6 +439,7 @@ BUILD_TARGETS	= ${BUILD_TARGETS}
 INSTALL_TARGETS	= ${INSTALL_TARGETS}
 CC		= ${CC}
 CFLAGS		= ${CFLAGS}
+CPPFLAGS	= ${CPPFLAGS}
 LDADD		= ${LDADD}
 LDFLAGS		= ${LDFLAGS}
 STATIC		= ${STATIC}
diff --git a/main.c b/main.c
index b64b3be..fcfb27f 100644
--- a/main.c
+++ b/main.c
@@ -195,7 +195,7 @@ main(int argc, char *argv[])
 	outmode = OUTMODE_DEF;
 
 	while (-1 != (c = getopt(argc, argv,
-			"aC:cfhI:iK:klM:m:O:S:s:T:VW:w"))) {
+			"aC:cfhI:iK:klM:m:O:S:s:T:vVW:w"))) {
 		switch (c) {
 		case 'a':
 			outmode = OUTMODE_ALL;
@@ -261,6 +261,10 @@ main(int argc, char *argv[])
 			if ( ! toptions(&curp, optarg))
 				return (int)MANDOCLEVEL_BADARG;
 			break;
+		case 'v':
+			printf("mandoc %s\n", VERSION);
+			exit(0);
+			break;
 		case 'W':
 			if ( ! woptions(&curp, optarg))
 				return (int)MANDOCLEVEL_BADARG;
-- 
2.11.0


^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Implement -v to display the current version and exit
  2017-01-16  8:29 [PATCH] Implement -v to display the current version and exit Michael Stapelberg
@ 2017-01-17  0:37 ` Ingo Schwarze
  2017-01-17  7:28   ` Michael Stapelberg
  0 siblings, 1 reply; 5+ messages in thread
From: Ingo Schwarze @ 2017-01-17  0:37 UTC (permalink / raw)
  To: Michael Stapelberg; +Cc: tech

Hi,

Michael Stapelberg wrote on Mon, Jan 16, 2017 at 09:29:07AM +0100:

> When using mandoc's output in other services (e.g. a web man viewer),
> it would be beneficial to display the version of mandoc that is in
> use.

Why?  In particular in a web viewer, you would end up displaying
that to end users.  They really shouldn't care.

> Currently, one cannot determine mandoc's version in a package
> management-indepent way.

Exactly, and that's a feature.  Version numbers contained in binaries
are very harmful.

Years ago, this option existed.  I got so fed up with it that i
deleted it.  Before, many bug reports were unusable because
people simply said "i'm using mandoc-1.10.5" and didn't bother
mentioning how it was built and packaged, or whether it was -current
or -release.

Once the version-option was gone, that problem completely went away
and people started reporting properly, like "i installed mandoc
from pkgsrc on FreeBSD 9, and ..." or "I compiled mandoc from
CVS HEAD as of (date) on Solaris 11, and ..."

> Please consider merging the attached patch. Thanks!

No, i don't want that.

If you absolutely need that for debian, consider making it a
debian-local patch, but please make sure that the following is
contained in the response printed:

 (1) the substring "debian"
 (2) if the package is OS-version-dependent, the complete version
     of the operating system the binary can run on
 (3) the name of the package manager that created the package
     containing the binary
 (4) the version number that package manager assigned to the
     package, including OS-local patch levels

Including the upstream release number is not important - but
it will likely happen anyway because it's probably part of item (4).


I cannot do that upstream because the essential information to
print is package-manager-dependent, and by definition, the
upstream build system cannot know anything about that.

But anyway, keeping track of which versions of software you have
installed is the task of the package manager in the first place,
and not the task of individual programs.

Oh, by the way, why can't you get the information you want from
the package manager instead of from mandoc?  If you can run

  mandoc -V

i guess you can run

  dpkg-query -l mandoc

with the proper options just as well?

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Implement -v to display the current version and exit
  2017-01-17  0:37 ` Ingo Schwarze
@ 2017-01-17  7:28   ` Michael Stapelberg
  2017-01-17 13:09     ` Ingo Schwarze
  0 siblings, 1 reply; 5+ messages in thread
From: Michael Stapelberg @ 2017-01-17  7:28 UTC (permalink / raw)
  To: Ingo Schwarze; +Cc: tech

On Tue, Jan 17, 2017 at 1:37 AM, Ingo Schwarze <schwarze@usta.de> wrote:
> Hi,
>
> Michael Stapelberg wrote on Mon, Jan 16, 2017 at 09:29:07AM +0100:
>
>> When using mandoc's output in other services (e.g. a web man viewer),
>> it would be beneficial to display the version of mandoc that is in
>> use.
>
> Why?  In particular in a web viewer, you would end up displaying
> that to end users.  They really shouldn't care.

End users might want to reproduce a rendering issue before reporting a
bug. For this use-case, it seems useful to know the version which was
used to generate the page.

>
>> Currently, one cannot determine mandoc's version in a package
>> management-indepent way.
>
> Exactly, and that's a feature.  Version numbers contained in binaries
> are very harmful.
>
> Years ago, this option existed.  I got so fed up with it that i
> deleted it.  Before, many bug reports were unusable because
> people simply said "i'm using mandoc-1.10.5" and didn't bother
> mentioning how it was built and packaged, or whether it was -current
> or -release.
>
> Once the version-option was gone, that problem completely went away
> and people started reporting properly, like "i installed mandoc
> from pkgsrc on FreeBSD 9, and ..." or "I compiled mandoc from
> CVS HEAD as of (date) on Solaris 11, and ..."

In my projects, when I was faced with this problem, I went exactly the
other route: I find “latest version that’s in FreeBSD 9” way to
imprecise, and just have my build system embed the git version number.
This works really well for me, but distributions tend to not patch my
projects.

I still think it’s valuable to have the upstream version number
available somehow. If you don’t want it to be considered as the
primary source of version information, that’s fine. Would you be okay
with making it available under a hard-to-discover flag name, e.g.
--upstream-version, accompanied by a message stating that users should
provide their package manager’s version when reporting bugs instead?

>
>> Please consider merging the attached patch. Thanks!
>
> No, i don't want that.
>
> If you absolutely need that for debian, consider making it a
> debian-local patch, but please make sure that the following is
> contained in the response printed:
>
>  (1) the substring "debian"
>  (2) if the package is OS-version-dependent, the complete version
>      of the operating system the binary can run on
>  (3) the name of the package manager that created the package
>      containing the binary
>  (4) the version number that package manager assigned to the
>      package, including OS-local patch levels
>
> Including the upstream release number is not important - but
> it will likely happen anyway because it's probably part of item (4).
>
>
> I cannot do that upstream because the essential information to
> print is package-manager-dependent, and by definition, the
> upstream build system cannot know anything about that.
>
> But anyway, keeping track of which versions of software you have
> installed is the task of the package manager in the first place,
> and not the task of individual programs.
>
> Oh, by the way, why can't you get the information you want from
> the package manager instead of from mandoc?  If you can run
>
>   mandoc -V
>
> i guess you can run
>
>   dpkg-query -l mandoc
>
> with the proper options just as well?

I could, but this would make my program non-portable. Worse, when
users put a different version of mandoc into their $PATH, the reported
version will be misleading.

-- 
Best regards,
Michael
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Implement -v to display the current version and exit
  2017-01-17  7:28   ` Michael Stapelberg
@ 2017-01-17 13:09     ` Ingo Schwarze
  2017-01-17 13:22       ` Michael Stapelberg
  0 siblings, 1 reply; 5+ messages in thread
From: Ingo Schwarze @ 2017-01-17 13:09 UTC (permalink / raw)
  To: Michael Stapelberg; +Cc: tech

Hi,

Michael Stapelberg wrote on Tue, Jan 17, 2017 at 08:28:48AM +0100:
> On Tue, Jan 17, 2017 at 1:37 AM, Ingo Schwarze <schwarze@usta.de> wrote:
> > Michael Stapelberg wrote on Mon, Jan 16, 2017 at 09:29:07AM +0100:

>>> When using mandoc's output in other services (e.g. a web man viewer),
>>> it would be beneficial to display the version of mandoc that is in
>>> use.

>> Why?  In particular in a web viewer, you would end up displaying
>> that to end users.  They really shouldn't care.

> End users might want to reproduce a rendering issue before reporting a
> bug. For this use-case, it seems useful to know the version which was
> used to generate the page.

I still don't get it.  If they report to the server operators, those
people will know the version they run anyway.  If they cnsider
reporting to me, we have exactly what i don't want:  I much prefer
a report "on http://foo.bar.com/pagename.3, rendering is broken as
follows" to "with mandoc-1.13.4" because in the former case, i can
check myself, and in the latter i'm clueless what is going on.  So
the version number should *NOT* be in there.  Or at least it must
state OS and packaging information, or it's worse than useless, in
particular for that purpose.

> In my projects, when I was faced with this problem, I went exactly the
> other route: I find "latest version that's in FreeBSD 9" way to
> imprecise,

Nothing is imprecise about that.  I can easily see the exact source
code they have online.

> and just have my build system embed the git version number.

Well, embedding the bsd.lv CVS commitid would be a terrible idea
for the same reasons as embedding the release version string.

Besides, OpenBSD and NetBSD use CVS (different versions), FreeBSD
uses SVN, DragonFly and illumos use git - consequently, i'm out of
luck regarding consistent downstream commitids.

> This works really well for me, but distributions tend to not patch
> my projects.

It wouldn't work at all for mandoc.  All major users have patches.
The most important user (OpenBSD) uses -current rather than any
release.  The second most important user (FreeBSD) often uses
something that is half-way betwwen the latest release and -current.
The third most important (NetBSD) has a heavily patched version -
not for very good reasons, but they *are* quite patch-happy with
respect to mandoc.

> I still think it's valuable to have the upstream version number
> available somehow. If you don't want it to be considered as the
> primary source of version information, that's fine.

Worse than that, it's misleading and caused real problems in the
past.

> Would you be okay with making it available under a hard-to-discover
> flag name, e.g. --upstream-version,

No.  Long options are inacceptable.  Besides, in interface design,
it is crucial to minimize the number of options.

> accompanied by a message

No.  Programs should not be chatty, but concise.  "Here is some
information, but do not use it" makes no sense.  Not providing
the misleading information in the first place is clearly better.

Besides, i see a contradiction there.  On the one hand, you want
the information to be hard to discover; but then you want to
display it on the web?  With the message?  Where are web users
supposed to get the packaging information from?

In the end, i think you should simply provide no version number
whatsoever.  That's less work for you and also better for me in
case of bug reports because it gives a better chance that people
actually explain what they are looking at.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Implement -v to display the current version and exit
  2017-01-17 13:09     ` Ingo Schwarze
@ 2017-01-17 13:22       ` Michael Stapelberg
  0 siblings, 0 replies; 5+ messages in thread
From: Michael Stapelberg @ 2017-01-17 13:22 UTC (permalink / raw)
  To: Ingo Schwarze; +Cc: tech

Okay. Thanks for the extensive rationale. I’ll do what works best for
you and not provide a version number.

On Tue, Jan 17, 2017 at 5:09 AM, Ingo Schwarze <schwarze@usta.de> wrote:
> Hi,
>
> Michael Stapelberg wrote on Tue, Jan 17, 2017 at 08:28:48AM +0100:
>> On Tue, Jan 17, 2017 at 1:37 AM, Ingo Schwarze <schwarze@usta.de> wrote:
>> > Michael Stapelberg wrote on Mon, Jan 16, 2017 at 09:29:07AM +0100:
>
>>>> When using mandoc's output in other services (e.g. a web man viewer),
>>>> it would be beneficial to display the version of mandoc that is in
>>>> use.
>
>>> Why?  In particular in a web viewer, you would end up displaying
>>> that to end users.  They really shouldn't care.
>
>> End users might want to reproduce a rendering issue before reporting a
>> bug. For this use-case, it seems useful to know the version which was
>> used to generate the page.
>
> I still don't get it.  If they report to the server operators, those
> people will know the version they run anyway.  If they cnsider
> reporting to me, we have exactly what i don't want:  I much prefer
> a report "on http://foo.bar.com/pagename.3, rendering is broken as
> follows" to "with mandoc-1.13.4" because in the former case, i can
> check myself, and in the latter i'm clueless what is going on.  So
> the version number should *NOT* be in there.  Or at least it must
> state OS and packaging information, or it's worse than useless, in
> particular for that purpose.
>
>> In my projects, when I was faced with this problem, I went exactly the
>> other route: I find "latest version that's in FreeBSD 9" way to
>> imprecise,
>
> Nothing is imprecise about that.  I can easily see the exact source
> code they have online.
>
>> and just have my build system embed the git version number.
>
> Well, embedding the bsd.lv CVS commitid would be a terrible idea
> for the same reasons as embedding the release version string.
>
> Besides, OpenBSD and NetBSD use CVS (different versions), FreeBSD
> uses SVN, DragonFly and illumos use git - consequently, i'm out of
> luck regarding consistent downstream commitids.
>
>> This works really well for me, but distributions tend to not patch
>> my projects.
>
> It wouldn't work at all for mandoc.  All major users have patches.
> The most important user (OpenBSD) uses -current rather than any
> release.  The second most important user (FreeBSD) often uses
> something that is half-way betwwen the latest release and -current.
> The third most important (NetBSD) has a heavily patched version -
> not for very good reasons, but they *are* quite patch-happy with
> respect to mandoc.
>
>> I still think it's valuable to have the upstream version number
>> available somehow. If you don't want it to be considered as the
>> primary source of version information, that's fine.
>
> Worse than that, it's misleading and caused real problems in the
> past.
>
>> Would you be okay with making it available under a hard-to-discover
>> flag name, e.g. --upstream-version,
>
> No.  Long options are inacceptable.  Besides, in interface design,
> it is crucial to minimize the number of options.
>
>> accompanied by a message
>
> No.  Programs should not be chatty, but concise.  "Here is some
> information, but do not use it" makes no sense.  Not providing
> the misleading information in the first place is clearly better.
>
> Besides, i see a contradiction there.  On the one hand, you want
> the information to be hard to discover; but then you want to
> display it on the web?  With the message?  Where are web users
> supposed to get the packaging information from?
>
> In the end, i think you should simply provide no version number
> whatsoever.  That's less work for you and also better for me in
> case of bug reports because it gives a better chance that people
> actually explain what they are looking at.
>
> Yours,
>   Ingo



-- 
Best regards,
Michael
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, back to index

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-01-16  8:29 [PATCH] Implement -v to display the current version and exit Michael Stapelberg
2017-01-17  0:37 ` Ingo Schwarze
2017-01-17  7:28   ` Michael Stapelberg
2017-01-17 13:09     ` Ingo Schwarze
2017-01-17 13:22       ` Michael Stapelberg

tech@mandoc.bsd.lv

Archives are clonable: git clone --mirror http://inbox.vuxu.org/mandoc-tech

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://inbox.vuxu.org/vuxu.archive.mandoc.tech


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git