Re: Specifying dependencies more clearly

[Alejandro Colomar]

Hi Branden,

On 11/8/22 16:12, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2022-11-08T13:26:21+0100, Alejandro Colomar wrote:
> > I've always had trouble installing the correct dependencies for groff,
> > since depending on what you compile you might need some more or some
> > less dependencies, and there's not a clear list of what you need for
> > what.
>
> I'm sorry to hear this, because it is one of the points I have tried
> consciously to clarify.

Okay, sorry.  It's probably a bit of my fault.  I was extremely pissed off these 
days[1], and I wasn't probably fresh enough to read those files carefully enough.

> > I suggest that you add a very schematic list similar to the one I added for
> > the Linux man-pages project:
> >
> > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/INSTALL#n73>
> >
> > BTW, I acknowledge, that this list in the man-pages is not complete, because
> > part of it is split into another file:
> >
> > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/RELEASE#n14>
> >
> > However, that's something I did on purpose, since distributing and
> > installing from source are completely unrelated processes.
>
> groff has a similar challenge; building it from a distribution archive
> ("release") has significantly fewer requirements than building from a
> repository, especially now.  The groff 1.23.0 distribution archive will
> no longer require a TeX installation to build our Texinfo manual.  But
> since most people probably didn't try to build that anyway, I guess the
> most noticeable reduction is that a yacc program won't be required.
>
> As I said, I've tried to make this stuff clear.  groff's "INSTALL.REPO"
> does tell the reader to consult "INSTALL.extra"; maybe you have a
> suggestion for how I can make that more noticeable.

It's actually as you say.  There's a pointer to the other file, and that other 
file seems to say that you basically install ghostscript(1), and you'll have the 
Nimbus fonts.

I somehow missed[2] that pointer.

But it doesn't work.  I do have ghostscript installed (probably from a previous 
moment that I installed groff from source), and yet I do have the Nimbus font 
issues.

It may be the issue that the deps mention about ambiguous paths; don't know.  I 
don't know if I have multiple versions of the URW fonts in my system.  I hope I 
don't, because I rarely install things from source, so I trust Debian packaging 
to sort that out for me.  Unless some groff configure scripts have messed my 
system about that, which I don't expect either...

Let's see if we can first find what is the actual bug, and then analyze what 
should be changed in the INSTALL.* files about it, if at all.

> Not everything that a groff build depends on is a command, and some
> components don't even have a man page, like the troublesome URW fonts.
> It is thus tough for me to have a terse list of section 1 man page
> references as you do.

I actually have non-command software there, but only one:

libbsd-dev

...

>  I furthermore try to be ecumenical regarding
> packaging systems, and not refer to requirements in terms of, say,
> Debian package names.[1]

And yes, I had to make the decission to show the Debian name for it, to keep it 
simple; I understand why this may not be the most desirable thing to do.

Although my care about proprietary distros (hi RHEL :) is close to zero, there's 
more than Debian in the free world, I know.  It's just easiest to put it like that.

> Another of the things I have tried to do is ensure that we have helpful
> and communicative Autoconf tests for dependencies.  I have also revised
> the configuration banner to communicate more relevant information.
>
> GNU Troff version 1.23.0.rc1.3365-2653e-dirty
> ----------------------------------------------------------------------
>   installation directory prefix    : /usr/local
>   C++ compiler and options         : g++ -Wall -Wextra
>   use libgroff's memory allocator  : no
>   C compiler and options           : gcc -Wall -Wextra
>   Perl interpreter version         : 5.32.1
>   X11 support                      : enabled
>   X11 app defaults directory       : /usr/local/lib/X11/app-defaults
>   'groff -l' uses print spooler    : lpr
>   use URW fonts for PDF output     : yes
>   URW fonts directory              : /usr/share/fonts/type1/gsfonts/
>   preconv can use uchardet library : yes
>   can build groff.dvi, groff.pdf   : yes
>   tests can use poppler PDF tools  : yes
> ----------------------------------------------------------------------
>
> In groff 1.22.4, we didn't report as much information--not even the
> identity of the C++ compiler, even though far more of groff is in C++
> than C.

I have a feeling that the build system for groff is way too complicated (not as 
much as libc, but still quite complex).  I guess it's due to it supporting all 
kinds of Unix systems, and not only GNU/Linux.

I don't have auto**** experience to dig through it when I have issues and fix or 
even understand issues when I face them.

I wish it could be chopped off to a tiny amount of code of what it is, but 
probably it's not that easy.

> Let me know your thoughts.
>
> Regards,
> Branden
>
> [1] I remember well the arrogance with which Red Hat Linux partisans
>      (and staff) handled its market position in the late 1990s and early
>      2000s.  Even Debian founder Ian Murdock wanted to throw up his hands
>      and "standardize" on the repellent RPM package format[2], I think in
>      part due to the Linux Standard Base canonizing it--but then Ubuntu
>      came along and put a million free CD-ROMs into the hands of the
>      people, abruptly arresting Red Hat's play for supremacy.  They
>      didn't give up much in the long term--systemd was a much more
>      successful play for domination of the GNU/Linux ecosystem.  The real
>      "Freedom Zero" is to eat what you're fed, or starve, no?

Yeah, I have a Devuan system around for opposing systemd, which for packaged 
stuff works quite nicely.  But when I build something from source, I tend to do 
it in Debian, since software these days only documents using it with systemd, 
and it's a nightmare to make some things work without it.

I can certainly feel when you're not using mainstream software/configurations 
and documentation just sucks.  Which is BTW why I tend to have few dotfiles around.

> [2] This was, however, years after he'd vacated the project leadership
>      role, and my assessment of the sentiment of the Debian Project at
>      the time was that the sentiment of its developers was strongly
>      against such a disruption.

Cheers,

Alex



[1]: (pissed off)

Okay, here we go for a rant.

Let's say there's some software with cowboy programmers, which has things like:

    typedef struct {
        size_t  length;
        u_char  *start;
    } str_t;

    #define length(s)   (sizeof(s) - 1)

    #define str_set(str, text)  do       \
    {                                    \
        (str)->length = length(test);    \
        (str)->start = (u_char *) text;  \
    }

(Of course, cowboy programmers don't need terminating NUL bytes, that's for 
newbies, but that's not today's rant.)

And the use of that macro is typically for things like:

    str_t  str = str_set("foo");

The same software uses the ternary operator extensively (and that's fine to me; 
it makes some things much more readable), so you can find it all around the code.

And then some new programmer in the team writes a line of code that's something 
like:

    str = str_set(cond ? "someword" : "another");

Okay, it looks reasonable.  The ternary operator is common enough in the project 
to be used to it, that macro is also used in many places so you guess it's also 
fine; okay.  It passes 3 different reviewers and looks good (and it's not even 
the main point of the patch; it's just a random line).

Then testing reveals some issue if cond is true.  You see only "somewor"; hmm. 
You start suspecting.  The author of the patch decides to completely rewrite 
that line even if the bug is not really understood, and it just works after it.

I then investigate that line again, and being told it has a bug, but that the 
bug is not known, I quickly realize that it is due to the ternary operator 
decaying the array into a pointer and sizeof later doing shit.  Coincidentally, 
I had been doing something related to detecting pointers in macros the week 
before, for a stackoverflow answer: <https://stackoverflow.com/a/72983424>.

And so I write a patch to prevent that stuff from happening again, considering 
that it passed review from me and two others, and none realized about the bug 
just by reading the code.  Especially, since I had done an extensive 
investigation a few years ago about this topic: 
<https://stackoverflow.com/a/57537491>.

My patch just changes

    #define length(s)   (sizeof(s) - 1)

to:

    #define length(s)   (nitems(s) - 1)

(nitems() is defined to be the obvious sizeof division (called ARRAY_SIZE(9) in 
the Linux kernel), and I didn't even have to add it, since it already existed in 
the project.)

And by doing such a change (with a single reviewer that approved it, of course), 
some old developer (which happens to be one of the reviewers that happened to be 
reviewing the patch that almost introduced a bug and didn't catch the bug) 
complains that I'm touching sacred code written by god, and I am blaspheming by 
insinuating that it was unsafe code.

Then I need to defend my one-line patch (I already defended it in the commit 
message with a somewhat extended explanation, including a dissection of the bug 
that would have been prevented by a compiler warning) 2 times with what would 
will more than what I would write in two hypothetical manual pages about 
sizeof() and the ternary operator.  Just imagine around 10 terminal pages of 
rationale for that change.  And then 3 meetings with different people.  And so 
we decide to bring this issue to one of the oldest programmers in the group. 
Then things go as follows.

I get a review that starts by saying that this makes the macro unreadable 
(seriously, wtf?  I mean, the length() name is probably the less useful name 
that could be given to such a macro, and my change is making it unreadable? 
okay, okay).

Then the review continues by saying that the reviewers are so bad that "actually
do allow such trivial bugs to happen".

And goes on to say that it's sad but it's expected of "new developers".

Oh boy, gimme a lace, an I'll go get some cows.

+++

[2]: (missed something in the docs)

I feel about your INSTALL.* (and other files) what I felt about the same 
man-pages files.  RST is not the easiest thing to read.  If you're reading it 
like a book, it might make sense.  If you have technical documentation, which is 
likely to be organized in unrelated sections that you may want to consult 
independently, indentation can play a big difference.

That's why I rewrote the man-pages repo documentation in a man-pages\[en]like 
(:P) document.  I find it much easier now to see the organization of the files 
at a short glance, and look for what you need.

Does it make sense to you?

+++


--
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature