Improving natbib.sty.tags

[dr-scsi]

Hi,

I played a little with digestif and updated the file data/natbib.sty.tags. I have no clue about writing tags file, but this seems to work. Only the package options part doesn't work. Can someone give me a hint what I've done wrong? I don't get the option summary when the point is and inside `\usepackage[round]{natbib}`.

Any other comments are welcome as well; I'll prepare a PR then. TIA. natbib.sty.tags.patch

[astoff]

Looks great, thanks!

I have no clue about writing tags file

Nobody has. Now, seriously, it's not documented but I supposed it's not too hard to guess how it works. Some comments:

Lines like this:

 `\citep{jon90}`               => (Jones et al., 1990)

will probably not display as expected for some markdown renderers. How about making it a bulleted list, like this?

* `\citep{jon90}` => (Jones et al., 1990)

Second, the way you repeat the arguments entry of each command is not a big problem, but you could use

  arguments = "$ref:natbib.sty#/commands/cite/arguments"

Only the package options part doesn't work.

I don't think I've implement the logic needed here, but it doesn't hurt to keep the necessary information recorded for future use.

Now, more importantly: Did you write this by yourself of is the text taken from some other source? I ask because it seems important to keep track of the licenses that apply to the various tags files. If you wrote it from scratch and want to add a specific copyright notice and a license of your liking, feel free to do so, following the example of comments at the heading of other tags files. Otherwise, please add a heading referencing the original source and its license.

[dr-scsi]

Looks great, thanks!

Thanks for your comments.

How about making it a bulleted list, like this?

* `\citep{jon90}` => (Jones et al., 1990)

Thanks, I will change this.

Second, the way you repeat the arguments entry of each command is not a big problem, but you could use

  arguments = "$ref:natbib.sty#/commands/cite/arguments"

This as well.

Only the package options part doesn't work.

I don't think I've implement the logic needed here, but it doesn't hurt to keep the necessary information recorded for future use.

Ok. When you look at it, keep in mind that packages can also take key=value's as options.

Now, more importantly: Did you write this by yourself of is the text taken from some other source?

I'd say 99% is taken from natbib manual and adapted by me to make it readable.

Otherwise, please add a heading referencing the original source and its license.

Will do.

While we're at it: Can one specify which argument takes what input? Take for example \defcitealias{key}{text} which takes a bibtex key as the first argument and some literal text as the second. digestif feeds currently both arguments with a bibtex key which looks like this when point is inside the second arg (I hit l to kick in the completion):

[astoff]

While we're at it: Can one specify which argument takes what input? Take for example \defcitealias{key}{text} which takes a bibtex key as the first argument and some literal text as the second.

Not directly. The way completion works for a given command is dictated by its action attribute. There's two options here for defcitealias: either we set action = "bibitem", so it will be handled exactly like the good old \bibitem command (a good first approximation), or we set action = "defcitealias" and then I'll have to add some special logic to handle it in the Lua code.

[dr-scsi]

Not directly. The way completion works for a given command is dictated by its action attribute. There's two options here for defcitealias: either we set action = "bibitem", so it will be handled exactly like the good old \bibitem command (a good first approximation), or we set action = "defcitealias" and then I'll have to add some special logic to handle it in the Lua code.

Ah, I was afraid you would say that. I think this design decision should be reconsidered in order to provide a more fine-grained control over the arguments. I can think of:

• If there is a action attribute top-level for a LaTeX command, then apply it to (all) argument(s), otherwise
• allow action attribute for each argument separately

So something like this:

  defcitealias = {
    arguments = {
      {meta = "key", action = "cite"},
      {meta = "replacement", action = "text"} -- action name TBD
    },
    summary = "Create an alias to a bibliography item."
  }

I'm also attaching the latest version. Please have a look and if Ok, I'll prepare a PR. natbib.sty.tags.patch

[astoff]

I think this design decision should be reconsidered in order to provide a more fine-grained control over the arguments.

What you suggest makes sense from the completion perspective, but there's more than that. When parsing the document, one needs to know which commands define a document element (section, heading, etc.).

The right action for \defcitealias is definitely bibitem, because the comands defines a bibliography item. One could also further annotate the individual arguments, but since there's nothing surprising there (the key is given by the first mandatory argument), I think we don't need to add any extra info.

Please make the PR, I'll make a couple of small suggestion then. Thanks!

[dr-scsi]

What you suggest makes sense from the completion perspective, but there's more than that. When parsing the document, one needs to know which commands define a document element (section, heading, etc.).

Yes, that would have been my next question ;-) I think what you describe is really important from the completion perspective. Take for example new colors defined with \definecolor which will be used in key=val options of other macros.

The right action for \defcitealias is definitely bibitem, because the comands defines a bibliography item. One could also further annotate the individual arguments, but since there's nothing surprising there (the key is given by the first mandatory argument), I think we don't need to add any extra info.

Please make the PR, I'll make a couple of small suggestion then. Thanks!

Done. Please have a look and we can finalize this. TIA.

[astoff]

By the way, there's some documentation of the tags file format here: https://github.com/astoff/digestif/wiki/Tags