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

docs: Latex generation improvements #18141

Merged
merged 3 commits into from
Jun 1, 2021
Merged

Conversation

a-mr
Copy link
Contributor

@a-mr a-mr commented May 31, 2021

Follow-up to #17997 (and discussion timotheecour#727).

A few improvements, mostly stylistic ones to Latex doc generation:

  • Support unicode using XeLatex engine. Hence generated .tex need to be compiled by xelatex, not pdflatex, as before. (It's still far from browser level: it uses a fixed font that should contain all required symbol. I only checked that Russian and Greek work and also contributing.rst/docstyle.rst which contain unicode examples in comments start to compile. Switching between different fonts is a more complex task in Latex, i did not try to achieve it here)
  • turned on restrictive policy on margin overflows, see example 2 below (it can make formatting sub-optimal but it's important to automatically get rid off any margin overflows in doc generation as discussed in doc2tex: generate docs to Latex #17997)
  • turn on automatic line breaking in code blocks (Using package fvextra instead of fancyvrb). Draw frames around code blocks. See Example 4.
  • underline inline code. Small fixes: double minus displays as -- in code, not as en-dash.
  • tables: automatic column width selection with better prevention of overflows. (Using tabulary package). Also table is not floating anymore (because floating without references can be very confusing like in Example 1, but we don't currently generate refs).
  • Fixed:
    1. multiline string literal were not line-broken before
    2. more fixes with escaping: I realized that there is no universal escaping in Latex, some characters needs special escaping in different contexts
    3. in some cases paragraphs were not created because of no 2 \n (e.g. Example 3).
  • some purely stylistic things
    1. don't indent paragraphs, just separate them with vertical space, like in HTML. This style is better suited when there are large amounts of code blocks IMHO.
    2. Switch to GoMono as default mono space font (better than antique courier IMHO)
    3. draw frames around doc.items in doc2tex and make additional indentation for items descriptions. See Example 3.
    4. some additional syntax highlighting (grey shades currently)
    5. no huge frames around links, just underlines (visible in pdf only)
    6. Add spacing around horizontal lines (transitions)

Tested with TexLive 2018 and Miktex 20.12. I expect that this will be incompatible with old versions of Latex, something around TexLive 2016 is probably required.

Example 1.

before

image

after

image

Example 2.

before

image

after

image

Example 3

before

image

after

image

Example 4

before

image

after

image

cc @timotheecour @narimiran

@a-mr a-mr changed the title dogs: Latex generation improvements docs: Latex generation improvements May 31, 2021
@Araq
Copy link
Member

Araq commented Jun 1, 2021

Notes to myself:

  • Escaping in Latex is so complex that the generator needs special escMode: EscapeMode logic.
  • The much better "xelatex" needs to be called up to 3 times to get labels generated.

No further questions -- but I noticed that I'm always right.

@Araq Araq merged commit ba3ec7b into nim-lang:devel Jun 1, 2021
PMunch pushed a commit to PMunch/Nim that referenced this pull request Mar 28, 2022
* docs: improve Latex generation

* make it work on Windows + fix ] escaping

* minor fixes with escapes and style
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants