Help on autogeneration of cwl files for own/custom packages

TXS - Help
  • Otto Debals

    Otto Debals - 2014-01-23


    I've a couple of questions about how the autogeneration of the cwl (completion) files for unknown packages within TXS works, as we are working on the creation of our own packages.

    I have understood that TXS autogenerates a cwl file if a package is unknown.

    (1) For me, it does this by introducing every command from the sty file into the cwl file, with an additional '#S' notation, standing for 'Do not show in completer at all'. If this is the default annotation of new commands in a cwl file, what's the point of the autogeneration after all? Why is this added to the commands by default?

    (2) Further on, is it possible to add documentation to the sty file, which is afterwards extracted by the autogenerator to choose the type of completion classifier automatically? For example, introduce a new \tensor command and annotate it with a math label.

    (3) As said, we are developing our own packages, and if (2) would not work, it would be useful to provide the cwl file with the sty file. The development happens with GIT version control. However, the cwl file needs to be in the correct completion TXS folder for it to work. Is it possible for TXS to search for cwl files in other directories? In this way, I could set up a GIT directory in the local tex tree with the installed sty file.

    Kind regards, thanks for the help, and thanks for providing this wonderful TXS,


  • Tim Hoffmann

    Tim Hoffmann - 2014-01-23

    @(1) The commands in cwl files are also used by the syntaxchecker, if a command is known or not. This was also the primary reason to introduce the autogeneration. Otherwise you might have lots of commands marked as unknown if you use less common packages. I think using #S was chosen as minimal setting but that was before my time. IMO the marker * 'unusual command which is used for completion only in with the "all" tab' would also be ok, maybe better. Without any marker, the commands would flood the "typical" completer tab.

    The autogenerated cwls are just a fall back. We recommend manually adapting them and adding the classifiers according to the cwl documentation. This logical information cannot be obtained by an automated parser. You can send us such tuned cwls and we will include them in the next relase.

    @(2) There is currently no annotation language or the likes. Basically, the target group is too small. It would only aim at package authors who are willing to directly add support for TXS-enhancements in their packages. Almost as good you can simply write the cwl directly. After all, the commands in a package are not likely to change very often.

    Moreover, I wouldn't want to bind the current state of the cwl format to an official API. It was a good thing to start with, but it has a few limitations, and therefore may change in the future.

    @(3) The cwl search path is fixed, but I plan to make it more flexible in the future. As a temporary workaround you could create a link in the settings directory and point it to the cwl in your git repository.

  • Otto Debals

    Otto Debals - 2014-01-23

    @(1) Marker * as default would indeed be useful then. Thanks for the information about how TXS checks whether a command is known, I didn't know this comes from the cwl file.

    @(2) True about the target group, just wanted to check whether the functionality existed and if I missed something. I'll work with the cwl file directly then, or maybe a personal simple bash file could do the trick.

    @(3) I'm working on Windows, so no symbolic linking available. I'm guessing it doesn't work with shortcuts.

    Thanks !

    • Tim Hoffmann

      Tim Hoffmann - 2014-01-28

      I'm working on Windows, so no symbolic linking available. I'm guessing it doesn't work with shortcuts.

      There are symbolic links on windows:


Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks