Enable tikz docstrings

[JensAc]

Hi Augusto,

I merged your old script with your newer one, and generated tag files for tikz and pgf. These are definitely not perfect. Yet, I think the docstrings could help, and experienced LaTeX users would be able to read them easily. Most probably you haven't been happy with a similar result in the past. However, you might want to have a look at this PR. I won't be disappointed, if you don't want to merge, but as I a already expected: it would consume too much time to get something perfect....at least for me.

[astoff]

Yeah, I think this doesn't look too bad, in fact. I have some further requests:

• I see stuff like See Sections [\[section-cross-pictures-pgf\]][1] and [\[section-cross-picture-tikz\]][2] for more details.. What do you think of replacing \ref{whatever} by ?? before passing to Pandoc? (PS: Even better: redefine the \ref macro).

• I've also seen some stray   in the Pandoc output. Can you check why this happens, and remove them manually as a last resort?

• In the comments section of the data file, add the version number after Extracted from the PGF manual. Also, I think it's ideal to use the last stable release here, just to make this more reproducible

• Make it so that cross references look like "$ref:pgf#/keys/pgf" instead of "$DIGESTIFDATA/pgf/keys/pgf"

• Make it so that documentation links look like "texmf/doc/generic/pgf/pgfmanual.pdf#pgf.%3CCS%3Epgfalternateextension" instead of "texdoc:generic/pgf/pgfmanual.pdf#pgf.%3CCS%3Epgfalternateextension".

• Check that those pgfmanual.pdf#something hyperlinks still work (at least on firefox, you can type the fragments in the address bar or inspect by hovering the mouse). I think they are fine for keys, but for commands they changed from pgfmanual.pdf#pgf.<CS>pgfalternateextension to something like pgfmanual.pdf#pgf.back/pgfalternateextension.

• Use the function inspect from digestif.util instead of the luarocks function to generate the Lua files.

Okay, that was quite a lot... I hope you get the chance to try this some time. Thanks!

[astoff]

There's also the case of the path commands (\draw, \fill, etc.), which are heavily used but don't have a super enlightening docstring.

What do you think of copying the doctring of the corresponding key? This can be done by setting, for instance, commands.draw.details to "$ref:tikz#/keys/tikz/draw/details".

[JensAc]

Alright...Actually, I did not notice that there are issues with the links, as my starting point was the script on master. Seems like you have used another version of it for generating the tags files. I am on it, and will try to push commits related to your requests.

[astoff]

I think I modified tikz.tags and pgf.tags by hand when I changed my mind about some details of the tags file format, so these things are reflected in the script. But I promise I'll only used the script to update the data files in the future :-)

[JensAc]

So, I do not really get the points of the last two bullets. I feel like I am not using any inspect function.

There's also the case of the path commands (\draw, \fill, etc.), which are heavily used but don't have a super enlightening docstring. What do you think of copying the doctring of the corresponding key? This can be done by setting, for instance, commands.draw.details to "$ref:tikz#/keys/tikz/draw/details".

IMHO this would be missleading. If the docstring for the key is needed, one can check either the PDF or simply add another line to the LaTeX code, which calls the command including the key.

[astoff]

Hi Jens, I have a few modifications to suggest. Can you enable the option allow edits from maintainers?

[astoff]

Okay, I managed to push to your branch.

IMHO this would be missleading. If the docstring for the key is needed, one can check either the PDF or simply add another line to the LaTeX code, which calls the command including the key.

I've added this in such a way that the user sees the command short summary, and the long documentation from the key. Hopefully it's not confusing.

So I'll let you take a look if you agree with this and other changes, and then I'll merge.

[JensAc]

Looks fine for me. Thanks for your feedback. I am not really sure, whether we should really clean the command.details here, as a newline might make it a little bit more readable. However, that is only a minor (and pedantic) comment ;-).

[JensAc]

And...actually I set the pandoc output to plain on purpose, since this was removing the   lines in the tags file. For me the output appeared to be clean and formatted correctly with plain output instead of markdown_strict

[astoff]

I am not really sure, whether we should really clean the command.details here, as a newline might make it a little bit more readable.

The cleaning is for the summary, right? The summary field is supposed to be a single line. We can change the formatting of the Eldoc buffer if you have any suggestions.

And...actually I set the pandoc output to plain on purpose, since this was removing the   lines in the tags file. For me the output appeared to be clean and formatted correctly with plain output instead of markdown_strict

You said are using Eglot – do you have markdown-mode installed as well? In this case the backticks will disappear and become colors.

So I'll merge this now. Future improvements are always welcome.

Thanks!

[JensAc]

Alright, I am totally fine, with the current state! If I find any improvements during usage, I will file another PR.