4 ms·

Books.jl: Create Books with Julia

59 points by UncleOxidant 5y ago

snicker7 5y ago
Built on top of pandoc and used to build the Julia Data Science book: https://juliadatascience.io/ https://juliadatascience.io/
Mageek 5y ago
The Tufte package also allows for typesetting a book with executable Julia code, only in LaTeX: https://github.com/sisl/tufte_algorithms_book https://github.com/sisl/tufte_algorithms_book It was used to make Algorithms for Optimization and Algorithms for Decision Making.
- huijzer 5y ago
  I thankfully used that repository to base the Books.jl template on indeed!
clircle 5y ago
Is this like Rmarkdown for Julia?
- rsfern 5y ago
  I think Weave.jl is a closer match for Rmarkdown. This project seems similar but geared more towards multi-chapter books instead of self-contained reports https://github.com/JunoLab/Weave.jl https://github.com/JunoLab/Weave.jl
- mbauman 5y ago
  That exists more directly with Weave.jl — this is built for bigger things. As the README says: > If you want a small report instead of a book with numbered sections, then Weave.jl might be more suitable for your problem. http://weavejl.mpastell.com/stable/ http://weavejl.mpastell.com/stable/
- Hasnep 5y ago
  It looks more like bookdown for Julia
- huijzer 5y ago
  Hi. Creator of the package here. It is indeed very much like Bookdown. However, there are a few specific problems that I have with Rmarkdown and similar systems (the foundation for Bookdown) that I wanted to solve: 1. Rmarkdown does not make it easy to write a book as a package. With a package, you get testing, dependency control and some more organizational things for free. 2. Rmarkdown and similar systems encapsulate your code in code blocks and require you to set metadata for each block. For the metadata, there is a kind of DSL with things like `show=TRUE`. I switched this around and just evaluate exactly what the user writes. This sort of "metadata" can be set via functions such as `sco` (show code and output). In combination with Julia's macro system, this even allows for grabbing function definitions from within the package with `@sco`. So, you can write a software package with a function `foo` and call `@sco foo(1)` so see the source code and output for calling `foo` with argument `1`. The benefit of avoiding the DSL is that users can be much more expressive in what they decide to do around their code blocks.
jtbayly 5y ago
Does not have search. I'm very interested in this space, but this is one of the core features I require to even look further at a project.
- huijzer 5y ago
  You're right. I should implement that. It's on the TODO list for a while already: https://github.com/JuliaBooks/Books.jl/issues/212 https://github.com/JuliaBooks/Books.jl/issues/212 Got any suggestions for a project for it?
  - jtbayly 5y ago
    If you can pre-build the index, Lunr seems to work well, but it doesn't support Chinese. R/bookdown switched for these reasons recently to fuse.js. There is discussion of some of the other options and their tradeoffs here: https://github.com/rstudio/bookdown/issues/1031 https://github.com/rstudio/bookdown/issues/1031

59 points by UncleOxidant 5y ago

Built on top of pandoc and used to build the Julia Data Science book: https://juliadatascience.io/ https://juliadatascience.io/

Mageek 5y ago

The Tufte package also allows for typesetting a book with executable Julia code, only in LaTeX: https://github.com/sisl/tufte_algorithms_book https://github.com/sisl/tufte_algorithms_book It was used to make Algorithms for Optimization and Algorithms for Decision Making.

huijzer 5y ago
I thankfully used that repository to base the Books.jl template on indeed!

clircle 5y ago

Is this like Rmarkdown for Julia?

rsfern 5y ago
I think Weave.jl is a closer match for Rmarkdown. This project seems similar but geared more towards multi-chapter books instead of self-contained reports https://github.com/JunoLab/Weave.jl https://github.com/JunoLab/Weave.jl
mbauman 5y ago
That exists more directly with Weave.jl — this is built for bigger things. As the README says: > If you want a small report instead of a book with numbered sections, then Weave.jl might be more suitable for your problem. http://weavejl.mpastell.com/stable/ http://weavejl.mpastell.com/stable/
Hasnep 5y ago
It looks more like bookdown for Julia
huijzer 5y ago
Hi. Creator of the package here. It is indeed very much like Bookdown. However, there are a few specific problems that I have with Rmarkdown and similar systems (the foundation for Bookdown) that I wanted to solve: 1. Rmarkdown does not make it easy to write a book as a package. With a package, you get testing, dependency control and some more organizational things for free. 2. Rmarkdown and similar systems encapsulate your code in code blocks and require you to set metadata for each block. For the metadata, there is a kind of DSL with things like `show=TRUE`. I switched this around and just evaluate exactly what the user writes. This sort of "metadata" can be set via functions such as `sco` (show code and output). In combination with Julia's macro system, this even allows for grabbing function definitions from within the package with `@sco`. So, you can write a software package with a function `foo` and call `@sco foo(1)` so see the source code and output for calling `foo` with argument `1`. The benefit of avoiding the DSL is that users can be much more expressive in what they decide to do around their code blocks.

jtbayly 5y ago

Does not have search. I'm very interested in this space, but this is one of the core features I require to even look further at a project.

huijzer 5y ago
You're right. I should implement that. It's on the TODO list for a while already: https://github.com/JuliaBooks/Books.jl/issues/212 https://github.com/JuliaBooks/Books.jl/issues/212 Got any suggestions for a project for it?
- jtbayly 5y ago
  If you can pre-build the index, Lunr seems to work well, but it doesn't support Chinese. R/bookdown switched for these reasons recently to fuse.js. There is discussion of some of the other options and their tradeoffs here: https://github.com/rstudio/bookdown/issues/1031 https://github.com/rstudio/bookdown/issues/1031