bug-groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[bug #66096] document behavior of multiple .hw calls


From: G. Branden Robinson
Subject: [bug #66096] document behavior of multiple .hw calls
Date: Fri, 16 Aug 2024 08:01:18 -0400 (EDT)

Update of bug #66096 (group groff):

                 Summary: Document behavior of multiple .hw calls => document
behavior of multiple .hw calls

    _______________________________________________________

Follow-up Comment #1:

[comment #0 original submission:]
> One of the changes
[http://git.savannah.gnu.org/cgit/groff.git/commit/?id=d15c86d95 commit
d15c86d95] made to the documentation of the .hw request was:

>    * Drop observation that the request can be used more than once; nearly
>      all can (cf. `ex`, `ab`).


> I agree this observation, on its own, was of little import.
> 
> However, .hw is different from most roff requests in that it updates an
internal database.  For most requests, the effect of using them more than once
is either documented or obvious.  But a user might reasonably wonder whether
multiple uses of .hw overwrite or append to its database.
> 
> I had always read "this request can be used more than once" as indicating
the latter, even though the actual wording does not explicitly say this.  But
the latter is the case, as this example illustrates:

> .de aa
> supercilious orangutan
> .sp
> ..
> .ll 1n
> .aa                 \" default hyphenation of both words
> .hw sup-erc-ili-ous
> .aa                 \" custom hyphenation of first word
> .hw ora-ngu-tan
> .aa                 \" custom hyphenation of second--and first?--word


> So the documentation should point this out.
> 
> (CSTR#54 also did not specify this, although I presume it is true of AT&T
troff as well.  The above example's post-.hw output is the same in Heirloom
troff as in groff, though they break both words differently by default.)

Well...

Like a lot of things with names inside GNU _troff_, hyphenation exception
words are stored in a dictionary.  Specifically, they resemble registers and
strings/macros/diversions in this respect.  A dictionary, as is better known
since Python became popular, is a data structure that associates a unique
"key" with some "value".[1]

The difference is that when you define a hyphenation exception word, what
you're defining it _as_ is not explicit in the same way.  The way you spell
the word (any hyphens in it?) is what defines the key's value; it's more or
less just a numeric list of offsets into the word at which hyphenation breaks
can occur (and this list can be empty, preventing hyphenation).

Now, you can't alias or rename hyphenation exception words.  Nor can you
remove them, though [https://savannah.gnu.org/bugs/?64478 I aim to change
that] and haven't ruled it out for _groff_ 1.24 yet since it _seems_ like it
should be easy.

So whatever new language arises here, I'd like to leverage the user's existing
or developing experience with the register and string concepts.  GNU _troff_
maintains several lookup tables, and the hyphenation exception words are one
of them.  (And, to be honest, if multiple environments are in use, potentially
*several* of them.)

Also I will quibble with your summary; "multiple .hw calls" are entirely
isomorphic to invoking the `hw` request with multiple arguments.

So...how to get the most salient points into the learner's brain?

[1] (an opinionated note on pedagogy)  Of course "dictionaries" existed long
before and in several other languages.  I think Python did the field a service
with its choice of terms here, popularizing the concept to the general benefit
of software practice.  (Doing everything by arbitrary integer lookup: yuck.)

Perl of course had "hashes" well before Python became popular, but that term
was a mis-step, I think, because it focussed attention--needlessly--on the
mathematics of hash computation, which are nearly always going to be entirely
irrelevant to the user of the data structure.  "Map" is a good term for
mathematicians, but not as illuminating for others.

Java of course eagerly embraced the worst of both worlds to attract advocates
in the buzzword set, yielding "HashMap".

Even earlier, C had "libdb", popularized in a major way by Berkeley, but they
defeated themselves (and potential users) a little bit with the heaviness of
the implicit term "database", which suggested big-time, resource-hungry
software, and, with the relational database revolution underway at about the
same time, served to confuse more than it illuminated, to the point that (with
a bit of preening self-promotion, of course) people acted like they were doing
something revolutionary when they implemented an in-memory key-value store
like memcached. 

Meanwhile a "dictionary" is a commonly understood word that gets across the
key/value concept via analogy to the familiar headword and entry.

I have my critiques of Python but its consequence of improving programmers'
facility with data structures is not one of them.  If only it had been more
strongly typed... :P


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?66096>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]