How to renew an internal function written with \cs_new_protected:Npn? - TeX

TopAnswers TeX

Top Answer

Joseph Wright

At the code level, the split is not `new`/`renew` but rather `new`/`(g)set`. This is because most code that needs to `set` a function will be in a relatively 'tight' situation, where checking is not desirable. We also need to have a  way to define functions which have indeterminate status. So you want either `\cs_set_protected:Npn` (local to the current group level) or `\cs_gset_protected:Npn` (global).

Note that internal functions are exactly that. If you need a (long term) change to an `expl3` internal function, either in the kernel or a third-party package, please initiate a discussion about a suitable interface.

I'm not sure of your issue with `\cs_undefine:N` without an example.

With the `macro` environment in the implementation, currently `l3doc` prints "End definition for `\foo`", which I think is an awkward construction. I wanted to change it to "The definition for `\foo` ends here". I managed to do it with the code I have posted above, but as it tinkers with an internal macro (which as you correctly warn might just go away in the coming versions) I added a date so that at least the future users don't get an undefined control sequence in case it vanishes. Another reason for doing the date-conditional is because I am hoping that it [gets resolved](https://github.com/latex3/latex3/issues/1140) in the future versions.

Sorry, but can you explain a bit more on this? I have kept the true branch of the `\@ifclasslater` blank to do absolutely nothing. If my code is supposed to do nothing with newer versions of the class why do you think it will still have to change?

It looks fine to me, and it's worth noting that `l3doc` is a bit of a special case (it's been built up over many years and is not really 'model' `expl3` code). The main thing to remember is that you might have to change your code as development occurs.

What about this? ``` \@ifclasslater{l3doc}{2022-01-12}{}{ \cs_set_protected:Npn \__codedoc_print_end_definition: { \seq_set_map:NNn \l__codedoc_tmpa_seq \g__codedoc_nested_names_seq { \__codedoc_macro_end_wrap_item:n {##1} } The~definition~for~ \int_compare:nTF { \seq_count:N \l__codedoc_tmpa_seq <= 3 }{ \seq_use:Nnnn \l__codedoc_tmpa_seq { \,~and~ } { \,,~ } { \,,~and~ } } { \seq_item:Nn \l__codedoc_tmpa_seq {1}\,~and~others }~ends~here\@.\__codedoc_print_documented: } } ```

Joseph is quite right. One major obstacle in improving or correcting packages are other packages which messed around with internals instead of asking for a proper interface. Patching and redefining internal commands is cheap and fast at first, but the long time cost of maintenance are high.

The idea of different layers implies from the word go that 'user' and 'programmer' approaches are separate. Those can be the same person, but it's important to understand that something like a document command and something like a code-level API are different.

Most more modern languages work exactly this way: local functions are not even 'visible' from outside of their scope. TeX doesn't work like that, so we can only ever appeal to conventions. So users _can_ modify internals, but as an `expl3` developer I have clarity from the word go about the fact that 'this might break'. Conversely, I also know that something like `\siunitx_compound_number:n` in `siunitx` _is_ a documented API so I can't change it (at least without stepping major version number and providing a migration path).

It's based on 30+ years of experience with LaTeX2e. Without a clear idea of what can be relied upon and what is internal, people (mainly package authors rather than end users) have (understandably) patched/relied on almost all of the kernel commands. That makes changing anything very challenging, to the point where in many places it becomes impossible.

Maybe I am too naïve to talk about this, but at the first look I find this very restrictive and orthogonal to what I have experienced so far as an end user. I feel an authoritative bias for developers here and I also feel that this approach kinda undermines end users by perceiving them as people who should just keep using things that are given to them without thinking or tampering with them. Sorry, I don't intend to sound harsh. There might be advantages of this method too, but on the first look at least I didn't find it impressive.

But that's the point: they are internal to the package that defines them. _Inside_ such a package, the programmer is free to do whatever. Look for example at `siunitx`: I have user docs, programmer docs describing the public API then 100s of internal functions. None of the latter should be used by anyone else: if there is a need for a new programmer API or user command, people can make a request and I do my best to incorporate them.

Internal commands are not documented or in any way 'reliable': in particular, we know that `l3doc` needs extensively re-working, so it's quite likely this will vanish at some point. Be ready to have to change your code

PS2: For the time being I just removed `\cs_undefine:N` and added the following (in the preamble), which produces the text that I expect. Do you think there are any potential risks in doing this? ``` \cs_set_protected:Npn \__codedoc_print_end_definition: { \seq_set_map:NNn \l__codedoc_tmpa_seq \g__codedoc_nested_names_seq { \__codedoc_macro_end_wrap_item:n {##1} } The~definition~for~ \int_compare:nTF { \seq_count:N \l__codedoc_tmpa_seq <= 3 }{ \seq_use:Nnnn \l__codedoc_tmpa_seq { \,~and~ } { \,,~ } { \,,~and~ } } { \seq_item:Nn \l__codedoc_tmpa_seq {1}\,~and~others }~ends~here\@.\__codedoc_print_documented: } ```

Regarding `\cs_undefine:N`, I just wanted to tweak the text that is printed by `l3doc` with macro `\__codedoc_print_end_definition` at the end of each macro and hence I was trying to experiment with it. I used `\cs_undefine:N` in the following way which didn't work for me. I would be very happy if you could explain why it didn't. ``` \cs_undefine:N \__codedoc_print_end_definition \cs_new_protected:Npn \__codedoc_print_end_definition: { \seq_set_map:NNn \l__codedoc_tmpa_seq \g__codedoc_nested_names_seq { \__codedoc_macro_end_wrap_item:n {##1} } The~definition~for~ \int_compare:nTF { \seq_count:N \l__codedoc_tmpa_seq <= 3 }{ \seq_use:Nnnn \l__codedoc_tmpa_seq { \,~and~ } { \,,~ } { \,,~and~ } } { \seq_item:Nn \l__codedoc_tmpa_seq {1}\,~and~others }~ends~here\@.\__codedoc_print_documented: } ```

I am not very familiar with the philosophy of `expl3`, so I don't think I can suggest any new long term function, but as many 2e users at some point encounter the code written with `expl3`, maybe it would be great if the `interface3` just documents the way of changing/renewing the existing definitions and I would be very happy if the word 'renew' is used, since most of the users who are used to using new/renew pair will search for it.

1 Answer