Improve the documentation of \babelposthyphenation

[ghost]

The documentation of \babelposthyphenation in both babel.pdf and https://latex3.github.io/babel/guides/non-standard-hyphenation-with-luatex.html should be improved IMHO. I see the following issues with it.

1. The command is documented by examples rather than by more abstract, more high-level description. Therefore, I don't understand certain aspects. For starters, what is the semantics of no = … in high-level terms?

2. The two documents use the term “discretionary” or “disc”. IMHO, this is a low-level concept. Probably, the typesetter should not see this term at all unless he/she is into luatex development. If the command \babelposthyphenation should not be used by a typesetter but rather by a developer, this should be clearly stated.

3. The documentation structure in https://latex3.github.io/babel/guides/non-standard-hyphenation-with-luatex.html should be improved. As of now, we see some text right after the title “Non-standard hyphenation with luatex”, a section called “Rules“, and a section called “Short examples”. The text right after the title is giving a short example, which has been mostly unintelligible to me for quite a while. The text following “Rules” is NOT giving a list of rules; we even don't see what a “rule“ is supposed to be (all we know is that “a set of hyphenation rules” is a “\language”). I suggest that instead, one or two paragraphs directly following the title shortly introduce the command in high-level terms rather than by an example (since the usage is way too versatile, and the example in the introduction is way too specific). After the introduction, a syntactic synopsis of the command should to be given. After that, the parts of the syntax should be explained in high-level terms. Finally (and/or after each part of the syntax), examples should be given.

   A relatively good (but by no means unique or unimprovable) example of a structure is given by a man page of a GNU tool (e.g., grep); perhaps you could adapt their structure (e.g., COMMAND NAME, SYNOPSIS, DESCRIPTION, FIRST ARGUMENT, SECOND ARGUMENT, THIRD ARGUMENT, PATTERNS, …, LOG OUTPUT, ENVIRONMENT (other global stuff such as macros/lengths/dimensions/… controlling the execution of the command), NOTES, BUGS, EXAMPLES, SEE ALSO). While writing, clearly distinguish between syntax, semantics (in high-level terms), and usage examples. Any implementation details of the command in low-level terms would, on the contrary, be counterproductive; always choose a high-level description whenever possible (because the implementation can change), and if there is no high-level description of a feature in user-level terms, it should be clearly marked as an “internal” feature, i.e., subject to change/removal and not to be used by typesetters.

As it turned out that I don't really understand \babelposthyphenation (cf., e.g., https://chat.stackexchange.com/transcript/message/63242636#63242636 or http://tex.stackexchange.com/questions/680690), I have a difficulty of providing you with better insights of how exactly to write a documentation of this command. This report is NOT intended to be read as a complaint – I greatly apologize for not being able to offer more help.

[jbezos]

Complaints are fine, of course 🙂. Discretionaries are actually explained in many sources, and they are not low level, but admittedly a little explanation or a link can be useful.

With relation to the issues you are experiencing, discretionaries have several subtypes (which are certainly low level) and maybe I didn't choose the most convenient one. I’ll investigate if it should be considered a bug or just an unfortunate decision, and how to fix it.

[ghost]

@jbezos Thank you a lot for a fast response! As for this very issue report, let us not overcomplicate things — I would appreciate it if you would now look only into the documentation. In my opinion, the lack of good structure is the main issue (other issues follow from it), so a complete rewrite from scratch is necessary.

As every documentation, this documentation should be able to stand for itself, i.e., be a plain English description of the interface of the command, regardless of the presence (let alone the quality) of an implementation. You might consider asking Werner L. and David C. to get more improvement suggestions (after all, I might be simply wrong or having a bad day).

(As for the implementation, strictly speaking, I cannot vouch for it being correct or faulty (as I originally thought in http://tex.stackexchange.com/questions/680690) before I know the interface.)

[jbezos]

I’ve revised the article, added pointers and provided more realistic examples. This guide is more a ‘report’ than a ‘man(ual)’, and I’m not sure the structure of the GNU tools is the best option. At least, I’ve usually found them somewhat terse and unfriendly. This doesn’t mean I won’t introduce further improvements in the future.

[ghost]

@jbezos Thanks! I saw you have worked on the documentation; great! (As I said, the manpages of the GNU tools are by no means … unimprovable, and blindly copying them or their structure would not work anyway, as you rightfully noticed. In my remark, these manpages served to demonstrate the existence of a clear structure.) The first issue in your updated documentation is the introductory example. “Here is a simple example of a declaration, […] . It consists of:” followed by a list of three items is unclear and potentially misleading. What is it that consists of three items: the example or a (any?) declaration? Whichever it may be, name it. For example, write “The example consists” or “A declaration consists”. After that, we read a vertical list of thee items. However, in your example, I don't see three but four items: \babelposthyphenation, {german}, {ck}, and {{ no = c, pre = k- }, {}} (broken into several lines, which may or may not matter). So you probably wish to say exactly this. For instance:

As demonstrated by the above example, a hyphenation adjustment is a declaration consisting of four items:

• the command name (in this example, this command name is \babelposthyphenation);
• its first argument (in this example, german);
• its second argument (in this example, ck);
• its third argument (in this example, the list { no = c, pre = k- }, {}).

Each argument is enclosed into a pair of braces.

The three arguments are expected to have the following syntax:

1. …
2. The second argument is a pattern (here, just the string “ck” occurring verbatim in the input document in the scope of the aforementioned language).
3. The third argument is a list of items of the same length as the pattern. Each such item is … .

The three arguments have the following semantics:

1. The first argument is the language the transformation should apply to (here, it denotes the pre-1996 German language).
2. The second argument means … .
3. The third argument means … .

Of course, insert suitable text instead of the horizontal ellipses. I don't know what exactly to write there because I don't quite understand this (what is a pattern?). Moreover, take my suggestion above with a grain of salt: this is just my (hopefully successful) guess.

Naturally, this suggestion is valid only if you wish to keep this introductory example at all. It's not necessary to do this because you'd find yourself in the need to explain the arguments in great detail. An alternative is to drop the example completely.

Thanks once again, and I hope this helps.