orgweb

Table of Contents

• How does it work?
• Installing
  • Docker
  • From Package
  • From Source
• Usage
  • Folder Structure
  • Tangle
  • Detangle
  • Execute
  • Monitor
• Tangling Workflows
• Contributions

orgweb is intended for developers that want to create literate programming project using Org-mode, but that does not want to investing time to learn how to use Emacs and Org-mode. If you are a developer that already uses Emacs and Org-mode, this tool is most likely not for you, but maybe for the people on your team that doesn't know, nor want to know, about Emacs.

orgweb is a very simple CLI tool that does the following:

• tangle one or multiple Org files
• detangle one or multiple source files
• execute one or multiple Org files
• monitor file changes on the file system to automatically tangle and detangle files that changes.

What is Literate Programming? Why?

If you wonder what a Literate Programming project looks like, just poke around this repository to have a glimps of the potential.

How does it work?

orgweb is designed in a way that developers can use all the power of Org-mode, in any IDE they like, without having to rely on Emacs directly.

To do that, it leverages Docker to build an image where Emacs is properly installed and configured to implement the commands that are exposed via the command line tool.

If the orgweb docker image is not currently existing in the environment, then it will request Docker to build the image using the Dockerfile. The build process will install and configure all the components required to implement all orgweb commands.

orgweb check if it exists every time it is invoked from the command line. This process will happen any time that the image is not available in the environment.

If the image is existing in the environment, then the following will happen.

orgweb will ask Docker to create a container based on the image. Once the container is running, it will execute a command on the container's terminal to run Emacs. Emacs is used directly from the command line by evaluating ELisp code it gets as input.

Every time a orgweb command line is executed, a new container is created:

Installing

Docker

If Docker is already installed in your development environment, you can skip this step. Otherwise, you should install Docker.

To install Docker Desktop, you simply have read and follow those instructions.

From Package

orgweb is available on PyPi, you can easily install it locally by running the following command in your terminal:

pip install orgweb

From Source

If you want to improve and contribute to the project, you will first have to generate the sources files from the Org mode files in the repository. To do so, you will need orgweb itself (installed in the previous step), or you could do the same if you have a local Emacs instance configured with org-mode. But let's assumes you don't.

First clone the repository in your environment:

git clone https://github.com/fgiasson/orgweb.git

Once the repository is cloned, let's tangle all the files:

cd orgweb
orgweb tangle .

These commands will tangle all the sources and configuration files required by the project.

Once they have been tangle, you will be able to use make to create the development environment and the package to run locally.

make create-venv          # create the pyenv virtual environment
make install-build        # install Python's build
source .venv/bin/activate # source that environment
make build                # build the orgweb CLI application
make install-local-build  # install the package we just created

After that, you will be able to run make rebuid-local every time you want to test some changes you made to the application.

Usage

Folder Structure

Each of the operation work with the same folder structure assumption. There are three main components:

• folder
• files

The folder is a where the files are located, within the project folder.

The files is a list of one or multiple files we want to tangle.

Tangle

orgweb tangle takes a folder as input. The folder is where the Org files we want to tangle are located. The operation is recursive, it will check in all subfolders of folder

Optionally, one or multiple files can be listed. Those files are located in folder, and those are the ones that will be tangled from that folder.

If no file is mentioned, then all the Org files from folder will be tangled.

cd /my/project/folder/
orgweb tangle . --file=foo.org --file=bar.org

In that example, orgweb will tangle the two files /my/project/folder/foo.org and /my/project/folder/bar.org

Detangle

orgweb detangle takes a folder as input. The folder is where the source files we want to detangle are located. The operation is recursive, it will check in all subfolders of folder

Optionally, one or multiple files can be listed. Those files are located in folder, and those are the ones that will be detangled from that folder.

If no file is mentioned, then all the Org files from folder will be detangled.

The detangle command does make sure that an input source file is a file that was previously tangled. Otherwise, it will be ignored. It does so by checking the tangling markup in comments of the source file.

cd /my/project/folder/
orgweb detangle . --file=foo.py --file=bar.py

In that example, orgweb will detangle the two files /my/project/folder/foo.py and /my/project/folder/bar.py

Execute

orgweb execute takes a folder as input. The folder is where the Org files we want to execute are located. The operation is recursive, it will check in all subfolders of folder

Optionally, one or multiple files can be listed. Those files are located in folder, and those are the ones that will be executed from that folder.

If no file is mentioned, then all the Org files from folder will be executed.

The execute command is used to execute every code block or the Org files. This is normally used to execute PlantUML code blocks such that it produces graphs that are referrenced within Org files.

cd /my/project/folder/
orgweb execute . --file=foo.org

In that example, orgweb will execute the /my/project/folder/foo.py

Monitor

orgweb monitor will take a folder as input and will monitor every file changes in that directory, recursively. If a Org file changes, it will be tangled, if a source file changes it will be detangled.

Monitoring is used to make sure that the Org files and their source files are always in sync, without having the developers to carefully tangle and detangle every time they modify a file.

cd /my/project/folder/
orgweb monitor .

Tangling Workflows

Let's take some time to cover the different tangling workflows that you may imagine.

The first scenario is when you have a single Org file that tangles code blocks in one, or multiple, source files, such as:

This is the workflow that is currently implemented in Org-mode. You can tangle a foo.org file in as many source files you want. Then, if you just detangle Foo.py, then only the code blocks with that code will be updated in Foo.org.

Then you could extrapolite this case and think about the following scenario:

This scenario is when you have two different Org files that tangle in the same source file. Then, when you detangle FooBar.py, you would imagine that each blocks would detangle in their respective Org file.

However, this is not currently the case with Org mode. This scenario is currently not supported and will break your literate programming workkflow.

Another thing to take care of is that the noweb syntax is not currently supported for the detangle command. This is a long standing issue with Org-mode that is discussed for several years now.

You can use noweb only if you won't detangle your source files.

Contributions

We welcome contributions to OrgWeb! If you’d like to contribute, please follow these steps:

• Fork the repository on GitHub.
• Create a new branch with a descriptive name: git checkout -b feature/your-feature-name
• Push your changes to your fork: git push origin feature/your-feature-name
• Make your changes and commit them: =git commit -m "Add feature: your feature name"​=
• Submit a pull request to the main branch of the original repository.
• Make sure that you only commit the Org-mode files, and not the source files themselves. Add them to the make clean method if needed.