{"id":15050870,"url":"https://github.com/debian/debiman","last_synced_at":"2025-04-12T23:29:16.727Z","repository":{"id":15470239,"uuid":"78214277","full_name":"Debian/debiman","owner":"Debian","description":"debiman generates a static manpage HTML repository out of a Debian archive","archived":false,"fork":false,"pushed_at":"2025-03-13T07:35:17.000Z","size":2403,"stargazers_count":205,"open_issues_count":56,"forks_count":50,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-04-05T22:03:16.028Z","etag":null,"topics":["debian","manpages"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Debian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-06T14:58:51.000Z","updated_at":"2025-03-30T14:30:13.000Z","dependencies_parsed_at":"2025-04-05T22:13:11.418Z","dependency_job_id":null,"html_url":"https://github.com/Debian/debiman","commit_stats":{"total_commits":279,"total_committers":11,"mean_commits":"25.363636363636363","dds":"0.043010752688172005","last_synced_commit":"ba9e96f0f6b083158bbb4929b937c5e62ea8f8c2"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Debian%2Fdebiman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Debian%2Fdebiman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Debian%2Fdebiman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Debian%2Fdebiman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Debian","download_url":"https://codeload.github.com/Debian/debiman/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248646889,"owners_count":21139079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debian","manpages"],"created_at":"2024-09-24T21:29:33.497Z","updated_at":"2025-04-12T23:29:16.705Z","avatar_url":"https://github.com/Debian.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# debiman\n\n[![Actions workflow](https://github.com/Debian/debiman/actions/workflows/main.yml/badge.svg)](https://github.com/Debian/debiman/actions/workflows/main.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Debian/debiman)](https://goreportcard.com/report/github.com/Debian/debiman)\n\n\u003cimg src=\"https://debian.github.io/debiman/debiman-logo.svg\" width=\"300\" height=\"280\" align=\"right\" alt=\"debiman logo\"\u003e\n\n## Goals\n\ndebiman makes (Debian) manpages accessible in a web browser. Its goals are, in order:\n\n1. **completeness**: all manpages in Debian should be available.\n2. **visually appealing** and **convenient**: reading manpages should be fun, convenience features (e.g. permalinks, URL redirects, easy navigation) should be available\n3. **speed**: manpages should be quick to load, new manpages should be quickly ingested, the program should run quickly for pleasant development\n\nCurrently, there is one known bug with regards to completeness ([#12](https://github.com/Debian/debiman/issues/12)).\n\nWith regards to speed, debiman can process all manpages of Debian unstable in **less than 10 minutes** on a modern machine. Incremental updates complete in **less than 15 seconds**. For more details, see [PERFORMANCE.md](https://github.com/Debian/debiman/blob/master/PERFORMANCE.md).\n\n## Prerequisites\n\n* mandoc\n* a local or remote Debian mirror or an apt-cacher-ng running on localhost:3142\n* a number of Go packages (which `go get` will automatically get for you, see below)\n    * pault.ag/go/debian\n    * pault.ag/go/archive\n    * github.com/golang/protobuf/proto\n    * golang.org/x/crypto/openpgp\n    * golang.org/x/net/html\n    * golang.org/x/sync/errgroup\n    * golang.org/x/text\n\n## Architecture overview\n\ndebiman works in 4 stages:\n\n1. All Debian packages of all architectures of the specified suites are discovered. The following optimizations are used to reduce the number of packages, and hence the input size/required bandwidth:\n    1. packages which do not own any files in /usr/share/man (as per the Contents-\u003carch\u003e archive files) are skipped.\n    2. each package is downloaded only for 1 of its architectures, as manpages are architecture-independent.\n2. Man pages and auxiliary files (e.g. content fragment files which are included by a number of manpages) are extracted from the identified Debian packages.\n3. All man pages are rendered into an HTML representation using mandoc(1).\n4. An index file for debiman-auxserver (which serves redirects) is written.\n\nEach stage runs concurrently (e.g. Contents and Packages files are\ninspected concurrently), but only one stage runs at a time,\ne.g. extraction needs to complete before rendering can start.\n\n## Development quick start\n\n### Set up Go\n\nInstall the latest supported version of Go from https://go.dev/dl. If you prefer\nto install Go from Debian, ensure you get the same version — if you use Debian\nstable, you likely need to install from backports.\n\n### Install debiman\n\nTo download, compile and install debiman to `~/go/bin`, run:\n```\ngo install github.com/Debian/debiman/cmd/...@main\n```\n\n### Run debiman\n\nTo synchronize Debian testing to ~/man and render a handful of packages, run:\n```\n~/go/bin/debiman -serving_dir=~/man -only_render_pkgs=qelectrotech,i3-wm,cron\n```\n\n### Test the output\n\nTo serve manpages from ~/man on localhost:8089, run:\n```\n~/go/bin/debiman-minisrv -serving_dir=~/man\n```\n\nNote that for a production setup, you should not use debiman-minisrv. Instead,\nrefer to the web server example configuration files in example/.\n\n### Recompile debiman\n\nTo update your debiman installation after making changes to the HTML\ntemplates or code in your `debiman` git working directory, run:\n```\ngo generate github.com/Debian/debiman/...\ngo install github.com/Debian/debiman/cmd/...\n```\n\n## Synchronizing\n\nFor https://manpages.debian.org, we run:\n\n```\nflock /srv/manpages.debian.org/debiman/exclusive.lock \\\nnice -n 5 \\\nionice -n 7 \\\ndebiman \\\n  -sync_codenames=oldstable,oldstable-backports,stable,stable-backports \\\n  -sync_suites=testing,unstable,experimental \\\n  -serving_dir=/srv/manpages.debian.org/www \\\n  -local_mirror=/srv/mirrors/debian\n```\n    \n…resulting in the directories wheezy/, wheezy-backports/, jessie/, jessie-backports/, testing/, unstable/ and experimental/ (respectively).\n\nNote that you will *NOT* need to change this command line when a new version of Debian is released.\n\nWhen interrupted, you can just run debiman again with the same options. It will resume where it left off.\n\nIf for some reason you notice corruption or other mistakes in some manpages, just delete the directory in which they are placed, then re-run debiman to download and re-process these pages from scratch.\n\nIt is safe to run debiman while you are serving from `-serving_dir`. debiman will swap files atomically using [rename(2)](https://manpages.debian.org/rename(2)).\n\n## Customization\n\nYou can copy the `assets/` directory, modify its contents and start\ndebiman with `-inject_assets` pointed to your directory. Any files whose\nname does not end in .tmpl are treated as static files and will be\nplaced in -serving_dir (compressed and uncompressed).\n\nThere are a few requirements for the templates, so that debiman can\nre-use rendered manpages (for symlinked manpages):\n\n1. In `assets/manpage.tmpl` and `assets/manpageerror.tmpl`, the string `\u003ca\n   class=\"toclink\"` is used to find table of content links.\n2. `\u003c/div\u003e\\n\u003c/div\u003e\\n\u003cdiv id=\"footer\"\u003e` is used to delimit the mandoc output\n   from the rest of the page.\n\n## interesting test cases\n\n[crontab(5)](https://manpages.debian.org/crontab(5)) is present in multiple Debian versions, multiple languages, multiple sections and multiple conflicting packages. Hence, it showcases all debiman features.\n\n[w3m(1)](https://manpages.debian.org/w3m(1)) has a Japanese translation which is only present in UTF-8 starting with Debian jessie. It also has a German translation starting with Debian stretch.\n\n[qelectrotech(1)](https://manpages.debian.org/qelectrotech(1)) has a French translation in 3 different encodings (none specified, ISO8859-1, UTF-8).\n\n[mysqld(8)](https://manpages.debian.org/mysqld(8)) is present in two conflicting packages: `mariadb-server-core-10.0` and `mysql-server-core-5.6`.\n\n## recommended reading\n\nhttps://wiki.debian.org/RepositoryFormat\n\n## URLs\n\nThe URL schema which debiman uses is `(\u003csuite\u003e/)(\u003cbinarypkg/\u003e)\u003cname\u003e(.\u003csection\u003e(.\u003clang\u003e))`. Any part aside from `name` can be omitted; here are a few examples:\n\nWithout suite and binary package:\n\n1. https://manpages.debian.org/i3\n2. https://manpages.debian.org/i3.fr\n3. https://manpages.debian.org/i3.1\n4. https://manpages.debian.org/i3.1.fr\n\nWith binary package:\n\n1. https://manpages.debian.org/i3-wm/i3\n2. https://manpages.debian.org/i3-wm/i3.fr\n3. https://manpages.debian.org/i3-wm/i3.1\n4. https://manpages.debian.org/i3-wm/i3.1.fr\n\nWith suite:\n\n1. https://manpages.debian.org/testing/i3\n2. https://manpages.debian.org/testing/i3.fr\n3. https://manpages.debian.org/testing/i3.1\n4. https://manpages.debian.org/testing/i3.1.fr\n\nWith suite and binary package:\n\n1. https://manpages.debian.org/testing/i3-wm/i3\n2. https://manpages.debian.org/testing/i3-wm/i3.fr\n3. https://manpages.debian.org/testing/i3-wm/i3.1\n4. https://manpages.debian.org/testing/i3-wm/i3.1.fr\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebian%2Fdebiman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdebian%2Fdebiman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebian%2Fdebiman/lists"}