[src/trunk]: src/distrib/sets distrib/sets/fmt-list: document how to sort by ...

[rillig <rillig%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/8b14cac98a6b
branches:  trunk
changeset: 980721:8b14cac98a6b
user:      rillig <rillig%NetBSD.org@localhost>
date:      Mon Feb 15 23:46:46 2021 +0000

description:
distrib/sets/fmt-list: document how to sort by directory first

In lists/base/mi, the directory ./libdata/firmware contains several
subdirectories for which the entries do not look aligned right now, even
after normalizing the alignment.

This is because the indentation for a directory is not determined
globally for all directory entries from the complete file, but instead
for each group of items, after sorting, that have the same directory.
This results in several entries having only a single item per group,
such as ./libdata/firmware/nouveau, and this single item is obviously
consistently indented since all of its 1 lines are already indented to
the same depth.

One possible solution for this is to sort the entries in another order,
keeping all entries from a directory together.  This allows to quickly
see all entries from a certain directory, but on the other hand, when
adding a new directory plus some entries, the directory has to be listed
far away from its entries.  (This would be done automatically by
fmt-list though, which weakens this argument a bit.)

Another possible solution for this is to first determine the indentation
for all entries from each directory, no matter how far these entries are
apart, and then indent these entries to the common indentation.  This
may or may not help since there will still be single entries between
groups of differently indented entries.

Writing down the intuitive rules for how to align the entries properly
is a nontrivial task.  See pkglint/varalignblock, which is around 650
lines of code, plus around 4000 lines of test code.

No functional change.

diffstat:

 distrib/sets/fmt-list |  9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)

diffs (26 lines):

diff -r 47204cfdfbcc -r 8b14cac98a6b distrib/sets/fmt-list
--- a/distrib/sets/fmt-list     Mon Feb 15 23:27:03 2021 +0000
+++ b/distrib/sets/fmt-list     Mon Feb 15 23:46:46 2021 +0000
@@ -1,5 +1,5 @@
 #! /usr/bin/lua
--- $NetBSD: fmt-list,v 1.4 2021/02/15 23:00:03 rillig Exp $
+-- $NetBSD: fmt-list,v 1.5 2021/02/15 23:46:46 rillig Exp $
 
 --[[
 
@@ -337,8 +337,15 @@
 
   local function less(a, b)
     if a.fullname ~= b.fullname then
+      -- To sort by directory first, comment out the following line.
       return a.fullname < b.fullname
     end
+    if a.dirname ~= b.dirname then
+      return a.dirname < b.dirname
+    end
+    if a.basename ~= b.basename then
+      return a.basename < b.basename
+    end
     if a.category ~= nil and b.category ~= nil and a.category ~= b.category then
       return a.category < b.category
     end