Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve parsing of tex strings #52

Merged
merged 2 commits into from
Oct 25, 2023
Merged

Improve parsing of tex strings #52

merged 2 commits into from
Oct 25, 2023

Conversation

goerz
Copy link
Member

@goerz goerz commented Oct 23, 2023

Implements a proper (albeit limited) single-pass parser for the subset of tex syntax that occurs in BibTeX fields, converting to the equivalent Markdown. Most importantly, this handles accents like \"o, and groupings, i.e., it removes curly braces in the same way that LaTeX does.

Inline math is recognized and translated into Documenter's preferred "``" syntax, but otherwise is left alone.

A limited set of LaTeX commands is recognized, most notably \href and \url, allowing to put hyperlinks in the @note field of a reference. We're deliberately conservative here. Anyone who can demonstrate the need for additional commands should submit an issue with a real-life example. It should be quite trivial to add any specific additional command.

All of this is considered "very internal". We're not making any promises. Ideally, a lot of this code would probably be better off in Bibliography.jl, but at this point, we're treating Bibliography as just a basic parser to get the raw tex, and doing all the processing / conversion to Markdown ourselves.

Closes #15.

Should also address #44, except that the lack of a new BibInternal release still requires the workaround of using non-breaking spaces.

@goerz goerz added the enhancement New feature or request label Oct 23, 2023
Implements a proper (albeit limited) parser for the subset of tex syntax
that occurs in BibTeX fields, converting to the equivalent Markdown.
Most importantly, this handles accents like \"o, and groupings, i.e., it
removes curly braces in the same way that LaTeX does.

Inline math is recognized and translated into Documenter's preferred
"``" syntax, but otherwise left alone.

A limited set of LaTeX commands is recognized, most notably \href and
\url, allowing to put hyperlinks in the `@note` field of a reference.
We're deliberately conservative here. Anyone who can demonstrate the
need for additional commands should submit an issue with a real-life
example. It should be quite trivial to add any specific additional
command.

All of this is considered "very internal". We're not making any
promises. Ideally, a lot of this code would probably be better in
Bibliography.jl, but at this point, we're treating Bibliography as a
just a basic parser to get the raw tex, and doing all the processing /
conversion to Markdown ourselves.
@goerz
Copy link
Member Author

goerz commented Oct 24, 2023

The \url/\href support probably shouldn't be overused, but the rendering of links as in GoerzPhd2015 can be pretty neat, from the following .bib entry:

@phdthesis{GoerzPhd2015,
Author = {Goerz, Michael},
Title = {Optimizing Robust Quantum Gates in Open Quantum Systems},
School = {Universität Kassel},
url = {https://kobra.uni-kassel.de/handle/123456789/2015052748381},
Year = {2015},
note = {See \url{https://michaelgoerz.net} for additional formats. Source available on \href{https://github.com/goerz/dissertation}{Github}},
}

@goerz
Copy link
Member Author

goerz commented Oct 24, 2023

@kellertuer @Seelengrab @lgoettgens Can you have a look?

Are there any specific LaTeX commands that you would like me to add support for?

This should be the last PR that goes into the 1.3 release. It should also make DocumenterCitations pretty feature-complete, as far as I'm concerned. Thus, after the 1.3 release, I'd wait a while to see if anything comes up from the plugin being used in the wild, and then at some point release 1.4 that declares the documented Internals as "stable", as discussed in #43 (comment).

@kellertuer
Copy link
Contributor

I am fine with the current state of rendering I think.

@Seelengrab
Copy link
Contributor

Anyone who can demonstrate the need for additional commands should submit an issue with a real-life example. It should be quite trivial to add any specific additional command.

I was wondering whether supporting urldate would be ok? It's not technically bibtex if I'm not mistaken, but does give online ressources a better anchor.

Other than that, I'm very happy already with the current state, so nothing for me to add either :)

@goerz
Copy link
Member Author

goerz commented Oct 24, 2023

I was wondering whether supporting urldate would be ok?

Can you open a separate issue for that, preferably with an example BibTeX entry, and how it should render?

@goerz goerz mentioned this pull request Oct 24, 2023
@goerz
Copy link
Member Author

goerz commented Oct 24, 2023

@Seelengrab Opened #53, we can discuss urldate there.

@goerz goerz merged commit 975a5a2 into master Oct 25, 2023
8 checks passed
@goerz goerz deleted the mg/15-latexstrings branch October 25, 2023 02:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Curly braces in bibtex Fields
3 participants