misc doc2tex

[timotheecour]

/cc @a-mr

• for decode_helpers.nim, pdflatex gives error on generated tex:

nim doc2tex --outdir:/tmp/d04b --doccmd:skip --warning:LockLevel:off --warning:RedefinitionOfLabel:off --warnings:off lib/std/private/decode_helpers.nim
cd /tmp/d04b
/Library/TeX/texbin/pdflatex decode_helpers.tex
open decode_helpers.pdf

! Missing $ inserted.
<inserted text>
                $
l.36

• in decode_helpers.nim, the _ is not escaped, turning into a subscript:
  in above commands, after pressing ENTER a few times, you get:
  

• a front page (with date) gets generated, which doesn't seem like a good default:

• generated hyperlinks don't work (ie, don't point to correct location), even if the link points to same page:

nim doc2tex --outdir:/tmp/d04 --project --doccmd:skip --warning:LockLevel:off --warning:RedefinitionOfLabel:off --warnings:off lib/std/jsonutils.nim

click on toJsonHook proc:

(it works with nim doc)

• the styling could be improved, in particular, runnableExamples should maybe have a shaded background as for nim doc:

also, in this case, a newline should've been inserted before Example
(example from std/enumutils)

links

• doc2tex: generate docs to Latex nim-lang/Nim#17997

note

for pdflatex, on osx:

• either install mactex via http://www.tug.org/mactex/
  then it's under: /Library/TeX/texbin/pdflatex
• or via brew install mactex (or was it brew cask install mactex ?)
• or via brew install basictex (incompatible with brew mactex: install 1 or the other)
  brew install basictex

(EDIT: with basictex i get: ! LaTeX Error: File enumitem.sty' not found.` when trying to use it, as also mentioned here: https://superuser.com/questions/1038612/where-do-i-get-the-pdflatex-program-for-mac#comment2305928_1416736)

[juancarlospaco]

I wonder if working on that is worth it, compared to just generating .epub,
epub is just HTML/CSS and docgen already does that, no JS,
then all the code for Latex can be removed, apps to view PDF can do EPUB too.

[timotheecour]

good question, I don't know; maybe @a-mr can comment on this?

• how would you generate epub via nim doc?
• ditto for tex?

epub to pdf

• it looks like calibre is the cmdline tool on osx (brew install calibre) and linux to generate pdf from epub;
  EDIT: i don't see an option to convert epub to pdf with calibre cmdline; but maybe pandoc can work: https://askubuntu.com/a/798129/602870

sudo apt install pandoc # on osx: `brew install pandoc`
pandoc -f epub -t pdf infile.epub -o outfile.pdf

EDIT: html to pdf via pandoc:

nim doc --outdir:/tmp/d05 --doccmd:skip lib/std/jsonutils.nim
pandoc /tmp/d05/jsonutils.html --pdf-engine /Library/TeX/texbin/pdflatex -t latex -o /tmp/d05/jsonutils.pdf

seems to work

use cases for doc2tex?

The question then is whether there still is a use case for nim doc2tex; we should look into quality of generated pdf's by both approaches (doc2tex is maybe more direct than html => pdf, ie less risk of getting lost in translation); maybe it's worth generating tex directly rather than pdf (say, to generate text instead of binary file), or to integrate with other tex/stf sources.

it would be nice if one could use nim sources for generating docs, slideshows, embed images, etc (and using the power of nim's macros for, say, generating tables, latex diagrams etc). A question is whether going via html can also do this too (or eventually do this too).

links

• https://stackoverflow.com/questions/44177555/how-to-convert-html-to-pdf-using-pandoc

latex and beamer (for latex slideshows)

see also options: --toc --chapters

[juancarlospaco]

But epub (AKA ebook) is al alternative format to PDF.
So you do not need to convert epub to PDF ideally.

is it mandatory to be specifically PDF?. Who is using PDF specifically ?.

I hate pandoc, because it installs gigabytes of Haskell libs and dependencies and the virtual machine.

[timotheecour]

so how do you convert html (generated by nim doc) to epub porgrammatically?

is it mandatory to be specifically PDF?. Who is using PDF specifically ?.

pdf is not dead, supporting it makes sense

I hate pandoc, because it installs gigabytes of Haskell libs and dependencies and the virtual machine.

on osx, brew install pandoc was fast (i forgot how fast though, and it could've been because i had some dependencies already installed, but, thanks to bottles i guess, that formula itself installed fast), but it does depend on presence of pdflatex, which can be slow to install (eg via mactex); how long does it take via apt?

[a-mr]

@juancarlospaco ,
I use pdf all the time — both for printing hardcopies on my printer and for reading on my e-ink e-book reader (where epub does not always work well unfortunately).

[juancarlospaco]

so how do you convert html to epub porgrammatically?

I can make it happen, but only if theres interest on merging that into stdlib or Fusion (or whatever is about to replace Fusion).

[timotheecour]

wait, there's no cmdline tool for that?

[juancarlospaco]

No but yeah, I mean is a Nim proc, you can add a cmdline, a rest api, or whatever way to use it. It must be a cmdline, why?.

[a-mr]

@timotheecour
first/second issue is the same bug, a lack of escaping :_ should escaped \_ in the title. It manifests itself also in rst files, e.g. try compiling something like nim rst2tex issue_16046.rst. I will fix it in the next PR.

[a-mr]

3. internal hyperlinks don't work because they are hard-coded as HTML links. Instead of providing workaround we should focus on implementing smart links simpler doc links: getFilePermissions <#getFilePermissions,string>_ => $getFilePermissions nim-lang/RFCs#125. I currently have a patch in my working copy which introduces usage of shared RST state in docgen for fixing rst: runnableExamples affects rst underline headings nim-lang/Nim#16990. Then it will be more convenient to go ahead with smart links.

[timotheecour]

Instead of providing workaround we should focus on implementing smart links nim-lang/RFCs#125.

ok, i agree

first/second issue is the same bug, a lack of escaping :_ should escaped _ in the title. It manifests itself also in rst files, e.g. try compiling something like nim rst2tex issue_16046.rst. I will fix it in the next PR.

sounds good; since it apparently also affects rst2tex, maybe that PR can be sent out independently, so as not to block on doc2tex?

[a-mr]

the styling could be improved, in particular, runnableExamples should maybe have a shaded background as for nim doc:

Shaded background would have been OK, but there is a problem with it in inline code: the line cannot be broken inside a shadow box in pdflatex & xelatex, it's a limitation of these traditional versions of Latex.

To not introduce inconsistency i decided in nim-lang#18141 to underline inline code and draw a frame around code blocks. Underlining is not perfect in Latex either but at least lines can be broken at spaces.