Development.md

+# Development
+## Components
+The conversion from LaTeX to the XML ready for import takes 2 steps:
+
+1. convert from LaTeX to a single page HTML file
+1. split the HTML into parts and chapters and create the import XML
+
+
+### Conversion to HTML: *Laweb*
+*Laweb* uses *tex4ht* and consists of two configuration files. Their main purposes:
+
+- `laweb.cfg`: page properties, CSS definitions
+- `laweb.sty`: define LaTeX macros
+
+### Dissection and XML generation
+*laweb2pressbooks* is a Python program, hosted in a [separate repository](https://gitlab.ethz.ch/laweb/laweb2pressbooks). Adaptions have to be done in the code, there is no relevant configuration file.
+
+## Where to Change
+Fix issues and add features as early as possible in the pipeline: address *Laweb* first, then *laweb2pressbooks*.
+
+
+### New Features for LaTeX
+`laweb.sty` is probably the best choice. With `\ifdefined\HCode`, macros may detect if the document is processed for HTML output or not, and act accordingly. See the definition for for the *<details>* element [in the source](https://gitlab.ethz.ch/laweb/laweb/-/blob/master/laweb.sty#L64) as an example.
+
+### Post Processing
+The post processing with *laweb2pressbooks* should be reserved for tasks which cannot be done in Laweb. *laweb2pressbooks* has no knowledge about the LaTeX source and only sees HTML.
+
+Examples for tasks performed by *laweb2pressbooks* besides splitting up the parts:
+
+- fix line breaks written as `\n`
+- create links between newly created pages
+- remove comments
+- process images
+
+## Releases
+The distribution formats for *laweb2pressbooks* are Python package and Docker container. Both are versioned through Git tags. To release a new version, create a tag with description (not a lightweight tag without description). The build pipelines will create and publish new packages/containers automatically.