Skip to content

Latest commit

 

History

History
79 lines (56 loc) · 3.17 KB

DOCUMENTATION.adoc

File metadata and controls

79 lines (56 loc) · 3.17 KB

rdiff-backup: Documentation Guidelines

1. Text

We use Asciidoc as it’s more standardized than Markdown and richer, but still simple enough.

2. Graphics

We standardize on diagrams.net, formerly known as draw.io, so that we have one standard format, which everybody can edit and adapt for their own needs.

Note
 exception applies of course for pre-existing graphics (e.g. screenshots) as long as they can be kept in Git and edited with open source tools.

2.1. Why diagrams.net ?

We decided to use diagrams.net because:

  1. open source and freely available for anybody

  2. it has a graphical user interface, similar to most standard tools, like Visio, OpenDraw or LucidChart, which is important for acceptance

  3. easy to install under Linux or even no installation necessary thanks to online service

  4. the file can be kept in Git together with the rest of the documentation into Git without need to export/import

  5. embedded in a PNG or SVG, it can be shown by GitLab and easily embedded in asciidoc without need for any plugin, while still being editable (SVG would be a better choice for Git, but I noticed some issues with rendering, depending on the tool)

2.2. How to install draw.io?

The easiest way to use diagrams.net is to use the service at https://app.diagrams.net/.

You can also install draw.io locally:

  • using a FlatPak

  • using a Snap

  • if you have podman (or docker), it can easily be downloaded and used using a script like:

    #!/bin/sh
# a script to pull the draw.io / diagrams.net container image and run it in
# one's browser
# Use -p or --pull to force pulling a new version of the image

DRAWIO_STATUS=$(podman ps -a --filter name=drawio --noheading --format '{{.Status}}')
if [[ -z "${DRAWIO_STATUS}" ]]
then
	if [[ "$1" == "--pull" ]] || [[ "$1" == "-p" ]]
	then
		podman pull jgraph/drawio
	fi
	podman run --rm --name="drawio" --detach -p 8080:8080 -p 8443:8443 jgraph/drawio
	sleep 1
elif [[ ${DRAWIO_STATUS} == "Created" ]]
then
	podman restart drawio
	sleep 1
fi
xdg-open http://localhost:8080/?offline=1&https=0

  • and there are many ways to install diagrams.net, also on Mac and Windows (but we haven’t tried them all)

2.3. Format requirements

Make sure that you save your diagrams as "Editable Bitmap Image (.png)" or "Editable Vector Image (.svg) to Git, so that there is no issue with rendering.

People and tools will be able to see and show your diagram like any other image, but you’ll be able to edit it further. Keep the default .drawio.png/svg extension so that we can make the difference between editable and normal graphics.

Caution
 do save as, not export as PNG/SVG or you’ll get a normal graphic file. And be aware that only the first page of multi-page documents will be shown by standard tools unaware of draw.io.