To receive notifications about scheduled maintenance, please subscribe to the mailing-list gitlab-operations@sympa.ethz.ch. You can subscribe to the mailing-list at https://sympa.ethz.ch

Commit b25c134e authored by Bengt Giger's avatar Bengt Giger
Browse files

Structured documentation

parent 601a1547
Pipeline #96758 passed with stages
in 6 minutes and 53 seconds
# Docker Images
Images for containers are provided. They contain a LaTeX environment and the laweb
components.
The container needs to have access to your working directory, which has to be mounted into
the container. Example which creates and starts a container, and removes it at the of the job:
```
docker run --rm -v $(pwd):/home/workdir registry.ethz.ch/laweb/laweb:stable tex_source
```
Do not change the path `/home/workdir`! It's hardcoded into the image.
Replace `docker` with `podman` or whatever container runtime you want to use.
## Docker Setup with WSL
The Docker image works identically on Windows, if you use *Docker Desktop* and the
Windows subsystem for Linux. Make sure that `/mnt/c/Program Files/Docker/Docker/resources/bin`
has been added to your path. Then run `docker` as shown above.
# Installation
## Laweb: LaTeX to HTML Conversion
Copy the files
- `laweb`
- `laweb.sty`
- `laweb.cfg`
to the directory containing your LaTeX main file.
As dependencies, install the packages
- tex4ht
- tikz
and a comprehensive installation of LaTeX. I.e. on Fedora this will prepare the environment:
```
dnf install -y texlive-tikz-dependency texlive-tex4ht texlive-scheme-full texlive-ifluatex
```
If you have no customizable LaTeX environment, you may use the [Docker image](DOCKER.md)
## laweb2pressbooks: HTML to Wordpress XML Conversion
See [the instructions here](https://gitlab.ethz.ch/laweb/laweb2pressbooks).
# laweb
Wrapper for htlatex, with MathJax support.
Publish LaTeX documents in Pressbooks, a Wordpress plugin.
Docker build: [![pipeline status](https://gitlab.ethz.ch/laweb/laweb/badges/master/pipeline.svg)](https://gitlab.ethz.ch/laweb/laweb/-/commits/master)
This is a tool designed to transform a LaTeX source into a HTML file which
can be
......@@ -8,62 +11,42 @@ can be
In the background, it uses `tex4ht` for conversion.
*Laweb* is licensed under the *INSERT LICENSE HERE* license.
# Installation
Copy the files
- `laweb`
- `laweb.sty`
- `laweb.cfg`
to the directory containing your LaTeX main file.
As dependencies, install the packages
- tex4ht
- tikz
and a comprehensive installation of LaTeX. I.e. on Fedora this will prepare the environment:
```
dnf install -y texlive-tikz-dependency texlive-tex4ht texlive-scheme-full texlive-ifluatex
```
# Usage
In your preamble, add
```
\usepackage{laweb}
```
# Technical information
## Download and Installation
## Command Line
See [INSTALL](INSTALL.md) for installation information.
Issue
## Usage
```./laweb <BASENAME>```
See [USAGE](USAGE.md) for usage instructions.
Ommit the `.tex` suffix for `<BASENAME>`.
## Do Not Edit in Pressbooks
It is important to note that the content imported to Pressbooks **may not be edited in Pressbooks**. The editor(s) integrated in Pressbooks will destroy the HTML when saving modifications. The book has to be deleted and imported again to recover.
# Overview
*Laweb* combines the unmatched presentation of scientific documents with the publication abilities of Wordpress.
## Docker Image
## Why use Laweb?
While it is possible to simply convert a LaTeX document into HTML and put it on a static webserver, this approach
has some drawbacks:
Images for containers are provided. They contain a LaTeX environment and the laweb
components.
- Laweb uses MathML and Mathjax for the rendering of mathematical equiations, resulting in a near to optimum presentation in different browsers
- usually, a conversion to HTML ends up in a single HTML document. Think of a document consisting of hundreds of pages! Laweb splits parts and sections into single pages and creates the navigation structure for Pressbooks.
- Images are converted to inline data embedded in the HTML. Losing references to images is impossible.
- Laweb ensures that link references remain functional and consistent across split up pages.
The container needs to have access to your working directory, which has to be mounted into
the container. Example which creates and starts a container, and removes it at the of the job:
## Components
*Laweb* consists of two components:
```
podman run --rm -v $(pwd):/home/workdir registry.ethz.ch/laweb/laweb:stable tex_source
```
- *laweb*: LaTeX style and helper scripts to convert LaTeX source code to HTML
- *laweb2pressbooks*: Converter from HTML to Wordpress XML
Do not change the path `/home/workdir`!
The LaTeX styles add information required by the XML conversion. The resulting XML contains each LaTeX *part* and *section* separated, resulting in a structured Wordpress publication.
Replace `podman` with `docker` or whatever container runtime you want to use.
Additionally, a Pressbook template with the ability to disable the `wpautop` function in Wordpress is required. Otherwise, the rendering engine of Wordpress will eliminate vital parts of the HTML during rendering.
## Docker Setup with WSL
## Example
See ... for the result of a Laweb conversion.
Add `/mnt/c/Program Files/Docker/Docker/resources/bin` to your path.
# Usage
In your preamble, add
```
\usepackage{laweb}
```
## Command Line
Issue
```./laweb <BASENAME>```
Ommit the `.tex` suffix for `<BASENAME>`.
For the command line using Docker images see the [Docker instructions](DOCKER.md).
## laweb2pressbooks: HTML to Wordpress XML Conversion
See [the instructions here](https://gitlab.ethz.ch/laweb/laweb2pressbooks).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment